How GQSCAN returns resource information

Using 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 information returned might not reflect changes in the resource queue that occur while the system collects the information.

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.

GQSCAN returns the information in the form of resource information blocks (RIB) and resource information block extensions (RIBE), as shown in the following figure. The RIB and the RIBE are described in z/OS MVS Data Areas in the z/OS Internet library.

The figure shows two resource information blocks (RIB A and RIB B). RIB A has three resource information block extensions (RIBE A1, RIBE A2, and RIBE A3), and RIB B has two RIBEs (RIBE B1 and RIBE B2).

In the RIB, the following fields contain information on RIBEs:

RIBTRIBE contains the total number of RIBEs associated with this RIB.
RIBNRIBE contains the total number of RIBEs associated with this RIB that GQSCAN could fit into the area specified on the AREA parameter.
RIBEDEVN contains a 4-digit EBCDIC device number for RESERVEs issued on the system. For RESERVEs issued on other systems, RIBEDEVN contains zero.

If the value in RIBNRIBE is less than the value in RIBTRIBE, you may need to specify a larger area with the AREA parameter.

The number of RIBs and RIBEs you receive for a particular resource depends on the size of the area you provide, and the scope and token values you specify on the GQSCAN macro.