Get request (GET) for the IMS catalog API

Use the GET function of the IMS catalog API to get an object definition from the IMS catalog and return the information back to the calling application.

For each successful GET request, one or more areas of storage is returned to the application that contains the requested information. The address of the first area of storage is stored at the address provided in the OUTPUT parameter. The address of the next area of storage, if any, is contained within the first area. For the last area, the address of the next area of storage is null.

The application is responsible for freeing each of these storage areas when they are no longer needed.

Restriction:

GSAM ACB or DBD control blocks cannot be retrieved from the IMS catalog by using the GET request of the IMS catalog API.

Syntax for GET requests

Parameters for GET requests

BLDL=bldr-addr | RS-type address, or register (2-12).

The address of an area in application storage where a list of object names resides. See the BLDL macro and its list-address parameter of the BLDL macro for the format and requirements for this area.

DEFINITION=definition-type

If DEFINITION=BOTH is specified for the OPEN request, the GET request must specify which data set of the IMS catalog, staging or directory, to retrieve information from:

CURRENT: The definitions of the resources that are currently active in the IMS system, that is, the definitions of the resources that are in the directory data set of the IMS catalog, are returned. This is the default value.
PENDING: The definitions of any resources that are pending activation, that is, the definitions of the resources that are in the staging data set of the IMS catalog, are returned.

EXTATTR=output-extended-attribute-type

Determines whether extended attribute metadata is returned. This parameter is valid only for the FORMAT=DBDLIB parameter.

ALL: All extended attribute metadata is returned. This is the default value.
NONE: Only the vendor section table is returned. If the vendor section table does not exist, no extended attribute metadata is not returned.

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.

FORMAT=format-type

The format in which to return the requested object definition.

ACBLIB: Return in ACBLIB format.
DBDLIB: Return in DBDLIB format.
PSBLIB: Return in PSBLIB format.

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).

NAME=name-addr | RS-type address, or register (2-12).

The address of an area in application storage describing the name or name pattern of the object to retrieve. The first 2 bytes of storage should contain the length of the name or pattern that follows.

A naming pattern can be provided by specifying a wild card mask. An asterisk can represent zero, one, or more characters in the name. A percent sign represents exactly one character in the name. To get all objects, specify only an asterisk.

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.

TOKEN=tok-addr | RS-type address, or register (2-12).

Specifies the address of a 4-byte field to receive the API token. Your program receives this token when a DFS3CATQ FUNC=OPEN macro is issued. This token must be supplied with all other macro calls that are associated with this instance of the OPEN request. The token is no longer valid after a DFS3CATQ FUNC=CLOSE macro call.

TYPE=object-type

The type of object that is requested, where object-type is one of the following values:

ANY: Any object type is requested.
DATABASE: Database types are requested.
PSB: Program specification block types are requested.

USEALIAS=YES

Returns the IMS catalog database with its alias name in the output area. This requires that a FUNCTION=HLQ or FUNCTION=OPEN,CATALIAS= call was used prior to this request.

Output area for GET requests

With each successful GET request or X'00000028' - X'00000006' (DCPLRC_INVSEG EQU) return-reason code combination (see the X'00000028' return code row in Table 2 for details), 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 might 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:

Table 1. Output area returned for GET requests
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	1 byte. Reserved for internal use.
Flags	1 byte. X`80`: EXTATTR=NONE is specified.
Size	2 bytes containing the size of each data area.
Reserved	4 bytes. Reserved for internal use.
Data area	The requested data is comprised of the following repeating elements: 4 bytes The address of the object. The object is mapped by one of the following macros: IDBD for a DBD returned in the DBDLIB format. DFSDMB for a DBD returned in the ACBLIB format. DFSIPSB for a PSB returned in the PSBLIB format. DFSPSB for a PSB returned in the ACBLIB format. 4 bytes Length of the object. 8 bytes Member name of the object.

Return and reason codes for GET requests

Table 2. Return and reason codes for the DFS3CATQ macro
Return Code	Reason Code	Meaning
`X'00000000'`	`X'00000000'`	Request completed successfully.
`X'00000004'`	`X'00000000'`	One or more list entries in the area specified by using the BLDL=`parameter` could not be found. Any entries that contain a wild card mask could not be found.
`X'0000000C'`	`X'0000000C'`	A valid address for the OUTPUT=`variable or location` was not provided.
`X'0000000C'`	`X'00000010'`	A valid address for the TOKEN=`variable or location` was not provided.
`X'0000000C'`	`X'00000018'`	One of the parameter pairs is specified: DEFINITION=CURRENT for the OPEN request and DEFINITION=PENDING for the GET request. DEFINITION=PENDING for the OPEN request and DEFINITION=CURRENT for the GET request.
`X'00000028'`	`X'nnnnnnnn'`	An attempt by the GET request to use an internal service was unsuccessful. The return code contains the service's return code (`nnnnnnnn`). The reason code `nnnnnnnn` can be from the DFS3CPL return codes. The associated labels and meaning are explained in the following list: X'00000001' (DCPLRC_SIZE EQU) Insufficient output buffer size. X'00000002' (DCPLRC_INVMBR EQU) Invalid DBD or PSB member. X'00000003' (DCPLRC_VIRSEG EQU) Invalid virtually paired segment name. X'00000004' (DCPLRC_SECIDX EQU) Invalid secondary index name. X'00000005' (DCPLRC_INVDBD EQU) Invalid DBD name. X'00000006' (DCPLRC_INVSEG EQU) Invalid segment name.* *The API will generate output for this error-reason code combination. The application is responsible for freeing the output areas when they are no longer needed. X'00000007' (DCPLRC_BLDERR EQU) Error building catalog segments. X'00000008' (DCPLRC_INVACB EQU) Invalid ACBLIB member. X'00000009' (DCPLRC_ISAM EQU) Invalid ISAM. X'0000000A' (DCPLRC_ACBERR EQU) Error processing ACBLIB member. X'0000FFFF' (DCPLRC_UNKERR EQU) Unknown error.
`X'0000002C'`	X'00000034'	Storage for the decoder output area could not be obtained.
`X'00080004'`	`X'yyyyzzzz'`	The request was unsuccessful during BLDL macro processing. The reason code contains the BLDL return code (`yyyy`) and reason code (`zzzz`).
`X'00080008'`	`X'yyyyzzzz'`	The request was unsuccessful during FIND macro processing. The reason code contains the FIND return code (`yyyy`) and reason code (`zzzz`).