Collecting information about resources and their requestors (ISGQUERY and GQSCAN macros)

Global resource serialization enables an installation to share symbolically named resources. Programs issue the ISGENQ, ENQ and RESERVE macros to request access to resources; global resource serialization adds information about each requestor to the appropriate resource queue. The only way you can extract information from the resource queues is by using the ISGQUERY or GQSCAN macro. See z/OS MVS Planning: Global Resource Serialization for information about how global resource serialization functions.

Using ISGQUERY and GQSCAN, you can inquire about a particular scope of resources (such as STEP, SYSTEM, or SYSTEMS), a specific resource by name, a specific system's resources, a specific address space's resources, or resources requested through the RESERVE macro. The system collects the information you request from the resource queues and consolidates that information before returning it. The authorized calls return a “snapshot” of the outstanding global resource serialization requests. The system serializes the resource queue so it does not change while the system gathers the information. (Authorized calls are those that specify either LOCAL or GLOBAL on the SCOPE parameter.) The information returned by unauthorized calls, which do not perform serialization, might be inconsistent because of changes in the resource queue that can occur while the system collects the information. (Unauthorized calls are those that specify either STEP, SYSTEM, SYSTEMS, or ALL on the SCOPE parameter.)

Using ISGQUERY the system returns information you request about the status of each resource identified to global resource serialization, which includes information about the tasks that have requested the resource. ISGQUERY fully supports 64-bit callers and as of z/OS® V1R6 is the IBM® recommended replacement for the GQSCAN service. Use the ISGQUERY service to inquire about:

A particular scope of resources (such as STEP, SYSTEM, or SYSTEMS).
A specific resource by name.
A specific system or systems resource.
A specific address space resource.
Resources that are requested through the RESERVE macro.
Requests that specified Userdata.

The system collects the information you request from the resource queues and consolidates that information before returning it. The ISGQUERY service returns the following types of global resource serialization information:

REQINFO=RNLSEARCH: To determine if a given resource name is in the current Resource Name Lists (RNL).
REQINFO=QSCAN: To obtain information on resources and requesters of outstanding ENQ requests.
REQINFO=ENQSTATS: To obtain information related to ENQ counts.
REQINFO=LATCHECA: To obtain enhanced contention analysis data for latch waiters that might indicate contention issues.
REQINFO=USAGESTATS: To obtain information for address space level contention information related to ENQs (all scopes) and latches (all latch sets).

On contrast, using the GQSCAN macro the system returns the information you request in an area whose location and size you specify using the AREA parameter. The size of the area, the scope of the resource, and whether you code the TOKEN parameter determine the information you receive from GQSCAN. Use the TOKEN parameter when you design your program to issue repeated calls to GQSCAN for the same request. For example, if you request information about a resource that is shared across systems, the amount of information might be more than will fit in the area that you provide. Using the TOKEN parameter allows you to issue subsequent calls to receive additional information about that resource.