List request (LIST) for the IMS catalog API

You can use the IMS catalog API list request to return a list of object names that match a specified object type and name.

For each successful LIST 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.

Syntax for LIST requests

Parameters for LIST 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.

If this parameter is specified, the TYPE= parameter is ignored.

DEFINITION=definition-type

If DEFINITION=BOTH is specified for the OPEN request, the LIST 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 listed. 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 listed.

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.

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 name pattern to use for the LIST request. The first two bytes of storage should contain the length of the name or pattern that follows. The 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 list 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.

If the BLDL= parameter is specified, this parameter is ignored.

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 LIST requests

With each successful LIST 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:

Table 1. Output area returned for LIST 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	8 bytes. Reserved for internal use.
Data area	The requested data, in the following format: 2 bytes The number of members returned. 2 bytes Length of information (`nn`) returned for each member. `nn` bytes Member information, mapped by the IMS ACBDIR PREFIX=BLDL macro.

Return and reason codes for LIST requests

Table 2. Return and reason codes for the DFS3CATQ macro LIST requests
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.
`X'0000000C'`	`X'0000000C'`	A 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'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'0000000C'`	`X'00000100'`	Invalid value for the FUNCTION parameter.
`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`).