ISGQUERY — Global resource serialization query service

Description

The GRS query service routine is given control from the ISGQUERY macro to:

Search a resource name list (RNL) for a given QNAME/RNAME pair.
Obtain information on resources and requesters of outstanding ENQ requests.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state. Any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	31- or 64-bit If in AMODE 64, specify SYSSTATE AMODE64=YES before invoking this macro.
ASC mode:	Primary or access register (AR) If in Access Register ASC mode, specify SYSSTATE ASCENV=AR before invoking this macro.
Interrupt status:	Enabled for I/O and external interrupts
Locks:	For REQINFO=RNLSEARCH, the caller may be unlocked or hold both a local lock (LOCAL or CML) and the CMSEQDQ lock. For all other REQINFO requests, the caller must not hold any locks.
Control parameters:	Control parameters must be in the primary address space or, for AR-mode callers, must be in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL). The control parameters must be in the same key as the caller. The user-provided answer area via the ANSAREA parameter has the same requirements and restrictions as the control parameters.

Programming requirements

The caller must include the ISGYQUAC macro to get a mapping for the answer area.

Note: The ISGYQUAA macro is stabilized as of z/OS R12.

The caller must include the ISGYCON macro to get the values for the return and reason codes.

The caller must include the ISGRNLE macro to get a mapping for the RNLE.

Restrictions

Do not issue ISGQUERY before the GRS address space has been initialized.

There is a restriction on the number of concurrent resource requests in an address space. These include unauthorized ISGENQ, ENQ, RESERVE, and incomplete GQSCAN and ISGQUERY requests. Reason code ISGQUERYRsn_MaxConcurrentRequests is issued if ISGQUERY would cause this limit to be exceeded.

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. When multilevel security support is active on the system, unauthorized callers of ISGQUERY who specify REQINFO=LATCHECA must have at least READ authorization to the ISG.LATCHECASERVICES.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.

Callers who specify REQINFO=LATCHECA must not hold any FRRs.

This macro supports multiple versions. Some keywords are unique to certain versions. For more information, see the description of the ,PLISTVER=IMPLIED_VERSION parameter and the common criteria.

Input register information

Before issuing the ISGQUERY 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: Reason code if GPR15 is not 0
1: Used as a work register by the system
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 the query takes. Using both a specific QNAME and a specific RNAME gives better performance than using patterns.

The use of GATHERFROM=SYSPLEX might greatly degrade the performance of the query request.

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.

Syntax


main diagram

>>-+------+--b--ISGQUERY--b------------------------------------->
   '-name-'                   

>--+-REQINFO--=--RNLSEARCH--|  |------------------------------------------+-->
   +-REQINFO--=--ENQSTATS--,--ASID--=--asid--,--ANSAREA--=--ansarea-------+   
   +-REQINFO--=--QSCAN--|  |----------------------------------------------+   
   +-REQINFO--=--LATCHECA--|  |-------------------------------------------+   
   '-REQINFO--=--USAGESTATS--,--ANSAREA--=--ansarea--,--ANSLEN--=--anslen-'   

>--+------------------------+--+------------------------+------->
   '-,--RETCODE--=--retcode-'  '-,--RSNCODE--=--rsncode-'   

   .-,--PLISTVER--=--IMPLIED_VERSION-.   
>--+---------------------------------+-------------------------->
   +-,--PLISTVER--=--MAX-------------+   
   +-,--PLISTVER--=--1---------------+   
   '-,--PLISTVER--=--2---------------'   

   .-,--MF--=--S--------------------------------------.   
>--+--------------------------------------------------+--------><
   |                               .-,--0D---.        |   
   +-,--MF--=--(--L--,--list addr--+---------+--)-----+   
   |                               '-,--attr-'        |   
   |                               .-,--COMPLETE-.    |   
   '-,--MF--=--(--E--,--list addr--+-------------+--)-'


parameters-1

>>-+-,--RNL--=--SIRNL-+--,--QNAME--=--qname--------------------->
   +-,--RNL--=--SERNL-+                       
   '-,--RNL--=--RCRNL-'                       

>--,--RNAME--=--rname--,--RNAMELEN--=--rnamelen----------------->

>--+------------------+----------------------------------------><
   '-,--RNLE--=--rnle-'


parameters-2

>>-+-,--SCANACTION--=--START--|  |--------------------------------------------------------------------------+-><
   +-,--SCANACTION--=--RESUME--,--RESUMETOKEN--=--resumetoken--,--ANSAREA--=--ansarea--,--ANSLEN--=--anslen-+   
   '-,--SCANACTION--=--QUIT--,--RESUMETOKEN--=--resumetoken-------------------------------------------------'


parameters-3

>>-+--------------------------------+--,--ANSAREA--=--ansarea--->
   '-,--RESUMETOKEN--=--resumetoken-'                           

                         .-,--ANSDETAIL--=--SUMMARY-.   
>--,--ANSLEN--=--anslen--+--------------------------+----------->
                         +-,--ANSDETAIL--=--FULL----+   
                         +-,--ANSDETAIL--=--FULL2---+   
                         '-,--ANSDETAIL--=--FULL3---'   

   .-,--GATHERFROM--=--SYSTEM--.   
>--+---------------------------+-------------------------------->
   '-,--GATHERFROM--=--SYSPLEX-'   

   .-,--REQUESTERLIMIT--=--32767----------.   
>--+--------------------------------------+--------------------->
   '-,--REQUESTERLIMIT--=--requesterlimit-'   

>--+-,--SEARCH--=--BY_ENQTOKEN--,--ENQTOKEN--=--enqtoken-+-----><
   '-,--SEARCH--=--BY_FILTER--|  |-----------------------'


parameters-4

>>-+-,--QNAMEMATCH--=--SPECIFIC--,--QNAME--=--qname-+----------->
   '-,--QNAMEMATCH--=--PATTERN--,--QNAME--=--qname--'   

>--+-,--RNAMEMATCH--=--ANY----------------------------------------------------+-->
   +-,--RNAMEMATCH--=--SPECIFIC--,--RNAME--=--rname--,--RNAMELEN--=--rnamelen-+   
   '-,--RNAMEMATCH--=--PATTERN--,--RNAME--=--rname--,--RNAMELEN--=--rnamelen--'   

   .-,--SCOPE--=--ANY-----.  .-,--SERIALIZEBY--=--ANY------.   
>--+----------------------+--+-----------------------------+---->
   +-,--SCOPE--=--STEP----+  +-,--SERIALIZEBY--=--RESERVE--+   
   +-,--SCOPE--=--SYSTEM--+  '-,--SERIALIZEBY--=--ENQ_ONLY-'   
   +-,--SCOPE--=--SYSTEMS-+                                    
   '-,--SCOPE--=--SYSPLEX-'                                    

   .-,--SYSNAME--=--ANY_SYSNAME-.   
>--+----------------------------+------------------------------->
   '-,--SYSNAME--=--sysname-----'   

>--+--------------------------------+--------------------------->
   | .-,--ASID--=--ANY_ASID-.       |   
   +-+-,--ASID--=--asid-----+-------+   
   | .-,--JOBNAME--=--ANY_JOBNAME-. |   
   +-+-,--JOBNAME--=--jobname-----+-+   
   | .-,--TTOKEN--=--ANY_TTOKEN-.   |   
   '-+-,--TTOKEN--=--ttoken-----+---'   

   .-,--MINREQUESTERS--=--NO_MINREQ-----.   
>--+------------------------------------+----------------------->
   '-,--MINREQUESTERS--=--minrequesters-'   

   .-,--MINOWNERS--=--NO_MINOWN-.   
>--+----------------------------+------------------------------->
   '-,--MINOWNERS--=--minowners-'   

   .-,--MINWAITERS--=--NO_MINWAIT-.   
>--+------------------------------+----------------------------->
   '-,--MINWAITERS--=--minwaiters-'   

   .-,--USERDATAMATCH--=--ANY---------------------------------------------------------------.   
>--+----------------------------------------------------------------------------------------+-><
   +-,--USERDATAMATCH--=--SPECIFIC--,--USERDATA--=--userdata--------------------------------+   
   '-,--USERDATAMATCH--=--PATTERN--,--USERDATA--=--userdata--,--USERDATALEN--=--userdatalen-'


parameters-5

>>-+-,--ANALYZE--=--WAITER--+----------------------------------><
   +-,--ANSAREA--=--ansarea-+   
   '-,--ANSLEN--=--anslen---'

Parameters

The parameters are explained as follows:

name

An optional symbol, starting in column 1, that is the name on the ISGQUERY macro invocation. The name must conform to the rules for an ordinary assembler language symbol.

,ANALYZE=WAITER

When REQINFO=LATCHECA is specified, a required output parameter, which queries LATCHECA waiter data to determine if any long term latch contention exists that might be cause for concern. ISGQUERY only returns LATCHECA data for waiters.

,ANSAREA=ansarea

When REQINFO=ENQSTATS is specified, a required output parameter, which is to contain the returned information. The area is mapped by macro ISGYQUAA. A header area, mapped by DSECT ISGYQUAAHdr, is returned followed by additional data, two entries mapped by ISGYQUAASys and two entries mapped by ISGYQUAASp.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,ANSAREA=ansarea

When REQINFO=LATCHAREA is specified, a required output parameter, which is to contain the returned information. The area is mapped by macro ISGYQUAA. A header area, mapped by DSECT ISGYQUAAHdr, is returned followed by additional data mapped by ISGYQUAARs, ISGYQUAARsx, ISGYQUAARq, and ISGYQUAARqx. Note that the ANSDETAIL specified determines which data is returned.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,ANSAREA=ansarea

When REQINFO=LATCHECA is specified, a required output parameter, which is to contain the returned information. The area is mapped by macro ISGYQUAA. A header area, mapped by DSECT ISGYQUAAHdr, is returned followed by additional data mapped by ISGYQUAALd and ISGYQUAALrd.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,ANSAREA=ansarea

When REQINFO=USAGESTATS is specified, a required output parameter, which is to contain the returned information. The area is mapped by macro ISGYQUAA. A header area, mapped by DSECT ISGYQUAAHdrUs, is returned followed by additional data mapped by ISGYQUAAUs.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,ANSAREA=ansarea

When SCANACTION=START and REQINFO=QSCAN are specified, a required output parameter, which is to contain the returned information. The area is mapped by macro ISGYQUAA. A header area, mapped by DSECT ISGYQUAAHdr, is returned followed by additional data mapped by ISGYQUAARs, ISGYQUAARsx, ISGYQUAARq, and ISGYQUAARqx. Note that the ANSDETAIL specified determines which data is returned.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,ANSAREA=ansarea

When SCANACTION=RESUME and REQINFO=QSCAN are specified, a required output parameter, which is to contain the returned information. The area is mapped by macro ISGYQUAA. A header area, mapped by DSECT ISGYQUAAHdr, is returned followed by additional data mapped by ISGYQUAARs, ISGYQUAARsx, ISGYQUAARq, and ISGYQUAARqx. Note that the ANSDETAIL specified determines which data is returned.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,ANSDETAIL=SUMMARY

,ANSDETAIL=FULL

,ANSDETAIL=FULL2

,ANSDETAIL=FULL3

When SCANACTION=START and REQINFO=QSCAN are specified, an optional parameter that indicates the detail level of the information that should be returned in the answer area. The default is ANSDETAIL=SUMMARY.

,ANSDETAIL=SUMMARY: indicates to only return ISGYQUAAHdr, ISGYQUAARs, and ISGYQUAARq answer area data records. See ISGYQUAA mapping macro to know what data is returned in each type of record.
,ANSDETAIL=FULL: indicates to return ISGYQUAAHdr, ISGYQUAARs, ISGYQUAARq, and ISGYQUAARqx answer area data records. See ISGYQUAA mapping macro to know what data is returned in each type of record.
,ANSDETAIL=FULL2: indicates that in addition to the records returned by ANSDETAIL=FULL, the ISGYQUAARsx and the larger FULL2 version of the ISGYQUAARqx is returned. See ISGYQUAA mapping macro to know what data is returned in each type of record.
,ANSDETAIL=FULL3: indicates that in addition to the records returned by ANSDETAIL=FULL2, USERDATA is returned for any records that specified USERDATA on ISGENQ. Note that when GATHERFROM=SYSPLEX is specified and GRS is operating in STAR mode, USERDATA is not returned for any global requests. See ISGYQUAA mapping macro to know what data is returned in each type of record.

,ANSLEN=anslen

When SCANACTION=START and REQINFO=QSCAN are specified, a required input parameter that is the length of the answer area provided. The minimum size is the amount needed to describe a single resource with a single requester. Use an answer area length of at least 4K.

For ANSDETAIL=SUMMARY, the minimum is defined by constant ISGYQUAA_kQSCANMinSummaryAnslen.
For ANSDETAIL=FULL, the minimum is defined by constant ISGYQUAA_kQSCANMinFullAnslen.
For ANSDETAIL=FULL2, the minimum is defined by constant ISGYQUAA_kQSCANMinFull2Anslen.
For ANSDETAIL=FULL3, the minimum is defined by constant ISGYQUAA_kQSCANMinFull3Anslen.

The length of the answer area is at least 4k.

To code: Specify the RS-type address, or address in register (2)-(12), of a fullword field, or specify a literal decimal value.

,ANSLEN=anslen

When SCANACTION=RESUME and REQINFO=QSCAN are specified, a required input parameter that is the length of the answer area provided. The minimum size is the amount needed to describe a single resource with a single requester. Use an answer area length of at least 4K. For ANSDETAIL=SUMMARY, the minimum is defined by constant ISGYQUAA_kQSCANMinSummaryAnslen. For ANSDETAIL=FULL, the minimum is defined by constant ISGYQUAA_kQSCANMinFullAnslen. For ANSDETAIL=FULL2, the minimum is defined by constant ISGYQUAA_kQSCANMinFull2Anslen. For ANSDETAIL=FULL3, the minimum is defined by constant ISGYQUAA_kQSCANMinFull3Anslen. use an answer area length of at least 4K.

To code: Specify the RS-type address, or address in register (2)-(12), of a fullword field, or specify a literal decimal value.

,ANSLEN=anslen

When REQINFO=LATCHECA is specified, a required input parameter that is the length of the answer area provided. The minimum size is the amount needed to describe a single resource with a single requester. Use an answer area length of at least 4K.

To code: Specify the RS-type address, or address in register (2)-(12), of a fullword field, or specify a literal decimal value.

,ANSLEN=anslen

When REQINFO=USAGESTATS is specified, a required input parameter that is the length of the answer area provided. The minimum size is the amount needed to describe the ENQ, QScan, and latch usage of a single address space as well as the usage information for terminated address spaces. The minimum is defined by constant ISGYQUAA_kUSAGESTATSMinAnslen. Use an answer area length of at least 4K.

To code: Specify the RS-type address, or address in register (2)-(12), of a fullword field, or specify a literal decimal value.

,ASID=asid

When REQINFO=ENQSTATS is specified, a required input parameter that is the ASID of the address space specific information to be returned.

Note that ASIDs are reusable. Once an address space has terminated another may be created with the same ASID.

To code: Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value.

,ASID=asid

,ASID=ANY_ASID

When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, an optional input parameter that is the ASID of the requesting tasks for which resource information is to be returned. Only information on requesters with that ASID is returned.

Note that ASIDs are reusable. Once an address space has terminated another may be created with the same ASID.

The default is ANY_ASID.

To code: Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value.

,ENQTOKEN=enqtoken

When SEARCH=BY_ENQTOKEN, SCANACTION=START and REQINFO=QSCAN are specified, a required input parameter that is the ENQToken of the request that is to be queried. Note: ENQTokens are only valid on the system where the ENQ request was made.

To code: Specify the RS-type address, or address in register (2)-(12), of a 32-character field.

,GATHERFROM=SYSTEM

,GATHERFROM=SYSPLEX

When SCANACTION=START and REQINFO=QSCAN are specified, an optional parameter that designates the extent to which the search is taken. Information about other systems is always available locally in a global resource serialization ring complex, so this keyword is ignored and forced to GATHERFROM=SYSTEM.

Use the SYSNAME keyword to obtain only information about one particular system.

Note: Only SYSTEMS scope information is obtained from other systems in the global resource serialization complex.

The default is GATHERFROM=SYSTEM.

,GATHERFROM=SYSTEM

Indicates to search only the caller's system. The answer area data contains information about requesters on other systems in the complex only if that information is already available on the caller's system. The returned information might be incomplete regarding requesters on other systems, including counts of the number of requesters for a resource. If performance is an issue, use GATHERFROM=SYSTEM. This request is always handled without placing the caller's dispatchable unit into a wait.

,GATHERFROM=SYSPLEX

Indicates to search the caller's sysplex. The answer area data contains information about requesters in the entire sysplex. If complete information regarding requesters in the sysplex is required use GATHERFROM=SYSPLEX. There are significant performance implications for this search and the caller might be suspended while the information is being gathered. Do not specify GATHERFROM=SYSPLEX if this condition cannot be tolerated.

GATHERFROM=SYSPLEX is mutually exclusive with the USERDATAMATCH=SPECIFIC and USERDATAMATCH=PATTERN filter options.

When global resource serialization is in STAR mode, GATHERFROM=SYSPLEX with ANSDETAIL=FULL3 results in no user data being returned for global requests.

,JOBNAME=jobname

,JOBNAME=ANY_JOBNAME

When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, an optional input parameter that is the job name of the requesting tasks for which resource information is to be returned. Only information on requesters with that job name is returned. The default is ANY_JOBNAME.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

,MF=S

,MF=(L,list addr)

,MF=(L,list addr,attr)

,MF=(L,list addr,0D)

,MF=(E,list addr)

,MF=(E,list addr,COMPLETE)

An optional input parameter that specifies the macro form.

Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.

Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.

Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.

,list addr: The name of a storage area to contain the parameters. For MF=S and MF=E, this can be an RS-type address or an address in register (1)-(12).
,attr: An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE: Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.

,MINOWNERS=minowners

,MINOWNERS=NO_MINOWN

When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, an optional input parameter that is the minimum number of owners of a resource required for that resource to be returned. If any of the conditions specified by MINREQUESTERS, MINOWNERS, or MINWAITERS is met, even if the other two are not met, information for that resource and its requesters is returned. The default is NO_MINOWN.

To code: Specify the RS-type address, or address in register (2)-(12), of a fullword field, or specify a literal decimal value.

,MINREQUESTERS=minrequesters

,MINREQUESTERS=NO_MINREQ

When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, an optional input parameter that is the minimum number of owners plus waiters for a resource required for that resource to be returned. If any of the conditions specified by MINREQUESTERS, MINOWNERS, or MINWAITERS is met, even if the other two are not met, information for that resource and its requesters is returned. The default is NO_MINREQ.

To code: Specify the RS-type address, or address in register (2)-(12), of a fullword field, or specify a literal decimal value.

,MINWAITERS=minwaiters

,MINWAITERS=NO_MINWAIT

When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, an optional input parameter that is the minimum number of waiters for a resource required for that resource to be returned. If any of the conditions specified by MINREQUESTERS, MINOWNERS, or MINWAITERS is met, even if the other two are not met, information for that resource and its requesters is returned. The default is NO_MINWAIT.

To code: Specify the RS-type address, or address in register (2)-(12), of a fullword field, or specify a literal decimal value.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=1

,PLISTVER=2

An optional input parameter in the 1-2 range that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:

IMPLIED_VERSION, which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
MAX, if you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
1, if you use the currently available parameters:
- ANSAREA
- ANSDETAIL
- ANSLEN
- ASID
- ENQTOKEN
- GATHERFROM
- JOBNAME
- MINOWNERS
- MINREQUESTERS
- MINWAITERS
- QNAME
- QNAMEMATCH
- REQINFO
- REQUESTERLIMIT
- RESUMETOKEN
- RNAME
- RNAMELEN
- RNAMEMATCH
- RNL
- RNLE
- SCANACTION
- SCOPE
- SEARCH
- SERIALIZEBY
- SYSNAME
- TTOKEN
2, which supports both the following parameters and those from version 1:
- USERDATA
- USERDATALEN
- USERDATAMATCH

To code: Specify one of the following:

IMPLIED_VERSION
MAX
A decimal value of 1, or 2

,QNAME=qname

When REQINFO=RNLSEARCH is specified, a required input parameter that is the QName of the resource for which the RNLs are to be searched.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

,QNAME=qname

When QNAMEMATCH=SPECIFIC, SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, a required input parameter that is the specific QName of the resources to be returned.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

,QNAME=qname

When QNAMEMATCH=PATTERN, SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, a required input parameter that is a pattern QName to match the resources to be returned.

The QName pattern is 8 characters where ? matches any single character, and * matches any string of zero or more characters. Note: All trailing blanks are ignored when matching QNames to QName patterns.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

,QNAMEMATCH=SPECIFIC

,QNAMEMATCH=PATTERN

When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, a required parameter.

,QNAMEMATCH=SPECIFIC: Indicates to only return information on resources that exactly match the specified specific QName.
,QNAMEMATCH=PATTERN: Indicates to only return information on resources that match the specified QName pattern.

REQINFO=RNLSEARCH

REQINFO=ENQSTATS

REQINFO=QSCAN

REQINFO=LATCHECA

REQINFO=USAGESTATS

A required parameter that designates the data to be returned.

REQINFO=RNLSEARCH

Indicates to search a specific RNL for a given resource name.

The CMSEQDQ lock serializes the use of the RNLs, so holding this lock ensures that the RNL does not change and therefore the returned RNLE is valid on the current RNLs.

During an RNL change, the currently active RNLs are searched.

For more information about how a resource can be changed by the system, see the TEST=YES function in ISGENQ — Global resource serialization ENQ service.

REQINFO=ENQSTATS

Indicates to return information related to ENQ counts.

REQINFO=QSCAN

Indicates to search the global resource serialization queues for resource and requester information.

REQINFO=LATCHECA

Indicates to search the global resource serialization queues for query latch enhanced contention analysis (ECA) data for waiters that might indicate contention issues.

Note: The LATCHECA search does not return data for blockers or dependency data.

REQINFO=USAGESTATS

Indicates to search the global resource serialization queues for address space level contention information related to ENQs (all scopes) and latches (all latch sets). Global resource serialization gathers latch statistics in requester and latch set owner address space categories. The statistics are provided for all address spaces as follows:

ENQ by scope: this includes contention counts, total delay times, and the sum of the squared delay (SUMSQ) times. The SUMSQ times can be used to compute the standard deviation.
Latch: For both requesters and latch set owners, this includes contention counts, total delay times, and the sum of the squared delay (SUMSQ) times
ENQ usage counts. Note that latch counts are kept in “fast counts” in latch sets and not on an address space basis.

,REQUESTERLIMIT=requesterlimit

,REQUESTERLIMIT=32767

When SCANACTION=START and REQINFO=QSCAN are specified, an optional input parameter that is the maximum number of requesters (owners and waiters) to be returned for each individual resource. Only resource related information is returned if 0 is specified. The value range of Requsterlimit is 0 to 2¬15-1 (32767). The default is 32767.

To code: Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value.

,RESUMETOKEN=resumetoken

When SCANACTION=START and REQINFO=QSCAN are specified, an optional output parameter that is the resume token for this search. When RESUMETOKEN is specified, a reason code of ISGQUERYRsn_AnswerAreaFull indicates that the token can be used to resume the scan on a subsequent call. If the return code indicates that the search can be resumed, a SCANACTION=RESUME or SCANACTION=QUIT with the returned resume token must be subsequently issued.

To code: Specify the RS-type address, or address in register (2)-(12), of a 16-character field.

,RESUMETOKEN=resumetoken

When SCANACTION=RESUME and REQINFO=QSCAN are specified, a required input/output parameter that is the resume token from a previously started search. If the search does not complete the resume token can be used to resume the search on a subsequent call. Check the return code to determine if the resume token can be used to resume the scan. If the return code indicates that the search can be resumed, a SCANACTION=RESUME or SCANACTION=QUIT with the returned resume token must be subsequently issued.

To code: Specify the RS-type address, or address in register (2)-(12), of a 16-character field.

,RESUMETOKEN=resumetoken

When SCANACTION=QUIT and REQINFO=QSCAN are specified, a required input/output parameter that is the resume token from a previously started search. Any global resource serialization storage associated with the search is freed, and the resume token is cleared to binary zeros.

To code: Specify the RS-type address, or address in register (2)-(12), of a 16-character field.

,RETCODE=retcode

An optional output parameter into which the return code is to be copied from GPR 15. If you specify 15, GPR15, REG15, or R15 (within or without parentheses), the value will be left in GPR 15.

To code: Specify the RS-type address of a fullword field, or register (2)-(12) or (15), (GPR15), (REG15), or (R15).

,RNAME=rname

When REQINFO=RNLSEARCH is specified, a required input parameter that is the RName of the resource for which the RNLs are to be searched.

The RName pattern is a string of characters where ? matches any single character, and * matches any string of zero or more characters.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,RNAME=rname

When RNAMEMATCH=SPECIFIC, SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, a required input parameter that is the specific RName of the resources to be returned.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,RNAME=rname

When RNAMEMATCH=PATTERN, SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, a required input parameter that is a pattern RName to match the resources to be returned. The RName pattern is a string of characters where '?' matches any single character, and '*' matches any string of zero or more characters.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,RNAMELEN=rnamelen

When REQINFO=RNLSEARCH is specified, a required input parameter that is the length of the given RName. The specified length can be 1 to 255.

To code: Specify the RS-type address, or address in register (2)-(12), of an one-byte field.

,RNAMELEN=rnamelen

When RNAMEMATCH=SPECIFIC, SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, a required input parameter that is the length of the given RName. The specified length can be 1 to 255.

To code: Specify the RS-type address, or address in register (2)-(12), of an one-byte field.

,RNAMELEN=rnamelen

When RNAMEMATCH=PATTERN, SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, a required input parameter that is the length of the given RName pattern. The specified length can be 1 to 255.

To code: Specify the RS-type address, or address in register (2)-(12), of an one-byte field.

,RNAMEMATCH=ANY

,RNAMEMATCH=SPECIFIC

,RNAMEMATCH=PATTERN

When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, a required parameter.

,RNAMEMATCH=ANY: Indicates to return information on resources with any RName.
,RNAMEMATCH=SPECIFIC: Indicates to only return information on resources that exactly match the specified specific RName.
,RNAMEMATCH=PATTERN: Indicates to only return information on resources that match the specified RName pattern.

,RNL=SIRNL

,RNL=SERNL

,RNL=RCRNL

When REQINFO=RNLSEARCH is specified, a required parameter that indicates which resource name list (RNL) is to be searched.

,RNL=SIRNL: Indicates to search the system inclusion RNL.
,RNL=SERNL: Indicates to search the systems exclusion RNL.
,RNL=RCRNL: Indicates to search the reserve conversion RNL.

,RNLE=rnle

When REQINFO=RNLSEARCH is specified, an optional output parameter that is a copy of the matching RNLE. The caller must include the ISGRNLE macro to get a mapping for the RNLE.

Note: The RNLE returned is dependent on the version of the parameter list. If a new version of the RNLE should be introduced, it might require a larger character field. Explicitly state the PLISTVER to ensure that the size of the RNLE returned does not change.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,RSNCODE=rsncode

An optional output parameter into which the reason code is to be copied from GPR 0. If you specify 0, 00, GPR0, GPR00, REG0, REG00, or R0 (within or without parentheses), the value will be left in GPR 0.

To code: Specify the RS-type address of a fullword field, or register (0) or (2)-(12), (00), (GPR0), (GPR00), REG0), (REG00), or (R0).

,SCANACTION=START

,SCANACTION=RESUME

,SCANACTION=QUIT

When REQINFO=QSCAN is specified, a required parameter that designates whether to start, resume, or quit a QScan.

,SCANACTION=START: Indicates to start a search of the global resource serialization queues.
,SCANACTION=RESUME: indicates to resume a previously started search.
,SCANACTION=QUIT: indicates to quit a previously started search. If a started search has not completed it must be either resumed until it completes or ended with SCANACTION=QUIT.

,SCOPE=ANY

,SCOPE=STEP

,SCOPE=SYSTEM

,SCOPE=SYSTEMS

,SCOPE=SYSPLEX

When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, an optional parameter that is the scope of the resources to be returned.

Note: Only information on resources with scope of SYSTEMS is returned from systems other than the caller's system.

The default is SCOPE=ANY.

,SCOPE=ANY: Indicates to return information on resources with any scope.
,SCOPE=STEP: Indicates to only return information on resources with a scope of STEP.
,SCOPE=SYSTEM: Indicates to only return information on resources with a scope of SYSTEM.
,SCOPE=SYSTEMS: Indicates to only return information on resources with a scope of SYSTEMS or SYSPLEX.
,SCOPE=SYSPLEX: Indicates to only return information on resources with a scope of SYSTEMS or SYSPLEX. (SYSPLEX is an alias for SYSTEMS.)

,SEARCH=BY_ENQTOKEN

,SEARCH=BY_FILTER

When SCANACTION=START and REQINFO=QSCAN are specified, a required parameter that designates the method to search for resources.

,SEARCH=BY_ENQTOKEN: Indicates to search using a specific ENQToken. Information is returned about the requester of the ENQ and the resource for which the ENQ was requested.
,SEARCH=BY_FILTER: Indicates to search on resource and requester characteristics using filters. Information is returned about the resources and requesters that match the search criteria.

,SERIALIZEBY=ANY

,SERIALIZEBY=RESERVE

,SERIALIZEBY=ENQ_ONLY

When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, an optional parameter that indicates if information should be returned depending on whether the requests are serialized by device reserves. The default is SERIALIZEBY=ANY.

,SERIALIZEBY=ANY: Indicates to return information on requests of any type.
,SERIALIZEBY=RESERVE: Indicates to only return information on reserve requests that were not converted.
,SERIALIZEBY=ENQ_ONLY: Indicates to only return information on requests that do not result in a device reserve. This includes reserve requests that were converted to global ENQs. Answer area bit ISGYQUAARqReserveConverted is set for reserve requests that were converted.

,SYSNAME=sysname

,SYSNAME=ANY_SYSNAME

When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, an optional input parameter that is the system name of the requesting tasks for which resource information is to be returned. Only information on requesters in that system is returned. If GATHERFROM=SYSTEM is specified (or is the default), SYSNAME might only be the name of the caller's system or the default of ANY_SYSNAME.

Note: Only information on resources with scope of SYSTEMS is returned from systems other than the caller's system.

The default is ANY_SYSNAME.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

,TTOKEN=ttoken

,TTOKEN=ANY_TTOKEN

When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, an optional input parameter that is the task token of the requesting task for which resource information is to be returned. Only information on that requester is returned. The TToken specified is valid only on the current system.

Note: The TToken of requesters is unavailable for ENQs obtained before the global resource serialization address space was created. The TToken filter will not match those ENQ requesters.

The default is ANY_TTOKEN.

To code: Specify the RS-type address, or address in register (2)-(12), of a 16-character field.

,USERDATA=userdata

When USERDATAMATCH=SPECIFIC, SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, a required input parameter that is the specific UserData of the requests to be returned.

To code: Specify the RS-type address, or address in register (2)-(12), of a 32-character field.

,USERDATA=userdata

When USERDATAMATCH=PATTERN, SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, a required input parameter that is a pattern UserData to match the requests to be returned. The UserData pattern is a string of characters where '?' matches any single character, and '*' matches any string of zero or more characters.

To code: Specify the RS-type address, or address in register (2)-(12), of a 32-character field.

,USERDATALEN=userdatalen

When USERDATAMATCH=PATTERN, SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, a required input parameter that is the length of the given UserData pattern. The specified length can be 1 to 32.

To code: Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value.

,USERDATAMATCH=ANY

,USERDATAMATCH=SPECIFIC

,USERDATAMATCH=PATTERN

When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, an optional parameter that indicates which requests to return. The default is USERDATAMATCH=ANY.

,USERDATAMATCH=ANY

indicates to return information on request with any USERDATA, including those with no USERDATA.

,USERDATAMATCH=SPECIFIC

indicates to only return requests that have USERDATA that exactly matches the specified USERDATA. For information about specifying USERDATA on an ISGENQ request, see ISGENQ — Global resource serialization ENQ service. Note that USERDATA can only be attached to a request through the ISGENQ interface.

This request requires a version 2 parameter list.

GATHERFROM=SYSPLEX is mutually exclusive with the USERDATAMATCH=SPECIFIC option.

,USERDATAMATCH=PATTERN

indicates to only return information on requests that match the specified UserData pattern. For information about specifying USERDATA on an ISGENQ request, see ISGENQ — Global resource serialization ENQ service .

All trailing blanks are not ignored when matching USERDATA to USERDATA patterns. For example, if the USERDATA is ABC123, and the pattern used to search is A*3, it does not match. A pattern such as A*3* does match.

Note: Userdata can only be attached to a request through the ISGENQ interface.

This request requires a version 2 parameter list.

GATHERFROM=SYSPLEX is mutually exclusive with the USERDATAMATCH=PATTERN option.

ABEND codes

None.

Return and reason codes

When the ISGQUERY macro returns control to your program:

GPR 15 (and retcode, when you code RETCODE) contains a return code.
When the value in GPR 15 is not zero, GPR 0 (and rsncode, when you code RSNCODE) contains a reason code.

Macro ISGYCON provides equate symbols for the return and reason codes.

The following table identifies the hexadecimal return and reason codes and the equate symbol associated with each reason code. IBM support personnel may request the entire reason code, including the xxxx value.

Table 1. Return and Reason Codes for the ISGQUERY Macro
Return Code	Reason Code	Equate Symbol Meaning and Action
00	—	Equate Symbol: ISGQUERYRc_OK Meaning: ISGQUERY request successful. For REQINFO=RNLSEARCH, a matching RNLE was found for the given resource name. For REQINFO=QSCAN, processing complete and data has been copied into the answer area. There is no more data to return. Action: None required.
04	—	Equate Symbol: ISGQUERYRc_Warn Meaning: Warning. ISGQUERY completed successfully, however a warning has been issued. Action: Refer to action under the individual reason code.
04	xxxx0401	Equate Symbol: ISGQUERYRsn_NoMatchingRNLE Meaning: For a REQINFO=RNLSEARCH request. No matching RNLE was found for the given resource name. Action: No action required.
04	xxxx0402	Equate Symbol: ISGQUERYRsn_RNLChangeInProgress Meaning: For a REQINFO=RNLSEARCH request. A matching RNLE was found for the given resource name, but an RNL change is in progress in the system. Action: No action required.
04	xxxx0403	Equate Symbol: ISGQUERYRsn_GRSRNLExclude Meaning: For a REQINFO=RNLSEARCH request. GRSRNL=EXCLUDE is in effect. When GRSRNL=EXCLUDE the RNLs are not used and all SYSTEMS scope requests are forced to SYSTEM. An alternative serialization product may be in use. No RNLE is returned. Action: No action required.
04	xxxx0404	Equate Symbol: ISGQUERYRsn_NoMatchingResources Meaning: For REQINFO=QSCAN and REQINFO=LatchECA requests. While scanning the queues, no resources were found that match the caller's request. Action: No action required.
04	xxxx0405	Equate Symbol: ISGQUERYRsn_AnswerAreaFull Meaning: For a REQINFO=QSCAN request. ISGQUERY has provided some data, however the answer area is too small to contain all the requested data. Action: The user should process the data in the answer area. If RESUMETOKEN was not specified on the request and more information is needed, re-issue the request with a larger answer area or specify a resume token. If RESUMETOKEN was specified, either issue a REQINFO=QSCAN SCANACTION=RESUME request with the returned resume token to continue continue the scan, or issue REQINFO=QSCAN SCANACTION=QUIT to end the search.
04	xxxx0406	Equate Symbol: ISGQUERYRsn_GRSNone Meaning: For a REQINFO=RNLSEARCH request. GRS=NONE is in effect. When GRS=NONE the RNLs are not used and all requests are serialized only within the current system. Note that though both scope SYSTEM and SYSTEMS requests are local to the current system, they still represent separate resouces and are NOT serialized with each other.
08	—	Equate Symbol: ISGQUERYRc_ParmError Meaning: ISGQUERY request specified parameters in error. Action: Refer to action under the individual reason code.
08	xxxx0801	Equate Symbol: ISGQUERYRsn_BadPlistAddress Meaning: Unable to access parameter list. Action: Check that the entire parameter list is addressable. If in AR-mode, check that the ALET of the parameter list is correct. Note that if this macro is issued in AR-mode, SYSSTATE ASCENV=AR must be issued before this macro. Ensure that the storage is in the same key as the caller.
08	xxxx0802	Equate Symbol: ISGQUERYRsn_BadPlistALET Meaning: Bad parameter list ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's dispatchable unit access list (DU-AL), nor a valid entry for a common area data space. Action: Ensure that the ALET of the parameter list is valid. Its access register might have been set up properly.
08	xxxx0803	Equate Symbol: ISGQUERYRsn_BadPlistVersion Meaning: Bad parameter list version number. The service level of GRS on which the caller is running does not support this version of the ISGQUERY service, or the ISGQUERY parameter list version is lower than the minimum required for parameters that were specified. Action: Check that the request has the correct version number. Check for possible storage overlay of the parameter list.
08	xxxx0804	Equate Symbol: ISGQUERYRsn_ReservedFieldNotNull Meaning: A reserved field in the parameter list is non-zero. Action: Check for possible storage overlay of the parameter list.
08	xxxx0805	Equate Symbol: ISGQUERYRsn_BadReqInfo Meaning: Bad REQINFO parameter. Action: Check for possible storage overlay of the parameter list.
08	xxxx0806	Equate Symbol: ISGQUERYRsn_BadRNL Meaning: Bad RNL parameter. Action: Check for possible storage overlay of the parameter list.
08	xxxx0807	Equate Symbol: ISGQUERYRsn_BadRNameAddress Meaning: Unable to access the RName. Action: Ensure that the entire RName field is addressable. If in AR-mode, this field is accessed through its address and ALET, check that both these values are correct. Check that specified RName length is correct. Ensure that the storage is in the same key as the caller.
08	xxxx0808	Equate Symbol: ISGQUERYRsn_BadRNameALET Meaning: Bad RName ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's dispatchable unit access list (DU-AL), nor a valid entry for a common area data space. Action: Ensure that the ALET of the RName is valid. Its access register might have been set up properly.
08	xxxx0809	Equate Symbol: ISGQUERYRsn_BadRNameLen Meaning: The RName length specified is not valid. Action: Ensure the RName length field contains a number from 1-255.
08	xxxx080A	Equate Symbol: ISGQUERYRsn_BadRNLEAddress Meaning: Unable to access RNLE output field. Action: Ensure that the entire RNLE field is addressable. If in AR-mode, this field is accessed through its address and ALET, check that both these values are correct. Check that RNLE length is correct. Ensure that the storage is in the same key as the caller.
08	xxxx080B	Equate Symbol: ISGQUERYRsn_BadRNLEALET Meaning: Bad RNLE ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's dispatchable unit access list (DU-AL), nor a valid entry for a common area data space. Action: Ensure that the ALET of the RNLE is valid. Its access register might have been set up properly.
08	xxxx080C	Equate Symbol: ISGQUERYRsn_MutuallyExclusive Meaning: Mutually exclusive keywords were specified. Action: Check for a possible storage overlay of the parameter list.
08	xxxx080D	Equate Symbol: ISGQUERYRsn_BadAnsAreaAddress Meaning: Unable to access the answer area. Action: Ensure that the entire answer area is addressable. If in AR-mode, this field is accessed through its address and ALET, check that both these values are correct. Check that the specified answer area length is correct. Ensure that the storage is in the same key as the caller.
08	xxxx080E	Equate Symbol: ISGQUERYRsn_BadAnsAreaALET Meaning: Bad answer area ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's Dispatchable Unit Access List (DU-AL), nor a valid entry for a common area data space. Action: Ensure that the ALET of the answer area is valid. Its access register might have been set up properly.
08	xxxx080F	Equate Symbol: ISGQUERYRsn_BadScanAction Meaning: Bad SCANACTION parameter. Action: Check for possible storage overlay of the parameter list.
08	xxxx0810	Equate Symbol: ISGQUERYRsn_BadResumeTokenAddress Meaning: Unable to access the ResumeToken. Action: Ensure that the entire ResumeToken is addressable. If in AR-mode, this field is accessed through its address and ALET, check that both these values are correct. Ensure that the storage is in the same key as the caller.
08	xxxx0811	Equate Symbol: ISGQUERYRsn_BadResumeTokenALET Meaning: Bad ResumeToken ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's dispatchable unit access list (DU-AL), nor a valid entry for a common area data space. Action: Ensure that the ALET of the ResumeToken is valid. Its access register might not have been set up properly.
08	xxxx0812	Equate Symbol: ISGQUERYRsn_BadGatherFrom Meaning: Bad GATHERFROM parameter. Action: Check for possible storage overlay of the parameter list.
08	xxxx0813	Equate Symbol: ISGQUERYRsn_BadSearch Meaning: Bad SEARCH keyword parameter. Action: Check for possible storage overlay of the parameter list.
08	xxxx0814	Equate Symbol: ISGQUERYRsn_BadENQTokenAddress Meaning: Unable to access the ENQToken. Action: Ensure that the entire ENQToken is addressable. If in AR-mode, this field is accessed via its address and ALET, check that both these values are correct. Ensure that the storage is in the same key as the caller.
08	xxxx0815	Equate Symbol: ISGQUERYRsn_BadENQTokenALET Meaning: Bad ENQToken ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's dispatchable unit access list (DU-AL), nor a valid entry for a common area data space. Action: Ensure that the ALET of the ENQToken is valid. Its access register might have been set up properly.
08	xxxx0816	Equate Symbol: ISGQUERYRsn_BadQNameMatch Meaning: Bad QNAMEMATCH keyword parameter. Action: Check for possible storage overlay of the parameter list.
08	xxxx0817	Equate Symbol: ISGQUERYRsn_BadRNameMatch Meaning: Bad RNAMEMATCH keyword parameter. Action: Check for possible storage overlay of the parameter list.
08	xxxx0818	Equate Symbol: ISGQUERYRsn_BadScope Meaning: Bad SCOPE keyword parameter. Action: Check for possible storage overlay of the parameter list.
08	xxxx0819	Equate Symbol: ISGQUERYRsn_BadSerializeBy Meaning: Bad SERIALIZEBY keyword parameter. Action: Check for possible storage overlay of the parameter list.
08	xxxx081A	Equate Symbol: ISGQUERYRsn_AnsLenTooSmall Meaning: The size of the answer area is not large enough to contain the minimal amount of information. Action: Increase the answer area size to at least the minimum required for the specified request. See the provided constants. However, the answer area length should be at least 4k.
08	xxxx081B	Equate Symbol: ISGQUERYRsn_ResumeTokenNotValid Meaning: The specified resume token is not a valid resume token. Action: Ensure the resume token is from a previously started search on the current system.
08	xxxx081C	Equate Symbol: ISGQUERYRsn_ResumeTokenTooOld Meaning: The specified resume token is from an old search request that has expired. Action: Restart the search if more information is needed.
08	xxxx081D	Equate Symbol: ISGQUERYRsn_ENQTokenNotValid Meaning: The ENQToken specified is not a valid ENQToken. Action: Ensure the ENQToken is from a previous ISGENQ request on the current system.
08	xxxx081E	Equate Symbol: ISGQUERYRsn_BadRequesterLimit Meaning: The REQUESTERLIMIT value specified is not valid. RequesterLimit must be 0 to 2?5-1 (32767). Action: Ensure that the requester limit is in the correct range.
08	xxxx081F	Equate Symbol: ISGQUERYRsn_NoPossibleMatch Meaning: For a REQINFO=QSCAN request. Conflicting parameters were specified such that no resources could possibly match the request. A SYSNAME other than the current system was specified along with SCOPE=STEP, SCOPE=SYSTEM, TTOKEN, or GATHERFROM=SYSTEM. Or SERIALIZEBY=RESERVE was specified with SCOPE=STEP. Action: Avoid specifying conflicting parameters.
08	xxxx0820	Equate Symbol: ISGQUERYRsn_BadAnsDetail Meaning: Bad ANSDETAIL keyword parameter. Action: Check for possible storage overlay of the parameter list.
08	xxxx0821	Equate Symbol: ISGQUERYRsn_NotAuthToQscan Meaning: SETROPTS MLACTIVE is in effect, and the program is not authorized to issue ISGQUERY REQINFO=QSCAN. Action: 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.
08	xxxx0822	Equate Symbol: ISGQUERYRsn_BadASID Meaning: Bad ASID keyword parameter. Action: Ensure that the ASID is valid.
08	xxxx0823	Equate Symbol: ISGQUERYRsn_BadUserDataAddress Meaning: Unable to access the userdata. Action: Ensure that the entire USERDATA is addressable. If in AR-mode, this field is accessed via its address and ALET, check that both these values are correct. If this is a USERDATA pattern request, check that specified USERDATA length is correct. Ensure that the storage is in the same key as the caller.
08	xxxx0824	Equate Symbol: ISGQUERYRsn_BadUserDataAlet Meaning: Bad USERDATA ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's Dispatchable Unit Access List (DU-AL), nor a valid entry for a common area data space. Action: Ensure that the ALET of the USERDATA is valid. Its access register might have been set up properly.
08	xxxx0825	Equate Symbol: ISGQUERYRsn_BadUserDataLen Meaning: The USERDATA length specified is not valid. Action: Ensure the USERDATA length field contains a number in the range 1-32.
08	xxxx0826	Equate Symbol: ISGQUERYRsn_BadUserDataMatch Meaning: Bad USERDATAMATCH keyword parameter. Action: Check for possible storage overlay of the parameter list.
08	xxxx0827	Equate Symbol: ISGQUERYRsn_BadAnalyze Meaning: The ANALYZE keyword parameter is not valid. Action: Check for possible storage overlay of the parameter list.
08	xxxx0828	Equate Symbol: ISGQUERYRsn_NotAuthToLatchECA Meaning: SETROPTS MLACTIVE is in effect and the program is not authorized to issue ISGQUERY REQINFO=LATCHECA. Action: 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.LATCHECASERVICES.AUTHORIZATION and that the FACILITY class is SETROPTS RACLISTed.
0C	—	Equate Symbol: ISGQUERYRc_EnvError Meaning: ISGQUERY request has an environment error. Action: Refer to action under the individual reason code.
0C	xxxx0C01	Equate Symbol: ISGQUERYRsn_SrbMode Meaning: ISGQUERY can not be used in SRB mode. Action: Avoid using ISGQUERY in SRB mode.
0C	xxxx0C02	Equate Symbol: ISGQUERYRsn_NotEnabled Meaning: ISGQUERY can not be used disabled. Action: Avoid using ISGQUERY when not enabled.
0C	xxxx0C03	Equate Symbol: ISGQUERYRsn_ComplexMigrating Meaning: For a REQINFO=QSCAN request. The ISGQUERY service failed because the GRS complex was migrating from a ring to a star configuration. Action: Retry the request on or more times.
0C	xxxx0C04	Equate Symbol: ISGQUERYRsn_CannotObtainLocks Meaning: For REQINFO=RNLSEARCH, the local and CMSEQDQ locks could not be obtained. Action: Only use ISGQUERY REQINFO=RNLSEARCH when either no locks are held, or both a local lock and the CMSEQDQ lock are held with no other locks.
0C	xxxx0C05	Equate Symbol: ISGQUERYRsn_LockHeld Meaning: An incorrect lock was held upon entry. For REQINFO=QSCAN, no locks may be held. For REQINFO=RNLSEARCH, either no locks or both a local lock (LOCAL or CML) and the CMDEQDQ lock must be held. Action: Avoid using ISGQUERY REQINFO=QSCAN when locks are held. Avoid using ISGQUERY REQINFO=RNLSEARCH when locks other than both a local lock and the CMSEQDQ lock are held.
0C	xxxx0C06	Equate Symbol: ISGQUERYRsn_MaxConcurrentRequests Meaning: For a REQINFO=QSCAN request. The answer area was filled before queue scan processing completed, and reason code ISGQUERYRsn_AnswerAreaFull would have been issued. However, RESUMETOKEN was specified, but the limit for the number of concurrent resource requests (ISGENQ, ENQ, RESERVE, GQSCAN, and ISGQUERY) has been reached. The data in the answer 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. For more information on concurrent count limits and how the system can be tuned when necessary, see z/OS MVS Planning: Global Resource Serialization.
0C	xxxx0C07	Equate Symbol: ISGQUERYRsn_RingResumeInStar Meaning: For a REQINFO=QSCAN request. The 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. Action: Reissue the original request.
0C	xxxx0C08	Equate Symbol: ISGQUERYRsn_InsufficientStorage Meaning: For a REQINFO=QSCAN request. The ISGQUERY service could not obtain storage to satisfy the request. Action: Retry the request one or more times.
0C	xxxx0C09	Equate Symbol: ISGQUERYRsn_FRRHeld, Meaning: For a REQINFO=LATCHECA request. The caller issued ISGQUERY with a functional recover routine (FRR) established. Action: Avoid issuing ISGQUERY REQINFO=LATCHECA when using functional recovery routines.
10	—	Equate Symbol: ISGQUERYRc_CompError Meaning: Component Error Action: Contact the IBM Support Center. The reason code contains internal diagnostic information.

Examples

Use these examples as a guide.

* ***********************************************************************
*   Search the Systems Inclusion RNL for a resource name                 
* ***********************************************************************
                                                                        
         ISGQUERY REQINFO=RNLSEARCH,RNL=SIRNL,                         X
               QNAME=MYQNAME,RNAME=MYRNAME,RNAMELEN=MYRNAMELEN,        X
               RETCODE=MYRC,RSNCODE=MYRSN                               
                                                                        
* ***********************************************************************
*  Query information on a request specified by ENQToken                 
* ***********************************************************************
                                                                         
         ISGQUERY REQINFO=QSCAN,SCANACTION=START,                      X
               ANSAREA=MYAREA,ANSLEN=MYAREALEN,                        X
               SEARCH=BY_ENQTOKEN,ENQTOKEN=MYENQTOKEN,                 X
               RETCODE=MYRC,RSNCODE=MYRSN                               
                                                                        
* ***********************************************************************
*  Start a resumable query for resources of a specific job that         
*  matches a specific QNAME and pattern RNAME                           
* ***********************************************************************
                                                                       
         ISGQUERY REQINFO=QSCAN,SCANACTION=START,                      X
               ANSAREA=MYAREA,ANSLEN=MYAREALEN,                        X
               SEARCH=BY_FILTER,QNAMEMATCH=SPECIFIC,QNAME=MYQNAME,     X
               RNAMEMATCH=PATTERN,RNAME==CL7'ABC?23*',RNAMELEN=7,      X
               USERDATAMATCH=SPECIFIC,USERDATA=MYUDATA,                X
               JOBNAME=MYJOBNAME,RESUMETOKEN=MYRESTOKEN,RETCODE=MYRC,  X
               RSNCODE=MYRSN        
                                                                        
* ***********************************************************************
*  Start a resumable query for resources of a specific job that         
*  matches a specific QNAME and pattern RNAME                           
* ***********************************************************************

ISGQUERY REQINFO=QSCAN,SCANACTION=START,                               X 
         ANSAREA=MYAREA,ANSLEN=MYAREALEN,                              X 
         SEARCH=BY_FILTER,QNAMEMATCH=SPECIFIC,QNAME=MYQNAME,           X
         RNAMEMATCH=PATTERN,RNAME==CL7'ABC?23*',RNAMELEN=7,            X
         USERDATAMATCH=PATTERN,USERDATA=MYUDATAP,USERDATALEN=7,        X
         JOBNAME=MYJOBNAME,RESUMETOKEN=MYRESTOKEN,RETCODE=MYRC,        X
         RSNCODE=MYRSN

MYUDATA  DC    CL32'MY USERDATA'
MYUDATAP DC    CL7'M??USE*'

* ***********************************************************************
*  Resume a query that was started but not completed                    
* ***********************************************************************
                                                                       
         ISGQUERY REQINFO=QSCAN,SCANACTION=RESUME,                     X
               RESUMETOKEN=MYRESTOKEN,                                 X
               ANSAREA=MYAREA,ANSLEN=MYAREALEN,                        X
               RETCODE=MYRC,RSNCODE=MYRSN                               
                                                                        
* ***********************************************************************
*  Quit a query that was started but not completed                      
* ***********************************************************************
                                                                       
         ISGQUERY REQINFO=QSCAN,SCANACTION=QUIT,                       X
               RESUMETOKEN=MYRESTOKEN,                                 X
               RETCODE=MYRC,RSNCODE=MYRSN

* ***********************************************************************
*  Gather ENQ statistics for a particular address space                 
* ***********************************************************************
 
          ISGQUERY REQINFO=ENQSTATS,                                    X
                ANSAREA=MYAREA,ASID=MYASID,                             X
                RETCODE=MYRC,RSNCODE=MYRSN

* ***********************************************************************
*  Gather query latch enhanced contention analysis (LATCHECA) data from the  *
*  global resource serialization queues for waiters delayed because of  *
*  contention                                                           *
*************************************************************************
 
         ISGQUERY REQINFO=LATCHECA,ANALYZE=WAITER,ANSAREA=MYAREA,      X
               ANSLEN=MYAREALEN,RETCODE=MYRC,RSNCODE=MYRSN             X

* ***********************************************************************
*  Gather  address space level contention information related to ENQs   * 
*  (all scopes) and latches (all latch sets) from the                   *
*  global resource serialization queues                                 *
*************************************************************************
 
         ISGQUERY REQINFO=USAGESTATS,ANSAREA=MYAREA,ANSLEN=MYAREALEN,  X
               RETCODE=MYRC,RSNCODE=MYRSN                              X

For more information on global resource serialization, see z/OS MVS Planning: Global Resource Serialization.