Description

The IHABLDP macro builds the STRLIST parameter list that is specified as input on the SDUMPX macro when you request coupling facility structure information. IHABLDP builds the STRLIST parameter list in a block of storage that you provide to the macro. The STRLIST parameter list is mapped by the macro IHASDSTR. The IHABLDP macro does not initiate a dump request.

Each time you invoke IHABLDP, you specify a TYPE parameter to indicate which operation is to be performed on the STRLIST parameter list. The TYPE option determines which entry is to be built in the STRLIST parameter list.

TYPE=INITIAL initializes the storage to binary zeros and generates an initialized header for the dump parameter list. The length of the dump parameter list header is 24 bytes.
TYPE=STRUCTURE generates a structure entry in the dump parameter list. The length of this entry is 48 bytes.
TYPE=STRRNG generates a structure range entry in the dump parameter list. The length of this entry is 12 bytes.
TYPE=STROPT generates a structure option entry in the dump parameter list. The length of this entry is 12 bytes.
TYPE=ENDLIST completes the construction of the dump parameter list. No entries will be added to the dump parameter list.

The data is dumped in the order in which you requested it. Serialized ranges are dumped before unserialized ranges.

The amount of storage required for the STRLIST parameter list depends on the number and type of entries in the parameter list. You determine the size by adding the number of bytes for each entry.

The minimum STRLIST parameter list consists of a header and one structure entry (TYPE=STRUCTURE); thus the minimum size is 72 bytes.
The maximum STRLIST parameter list can consist of 47 structures and 6 ranges. For each structure less than 47, you can specify an additional 10 ranges. For example:
```
         47 structures and  6 ranges
         46 structures and 16 ranges
         44 structures and 36 ranges
```
If you specify more than the maximum allowed in the STRLIST, the system truncates the extraneous entries and indicates that the dump is a partial one by setting the SDRSTRLE flag in IHASDRSN, SDUMP Partial Reason Codes.

IHABLDP processes requests with incorrect parameter list lengths in the following ways:

Minimum storage not specified at initialization
If less than 72 bytes of storage is specified when TYPE=INITIAL is requested, IHABLDP returns a return code of 8 and a reason code of 4 to indicate that insufficient space is available. Subsequent IHABLDP invocations that reference the same STRLIST parameter list also fail.
Insufficient storage not specified after initialization
If sufficient storage is not available in an initialized STRLIST parameter list to add another entry, IHABLDP returns a return code of 8 and a reason code of 4. Subsequent IHABLDP invocations that reference the same STRLIST parameter list also are unable to add entries to the parameter list and receive the same return and reason codes. When you invoke TYPE=ENDLIST to complete the construction of this parameter list, IHABLDP sets the total length of the list to 16 bytes less than the block of storage that you initially provided to the macro. The SDUMPX macro must be responsible to check that all entries in the parameter list are processed.

To use the macro, follow these guidelines:

Specify TYPE=INITIAL before any other invocation of IHABLDP.
Specify TYPE=STRUCTURE for each structure desired in the dump before specifying TYPE=STRRNG or TYPE=STROPT for that structure.
Once TYPE=STRUCTURE is processed, you can specify one or more TYPE=STRRNG or TYPE=STROPT options until all the desired ranges for a requested structure are specified. IHABLDP allows you prioritization of information that you request for a specified structure. You can specify the STRRNG and STROPT options in any order to give you more flexibility in requesting the most information at the earliest time.
On TYPE=STRRNG, the starting range value must not be greater than the ending range value. If the starting value is greater, IHABLDP does not allow the structure range entry to be added to the parameter list and returns a return code of 8 and a reason code of 8.
Specify TYPE=ENDLIST to complete the building of the parameter list. Make sure that you have specified all of the requested structures and their requested ranges.
Do not attempt to change the built parameter list once you have specified TYPE=ENDLIST.