Using the Subsystem Query Request of the IEFSSI Macro

The query request of the IEFSSI macro is the only service provided by this macro that does not require the caller to be authorized.

Inputs

The SSI obtains the storage necessary to return the query request information, because the issuer of the query request cannot determine in advance how much information will be returned. The issuer of the query request can use the WORKASP parameter to specify the subpool in which the SSI can obtain the storage. The query request fails if the SSI is unable to obtain enough storage. Unauthorized callers are limited to unauthorized subpools.

The query request returns information either for a single subsystem or for all subsystems matching the pattern specified with the SUBNAME parameter. The pattern can contain the following wildcard characters:

An asterisk ('*') — matches zero or more characters
A question mark ('?') — matches one character.

Outputs: The mapping macro IEFJSQRY maps the output returned by the query request.

If the SSI obtains the storage it needs to use the query request, the SSI returns the address of the output work area in the variable that the WORKAREA parameter identifies. The JQRYLEN field mapped by the IEFJSQRY macro contains the length of the returned storage. Upon completion, the issuer of the IEFJSQRY macro must free the returned storage. You should have established a recovery routine to free the returned storage in case your program ends abnormally. IBM® recommends you use task-oriented or job-oriented storage to ensure that the storage is released upon task or job completion.

If you request information about multiple subsystems, the output lists the information in broadcast order. That is, the subsystems are listed in the same order in which SSI broadcast processing invokes them. For each subsystem, the IEFSSI query request returns information about all associated vector tables managed by the SSI, active or not. For vector tables that are not managed by the SSI, the system locates only the active vector table and returns information about that vector table only.

A query request may fail to return information about some subsystems. If a subsystem is defined after IPL by directly manipulating the SSI control blocks and the definition either occurs during the processing of the query request or is not correctly completed, some subsystems may not be represented in the response to the query request.