Description

The IXLZSTR macro allows you to request coupling facility structure data from a dump containing that information. The macro returns the data requested in an answer area that you provide. You can use IXLZSTR only in an IPCS environment.

The TYPE parameter on the IXLZSTR macro determines what type of data will be returned to the caller:

TYPE=STRUCTURE returns structure information.
TYPE=CLASS returns class information for a requested cache structure.
TYPE=LISTNUM returns list number information for a requested list structure.
TYPE=LOCKENTRIES returns lock table information for a requested list structure.
TYPE=USERCNTLS returns user control information for a requested structure.
TYPE=ENTRY returns entry information for a requested entry in a requested structure.
TYPE=EMCONTROLS returns event monitor control information for a requested list structure. The requested list structure must be a keyed list structure allocated in a coupling facility with CFLEVEL=4 or higher.
TYPE=EVENTQS returns event queue control information for a requested connection ID. The requested connection ID must be connected to a keyed list structure in a coupling facility with CFLEVEL=4 or higher.

To use the macro, follow these guidelines:

Ensure that you include the proper structure attributes on the applicable structure type. For example, you cannot request a range of list numbers for a cache structure or a castout class for a list structure. If you specify structure attributes that do not apply, IXLZSTR fails the request and returns a return code of 8 and a reason code of X'14'.
Note: To determine the structure type of a given structure in the dump, issue the IXLZSTR macro with TYPE=STRUCTURE,STRLEVEL=SUMMARY. IXLZSTR returns a list of all structures requested to be dumped and their structure type in the answer area. Using the StrBStrSummary mapping in IXLZSTRB, you can find the structure name and check its corresponding type.
To determine the correct dump identifier for a given structure, issue the same macro as above. IXLZSTR returns the structure dump ID for each structure in the list of structures requested to be dumped, as well as the name of the coupling facility in which the structure was allocated.
On requests that specify a range of values, ensure that the starting range value is not greater than the ending range value. If the value is greater, IXLZSTR fails the request and returns a return code of 8 and a reason code of X'18'.
Use the RESTOKEN keyword to retrieve information when IXLZSTR cannot return all information at once in the answer area. When this volume of information exists, you must issue the IXLZSTR macro more than once, each time specifying the RESTOKEN as input.

Determining an Answer Area Size
The IXLZSTR macro puts the requested information in an answer area that you provide. The answer area contains a header (STRBHEADER) that describes the remainder of the information retrieved, followed by one or more entries for the requested information.

The amount of storage that you can specify for the answer area depends on the type of request. The minimum answer area size is 4096 bytes (4K). If you supply less than this amount, IXLZSTR fails the request and returns a return code of 8 and a reason code of X'10'.

A minimum storage allocation of 8192 bytes (8K) is required for a TYPE=STRUCTURE STRLEVEL=DETAIL request and for any request that specifies the ENTRYDATA keyword. If you provide less than 8K of storage for the answer area, IXLZSTR fails the request and returns a return code of 8 and a reason code of X'10'.

You might not be able to provide an answer area large enough to contain all the information returned by IXLZSTR for a single request. To allow for this situation, IXLZSTR provides the RESTOKEN parameter. You specify this token, initialized to binary zeros, on each invocation of IXLZSTR. If all the information can be returned in the answer area, IXLZSTR sets a return code of 0 and a reason code of 0. However, if all the information cannot be returned at once, IXLZSTR sets a return code of 4 and a reason code of 4 to indicate that there is more data to be retrieved from the dump data set. To retrieve the remainder of the data, you must invoke the IXLZSTR macro again with the same keywords and with RESTOKEN as input. (Do not reset RESTOKEN to binary zeros until all until all data for this request is retrieved.) When all data has been retrieved, IXLZSTR sets a return code of 0 and a reason code of 0 to indicate successful completion. IXLZSTR also sets the RESTOKEN to binary zeros.
Determining the Size of Each Entry Returned
Each time you retrieve information into your answer area, the header record (STRBHEADER) specifies the length of the table entry (STRBTABLEENTRYLEN). Each table entry also contains a header (STRBENTRY), which contains additional length specifications for the data.
- STRBENTRYADJLEN — length of the adjunct data
- STRBENTRYEDATALEN — length of the entry data
- STRBENTRYCNTLLEN — length of the entry control information
By calculating the sum of these four lengths, you can determine the length of the table entry and calculate the location of the next entry in the answer area.

When the information requested cannot all fit in one answer area, you must again calculate the length for the entry. Additional entries that can fit in the answer area after the first is completed, are preceded by the STRBENTRY header, which contains the appropriate lengths for the data entry that follows.