 |
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/.
There are two fields in the RIB that you can use to determine whether
any RIBEs were not returned: - RIBTRIBE contains the total number of RIBEs associated with this
RIB
- RIBNRIBE contains the total number of RIBEs returned by GQSCAN
with this RIB in the user-specified area indicated by the AREA parameter.
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.
Environment
The requirements for the caller are:
| Environmental factor |
Requirement |
|---|
| Minimum authorization: |
Problem state with any PSW key. |
| 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. |
Programming requirements
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.
Input register information
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.
Output register information
When control returns to the caller, the GPRs contain: - Register
- Contents
- 0
- Register 0 contains a fullword reason code if the return code
in register 15 is X'0A' or X'0C'. Otherwise, register
0 contains the following two halfword values:
- The first (high-order) halfword contains the length of the fixed
portion of each RIB returned.
- The second (low-order) halfword contains the length of each RIBE
returned or reason code.
- 1
- Contains the number of RIBs that were copied into the area provided
- 2-13
- Unchanged
- 14
- Used as a work register by the system
- 15
- Return code
When control returns to the caller, the ARs contain: - Register
- Contents
- 0-1
- Used as work registers by the system
- 2-13
- Unchanged
- 14-15
- Used as work registers by the system
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.
Performance implications
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.
None.
Syntax
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 |
|
| |
|
| ,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.
|
| |
|
Parameters
The parameters are explained as follows:
- AREA=(area addr,area size)
- Specifies the location and size of the area where information
extracted from the global resource serialization resource queues is
to be placed. The minimum size is the amount needed to describe a
single resource, which is the length of the fixed portions of the
RIB and the maximum size rname rounded up to a fullword value. IBM
recommends that you use a minimum of 1024 bytes as the area size.
- ,REQLIM=value
- ,REQLIM=MAX
- Specifies the maximum number of owners and waiters to be returned
for each individual resource within the specification of RESNAME,
which can be any value between 0 and 215-1.
MAX specifies 215-1 (32767).
- ,SCOPE=ALL
- ,SCOPE=STEP
- ,SCOPE=SYSTEM
- ,SCOPE=SYSTEMS
- Specifies that you want information only for resources having
the indicated scope. STEP, SYSTEM, or SYSTEMS is the scope specified
on the resource request. If you specify SCOPE=ALL (meaning STEP,
SYSTEM, and SYSTEMS), the system returns information for all resources
the system recognizes that have the specified RESNAME, RESERVE, or
SYSNAME characteristics.
- ,RESERVE=YES
- ,RESERVE=NO
- If you specify RESERVE=YES, information is only returned for the
requestors of the resource, that requested the resource with the RESERVE
macro. If, for example, the resource also had requestors with the
ENQ macro, the ENQ requestor's information would not be returned for
the resource.
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=(qname addr[,rname addr,rname
- length],[GENERIC|SPECIFIC], qname length)
- RESNAME identifies an individual resource or group of resources
that GQSCAN will examine.
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). 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.
Note: GENERIC and SPECIFIC are mutually exclusive.
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.
- ,SYSNAME=(sysname addr [,asid value])
- Specify SYSNAME to tell GQSCAN to return information for resources
requested by tasks running on the MVS system specified in an 8-byte
field pointed to by the address in sysname address and
the asid value, a 4-byte address space identifier,
right justified. Valid SYSNAMEs are specified in the IEASYSxx parmlib
member.
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.
- ,QUIT=YES
- ,QUIT=NO
- QUIT=NO indicates that you do not want to end the current global
resource serialization queue scan. QUIT=YES tells GQSCAN to stop processing
the current global resource serialization queue scan and release the
storage allocated to accumulate the information specified in the token.
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'.
- ,REQCNT=rcount
- Specifies that you want GQSCAN to return resource information
only when the total number of requesters (owners plus waiters) for
an individual resource is greater than or equal to rcount,
which can be any value between 0 and 231-1.
- ,OWNERCT=ocount
- Specifies that you want GQSCAN to return resource information
only when the total number of owners for an individual resource is
greater than or equal to ocount, which can be any
value between 0 and 231-1.
- ,WAITCNT=wcount
- Specifies that you want GQSCAN to return resource information
only when the total number of waiters for an individual resource is
greater than or equal to wcount, which can be any
value between 0 and 231-1.
- OWNERCT=ocount,WAITCNT=wcount
- Specifies that you want GQSCAN to return resource information
only when the total number of owners for an individual resource is
greater than or equal to ocount or when the total
number of waiters for an individual resource is greater than or equal
to wcount.
- ,TOKEN=addr
- Specifies the address of a fullword of storage that the GQSCAN
service routine can use to provide you with any remaining information
in subsequent invocations. If the token value is zero, the scan starts
at the beginning of the resource queue. If the token value is not
zero, the scan resumes at the point specified on TOKEN. Specify the
same token value that GQSCAN returned on its previous invocation to
continue where processing left off on the previous invocation.
When
providing a non-zero token value, you must specify the same scope
that you specified on the GQSCAN request that returned the token.
- ,XSYS=YES
- ,XSYS=NO
- Specifies whether GQSCAN should be propagated across systems in
the global resource serialization complex, to gather complex-wide
information. This parameter is ignored in a global resource serialization
ring complex, and for requests that only gather local data.
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.
Return and reason codes
When GQSCAN returns control, register 15 contains one of the following
return codes:
Table 1. Return Codes for the
GQSCAN Macro| 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. - Reason Code
- Meaning
- 04
- The caller attempted to use GQSCAN before the global resource
serialization (GRS) address space was active.
- 08
- The size of the reply area, specified by the AREA parameter, is
too small to contain a resource information block (RIB) of maximum
size.
- 0C
- You specified mutually exclusive arguments (RESERVE=YES, RESERVE=NO,
RESNAME=, SYSNAME=, or XSYS=NO) to GQSCAN.
- 10
- The caller was holding a local lock other than the GRS local lock
when GQSCAN was invoked.
- 14
- One of the following conditions, in reference to the RESNAME parameter,
was detected by GQSCAN:
- The qname length was specified with a value
greater than eight.
- The qname length value was specified without
the qname addr value.
- The SPECIFIC parameter was specified with a rname length value
of zero.
- The rname or rname length was
specified without the qname addr value.
- 18
- The asid value, for the SYSNAME parameter was
specified without the sysname addr value.
- 1C
- The REQCNT parameter was specified with either the OWNERCNT or
WAITCNT parameters.
- 20
- The combination of values specified on the SCOPE parameter is
not valid.
- 28
- An element in GQSCAN's input parameter list was not in the caller's
storage protect key.
- 2C
- An invalid token was specified to GQSCAN.
- 30
- The GQSCAN caller is not authorized to use the restricted interface
(SCOPE=LOCAL or GLOBAL).
- 34
- QUIT=YES was specified without the TOKEN parameter.
- 38
- The caller held a CMS lock other than CMSEQDQ when GQSCAN was
invoked.
- 3C
- The caller held a lock that violated the environmental restrictions
of a service required by GQSCAN.
- 40
- The caller invoked GQSCAN in the service request block (SRB) mode.
- 44
- The value specified for the REQLIM parameter was not valid.
- 48
- The value specified for the REQCNT parameter was not valid.
- 4C
- The value specified for the OWNERCT parameter was not valid.
- 50
- The value specified for the WAITCNT parameter was not valid.
- 58
- SETROPTS MLACTIVE is in effect, and the program is not authorized
to issue GQSCAN. Ensure the program is running authorized, or is associated
with a userid with at least READ access to the best fit FACILITY
class resource profile of the form ISG.QSCANSERVICES.AUTHORIZATION
and that the FACILITY class is SETROPTS RACLISTed.
|
| 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: - Reason Code
- Meaning
- 00
- GQSCAN has sustained an unrecoverable error.
- 04
- The GQSCAN caller attempted to resume a scan that was started
when the global resource serialization complex, which is now in star
mode, was in ring mode.
- 08
- The GQSCAN service is not able to obtain storage to satisfy the
request.
- 0C
- Sysplex processing of a SYSTEMS or GLOBAL request failed.
- 10
- The GQSCAN service failed because the complex was migrating from
a ring to a star configuration.
- 14
- The GQSCAN service failed because inconsistent data was returned
from one or more systems.
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.
|
|
z/OS MVS Programming: Assembler Services Reference ABE-HSP
Copyright IBM Corporation 1990, 2014