ISGQUERY — Global resource serialization query service
Description
- 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.
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
- 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
- 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.
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
- 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.
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
* ***********************************************************************
* 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.