HLQ request (HLQ) for the IMS catalog API
Use the HLQ function of the IMS catalog API to acquire the high-level qualifier (HLQ) for the boot strap data set (BSDS) name for the subsequent IMS catalog API OPEN requests that require the BSDS name.
During the HLQ request, the IMS directory boot strap data set (BSDS) is found and returned in the output area. The BSDS information can then be saved and provided to the API OPEN request.
- IMS online regions of type BMP or IFP.
- IMS batch regions of type DLI, ULU, or DBB.
- z/OS® environment where an IMS control region is available on the same LPAR.
Syntax for HLQ requests
DFS3CATQ FUNCTION=HLQ,OUTPUT=(R2),HLQENV=ZOS,
IMSID=(R3)Parameters for HLQ requests
- EPADDR=ep-addr | RS-type address, or register (2-12).
- If specified as a symbol, specifies the label of a word of storage that contains the address of the load module DFS3CATQ. The application is responsible for loading module DFS3CATQ, saving its entry point address for this parameter and deleting the load module when it is no longer needed.
- HLQENV=
- Specifies the environment where the HLQ request is executed.
- BATCH
- IMS batch regions of type ULU, DLI, and DBB.
- ONLINE
- IMS online regions of type BMP and IFP.
- ZOS
- Programs that are executed by z/OS. When you use the HLQENV=ZOS parameter, the IMS control region must be up.
- IMSID=name-addr | RS-type address, or register (2-12)
- Specifies the address of the 4-byte application storage area that identifies the IMS system for the associated BSDS. When more than one IMS system is present on an LPAR, the IMSID= parameter must be paired with the HLQENV=ZOS parameter.
- MF=
- The macro form of the request.
- I
- Invokes the DFSCATQx program with an in-line parameter list. If your program is reentrant, do not use this form of the macro because reentrant code cannot be modified.
- L
- Specifies the list form of the macro.
- (E,list)
- Specifies the execute form of the macro.
list | RS-type address, or register (2-12).
- OUTPUT=out-addr | RS-type address, or register (2-12).
- Specifies the address of a 4-byte field to receive the address
of the first storage area that contains the information for the request.
Additional storage may be needed to contain the full set of information requested. Each additional area of storage is chained off of the prior one. The application is responsible for freeing the output areas when they are no longer needed.
- RETCODE=symbol | (2-12)
- Saves the return code to a storage location determined by the
specified symbol or register.
If a symbol is specified, the symbol must represent the label of a word of storage in which to save the return code.
If a register is specified, the register must contain the address of a word of storage in which to save the return code. Specify a register from 2 to 12 that is enclosed in parentheses.
Regardless of whether RETCODE is specified, IMS returns the return code in register 15.
- RSNCODE=symbol | (2-12)
- Saves the reason code to a storage location determined by the
specified symbol or register.
If a symbol is specified, the symbol must represent the label of a word of storage in which to save the reason code.
If a register is specified, the register must contain the address of a word of storage in which to save the reason code. Specify a register from 2 to 12 that is enclosed in parentheses.
Regardless of whether RSNCODE is specified, IMS returns the reason code in register 0.
Output area for HLQ requests
The returned storage of the HLQ request is consist of a 16-byte prefix and the HLQ of the BSDS required by the OPEN request.
With each successful HLQ request, DFS3CATQ acquires storage to hold the requested information. The address of the storage obtained is stored in the caller's area (see the OUTPUT= parameter).
The storage is allocated by the STORAGE macro with LOC=31 and SP=0.
More than one output area may be needed to contain all of the information requested. The address of the next output area is stored in the area. The application is responsible for freeing the output areas when they are no longer needed.
Each output area has the following format:
| Content | Description |
|---|---|
| Size | 4 bytes. The size of this storage area. |
| Address | 4 bytes. The address of the next area, or '00000000'x if this is the last area. |
| Reserved | 8 bytes. Reserved for internal use. |
| Data area | The requested data in the following format:
|
Return and reason code for HLQ requests
| Return Code | Reason Code | Meaning |
|---|---|---|
| X'00000000' | X'00000000' | Request completed successfully. |
| X'0000000C' | X'0000000C' | Valid address for the OUTPUT= variable or location was not provided. |
| X'0000000C' | X'00000010' | Valid address for the TOKEN= variable or location was not provided. |
| X'0000000C' | X'00000200' | The HLQ request was unsuccessful due to a missing or invalid parameter. |
| X'00000014' | X'00000214' | The HLQ request was unsuccessful. The specified IMS control program is not active. |
| X'00000024' | X'00000204' | The HLQ request was unsuccessful using an internal service. The request was unable to get to the catalog anchor block. |
| X'00000024' | X'00000208' | The HLQ request was unsuccessful using an internal service. The request was unable to get to the catalog directory. |
| X'00000024' | X'0000020C' | The HLQ request was unsuccessful using an internal service. A severe error occurred. |
| X'00000024' | X'00000218' | A GSCD call was performed, and the address of the SCD was not returned. |
| X'aaaabbbb' | X'cccccccc' |
An IMS or MVS service returned an unexpected return or reason code. aaaa identifies the service that was performed. bbbb is the service return code. cccccccc is the service reason code. The possible values for aaaa and the service each identifies are:
For more information about the return and reason codes that may be returned for each service, refer to the following topics in the z/OS documentation: ISGENQ — Global resource serialization ENQ service |