Use the GQSCAN macro to obtain the status of resources and requestors of those resources. The GQSCAN macro allows you to obtain resource information from the system.
ISGQUERY is the IBM recommended replacement for the GQSCAN service.
The ISGRIB macro allows you to interpret the data that the GQSCAN service routine returns to the user-specified area. The ISGRIB macro maps the resource information block (RIB) and the resource information block extent (RIBE) as shown in z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/.
Global resource serialization counts and limits the number of outstanding global resource serialization requests. A global resource serialization request is any ENQ, RESERVE, or GQSCAN that causes an element to be inserted into a queue in the global resource serialization request queue area. See “Limiting global resource serialization requests” in “Chapter 4: Serialization” in z/OS MVS Programming: Authorized Assembler Services Guide.
The requirements for the caller are:
Environmental factor | Requirement |
---|---|
Minimum authorization: | Problem state with any PSW key. For the SCOPE=GLOBAL and SCOPE=LOCAL parameters, supervisor state. |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN=HASN=SASN or PASN¬=HASN¬=SASN |
Any PASN, any HASN, any SASN | |
AMODE: | 24- or 31-bit |
ASC mode: | Primary |
Interrupt status: | Enabled for I/O and external interrupts |
Locks: | No locks held |
Control parameters: | Control parameters must be in the primary address space. |
To interpret the data that the GQSCAN service routine returns in the user-specified area, you must include the ISGRIB mapping macro as a DSECT in your program.
Unauthorized callers of GQSCAN need to be authorized through Security Authorization Facility (SAF) when Multi-level security (MLS) is active. If the caller is not authorized, the request will fail.
When multilevel security support is active on the system, unauthorized callers of ISGQUERY who specify REQINFO=QSCAN must have at least READ authorization to the ISG.QSCANSERVICES.AUTHORIZATION resource in the FACILITY class. You can activate the multilevel security support through the SETROPTS MLACTIVE option in RACF. For general information about defining profiles in the FACILITY class, see z/OS Security Server RACF Command Language Reference and z/OS Security Server RACF Security Administrator's Guide. For information about multilevel security, see z/OS Planning for Multilevel Security and the Common Criteria.
Before issuing the GQSCAN macro, the caller does not have to place any information into any general purpose register (GPR) or access register (AR) unless using it in register notation for a particular parameter, or using it as a base register.
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
In general, the narrower the search parameters (particularly QNAME and RNAME), the less time it takes. Using both a specific QNAME and a specific RNAME gives better performance than using generic prefix.
The use of XSYS=YES (the default) might greatly degrade the performance of the request. Use it only when required.
Polling for ENQ contention through GQSCAN or ISGQUERY is not recommended. See the z/OS MVS Planning: Global Resource Serialization and z/OS MVS Programming: Authorized Assembler Services Guide for more information about monitoring contention through ENF 51.
When you specify SCOPE=GLOBAL, or SCOPE=LOCAL, the performance of programs that issue ENQ, DEQ, or the RESERVE macro might be temporarily degraded while the GQSCAN service is running.
The standard form of the GQSCAN macro is written as follows:
Syntax | Description |
---|---|
name | name: symbol. Begin name in column 1. |
␢ | One or more blanks must precede GQSCAN. |
GQSCAN | |
␢ | One or more blanks must follow GQSCAN. |
AREA=(area addr,area size) | area addr: A-type address or register (2) - (12). |
area size: symbol, decimal
digit, or register (2) - (12). Note: AREA cannot be specified with
QUIT=YES.
|
|
,REQLIM=value | value: symbol, decimal digit, register (2) - (12), or the word MAX. |
,REQLIM=MAX | Default: REQLIM=MAX |
,SCOPE=ALL | Default: SCOPE=STEP |
,SCOPE=STEP | |
,SCOPE=SYSTEM | |
,SCOPE=SYSTEMS | |
,SCOPE=LOCAL | |
,SCOPE=GLOBAL | |
,RESERVE=YES | Default: All resources requested with RESERVE and all |
,RESERVE=NO | resources requested with ENQ. |
,RESNAME=(qname | qname addr: RX-type address or register (2) - (12). |
addr[,rname addr, | rname addr: RX-type address or register (2) - (12). |
rname length], | rname length: decimal digit, or register (2) - (12). |
[GENERIC|SPECIFIC], | Default: assembled length of rname. |
qname length) | Default: qname length of eight. |
,SYSNAME=(sysname addr | sysname addr: RX-type address or register (2) - (12). |
[,asid value]) | asid value: symbol, decimal
digit, or register (2) - (12). Note: Provide rname addr only
when qname addr is used. Code rname length if
a register is specified for rname addr. Code an asid
value only when the sysname addr is used.
|
,QUIT=YES | Default: QUIT=NO |
,QUIT=NO | Note: QUIT=YES is mutually exclusive with all
parameters but TOKEN and MF.
|
,REQCNT=value | value: decimal digit or register (2) - (12). |
Default: REQCNT=0 | |
,OWNERCT=value,WAITCNT= | |
value | value: decimal digit or register (2) - (12). |
,OWNERCT=value | value: decimal digit or register (2) - (12). |
,WAITCNT=value | value: decimal digit or register (2) - (12). |
,TOKEN=addr | addr: RX-type address or register (2) - (12). |
,XSYS=YES | Default: XSYS=YES |
,XSYS=NO | Note: XSYS=NO is mutually exclusive with TOKEN,
QUIT=YES and SYSNAME, when SYSNAME is not equal to zero or zero and
the asid value(0,asid value). In a global resource serialization ring
complex, XSYS=NO is ignored.
|
The parameters are explained as follows:
RESERVE=NO information is only returned for the requestors of the resource that requested the resource with the ENQ macro. In other words, if the resource also had requestors with the RESERVE macro, the RESERVE requestor's information would not be returned for the resource.
RESNAME with (rname) indicates the name of one resource.
The qname addr specifies the address of the 8-character major name of the requested resource.
The rname addr specifies the virtual storage address of a 1 to 255-byte minor name used with the major name to represent a single resource. Information returned is for a single resource unless you specify SCOPE=ALL, in which case it could be for three resources (STEP, SYSTEM, and SYSTEMS) or SCOPE=LOCAL in which case it could be for two resources (STEP and SYSTEM) if there is a matching name in each of these categories. If the name specified by rname is defined by an EQU assembler instruction, the rname length must be specified.
The rname length specifies the length of the minor name. If you use the register form, specify length in the low-order (rightmost) byte. The length must match the rname length specified on ENQ or RESERVE.
GENERIC specifies that the rname of the requested resource must match but only for the length specified. For example, an ENQ for SYS1.PROCLIB would match the GQSCAN rname specified as SYS1 for an rname length of 4.
SPECIFIC specifies that the rname of the requested resource must exactly match the GQSCAN rname.
The qname length specifies the number of characters in a resource qname that must match the GQSCAN qname specified by RESNAME. You must specify a qname length to request a GQSCAN for a generic qname. For example, an ENQ with a qname of SYSDSN would match a GQSCAN specifying GENERIC with a qname of SYSD and qname length of 4. Specify zero for the qname length (with any qname) to request a generic GQSCAN matching any resource qname. If you do not specify a qname length, GQSCAN uses the default of 8.
Information returned includes only those resources whose sysname addr and asid value match the ones specified. SYSNAME=0 or SYSNAME=(0,asid value), specifies that the system name is that of the system on which GQSCAN is issued. The system issues return code X'0A' with a reason code of X'0C', if SYSNAME≠0 or SYSNAME≠(0,asid value) is specified with XSYS=NO.
If you specify QUIT=YES, you must specify the TOKEN parameter. If you specify QUIT=YES without the TOKEN parameter, the system issues abend X'09A'.
If you specify QUIT=YES without the TOKEN parameter, the system issues return code X'0A' with a reason code of X'34'. Specifying QUIT=YES with TOKEN=0 will result in the system issuing return code X'0A' with a reason code of X'2C'.
If you specify QUIT=YES with a token that was previously obtained through GQSCAN with SCOPE=LOCAL or SCOPE=GLOBAL, your program must be in supervisor state when it issues GQSCAN with QUIT=YES.
If you specify QUIT=YES with XSYS=NO, the system issues return code X'0A' with a reason code of X'0C'.
When providing a non-zero token value, you must specify the same scope that you specified on the GQSCAN request that returned the token.
Specify XSYS=YES if the program requires complex-wide global resource serialization information. The caller might be suspended while the information is being gathered. Do not specify or default to XSYS=YES if this condition cannot be tolerated.
Specify XSYS=NO if the program will accept global resource serialization information from this system only. The RIBE data will contain information about requestors from other other systems in the complex only if that information is already available on the GQSCAN caller's system. Otherwise, RIBE data will be provided only for requests from the GQSCAN caller's system, and the counts in the RIB will reflect only those requests. This request is always handled without placing the caller's dispatchable unit into a wait.
See z/OS MVS System Codes for more information about the abend codes.
When GQSCAN returns control, register 15 contains one of the following return codes:
Hexadecimal Return Code | Meaning and Action |
---|---|
0 | Meaning: Queue scan processing is complete.
Data is now in the area you specified. There is no more data to return. Action: Process the data. |
4 | Meaning: Queue scan processing is complete.
No resources matched your request. Action: Do not try to process any data; none exists. |
8 | Meaning: The area you specified was filled
before queue scan processing completed. Action: If you specified TOKEN, process the information in the area and issue GQSCAN again, specifying the TOKEN returned to you. If you did not specify TOKEN, specify a larger area or specify a TOKEN. |
0A | Meaning: The information you specified to GQSCAN is not valid. Action: Take the action indicated
by the following hexadecimal reason code found in register 0.
|
0C | Meaning: System error. Queue scan encountered
an abnormal situation while processing. The information in your area
is not meaningful. The reason code in register 0 contains one of
the following:
Action: Do not try to process any data; none exists. Retry the request one or more times. |
10 | Meaning: Program error. An incorrect SYSNAME
was specified as input to queue scan. The information in your area
is not meaningful. Action: Specify a valid SYSNAME on the call to GQSCAN. |
14 | Meaning: Environmental error. The area
you specified was filled before queue scan processing completed. Your
request specified TOKEN, but the limit for the number of concurrent
resource requests (ENQ, RESERVE, or GQSCAN) has been reached. The
information in your area is valid but incomplete. The scan cannot
be resumed. Action: Retry the request one or more times. If the problem persists, consult your system programmer, who might be able to tune the system so that the limit is no longer exceeded. |