Open request (OPEN) for the IMS catalog API

Use the IMS catalog API OPEN function to allocate either the IMS directory data set or the IMS directory staging data set for subsequent API calls to list or retrieve the database and program view resources that are defined to IMS.

During the OPEN request, the IMS directory boot strap data set (BSDS) is allocated, opened, read, closed, and unallocated. If you specify DEFINITION=CURRENT to retrieve the definitions that are currently active in the IMS system, the IMS directory data set remains allocated until the CLOSE request. If you specify DEFINITION=PENDING to retrieve any definitions that are waiting to be activated, the staging data set of the IMS directory remains allocated until the CLOSE request.

When you make an OPEN request, the DFS3CATQ macro dynamically allocates the BSDS and directory data sets as needed. It allocates a block of virtual storage that is used to communicate information across subsequent GET and LIST requests. The address of the block is stored at the address that is provided in the TOKEN parameter. The same token must be used for subsequent requests.

You can issue a CLOSE request to free the allocation.

You can make multiple IMS catalog API OPEN requests and allow them to remain in use before you issue a CLOSE request for any specified OPEN request.

To have multiple IMS catalog API allocations active at the same time:
  1. Provide a different TOKEN address for each OPEN request.
  2. Specify that token for each subsequent GET or LIST request against that IMS catalog.
  3. Specify that token on the CLOSE request to free the allocation of that IMS directory data set.

Up to 36 OPEN requests can be active at one time if the system-generated DDname is available and there are no environment limits.

Syntax for OPEN requests

Read syntax diagramSkip visual syntax diagramDFS3CATQFUNCTION=OPEN,BSDSHLQ= bsds-addr,CATALIAS= alias-addr,DEFINITION=CURRENT,DEFINITION=PENDING,DEFINITION=BOTH,EPADDR= ep-addr,MF=I,MF=L,MF=(E, list),PLISTVER= parmlist_version,RETCODE= symbol|( 2-12),RSNCODE= symbol|( 2-12),RSNTEXT= symbol|( 2-12),TOKEN= tok-addr

Parameters for OPEN requests

BSDSHLQ=bsds-addr | RS-type address, or register (2-12).
The address of an area in application storage that contains the high-level qualifier prefix for the IMS boot strap data set. The first two bytes of storage must contain the length of the high-level qualifier prefix that follows.

The qualifier '.BSDS' is appended to the high-level qualifier prefix value to form the full name of the IMS boot strap data set.

If both BSDSHLQ and CATALIAS are specified, IMS locates the IMS directory by using the high-level qualifier that is defined in the CATDSHLQ DFSMDA member that corresponds to the CATALIAS value. The DFSMDA member must exist either in a library allocated as //IMSDALIB, or in the //JOBLIB or //STEPLIB libraries. The IMS catalog API first searches in //IMSDALIB, if it exists, for the MDA members. If IMS catalog API does not find the DFSMDA member, the IMS catalog API uses the high-level qualifier at the BSDSHLQ location.

CATALIAS=alias-addr

The address of an area in application storage that contains the 4-character IMS catalog alias name that is specified on the DDNAME parameter of the CATDSHLQ DFSMDA macro statement that contains the high-level qualifier of the IMS directory data sets.

If both BSDSHLQ and CATALIAS are specified, IMS locates the IMS directory by using the high-level qualifier that is defined in the CATDSHLQ DFSMDA member that corresponds to the CATALIAS value. The DFSMDA member must exist either in a library allocated as //IMSDALIB, or in the //JOBLIB or //STEPLIB libraries. The IMS catalog API first searches in //IMSDALIB, if it exists, for the MDA members. If IMS catalog API does not find the DFSMDA member, the IMS catalog API uses the high-level qualifier at the BSDSHLQ location.

If a symbol is specified, you must specify RSNTEXT.

DEFINITION=definition-type
BOTH
The definitions of any resources in the CURRENT or PENDING data sets of the IMS directory are returned or listed.
CURRENT
The definitions of the resources that are currently active in the IMS system are returned or listed. This is the default.
PENDING
The definitions of any resources in the staging data set of the IMS directory that are pending activation are returned or 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).

PLISTVER=parmlist_version
The version of the OPEN function parameter list.
1
Specifies version 1 of the parameter list for the OPEN function.

Version 1 is the default.

2
Specifies version 2 of the parameter list for the OPEN function.

Version 2 of the parameter list includes the CATALIAS, PLISTVER, and RSNTEXT parameters and is larger in size than version 1.

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

RSNTEXT=symbol | (2-12)
Saves the reason text to a storage location determined by the specified symbol or register. The reason text storage area must be defined with 120 bytes long.

If a symbol is specified, the symbol must represent the label of a word of storage in which to save the reason text.

If a register is specified, the register must contain the address of a word of storage in which to save the reason text. Specify a register from 2 to 12 that is enclosed in parentheses.

If a symbol is specified, you must specify CATALIAS.

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.

Return and reason codes

Table 1. Return and reason codes for the DFS3CATQ macro OPEN requests
Return Code Reason Code Meaning
X'00000000' X'00000000' Request completed successfully.
Start of changeX'0000000C'End of change Start of changeX'00000004'End of change Start of changeRequest block level error.End of change
X'0000000C' X'00000008' BSDS qualifier length error.
X'0000000C' X'0000000C' A valid address for the OUTPUT= variable or location was not provided.
X'0000000C' X'00000010' The address provided for the TOKEN= variable or location was not valid.
Start of changeX'0000000C'End of change Start of changeX'00000020'End of change Start of changeThe address provided for the RSNTEXT= variable or location was not valid.End of change
X'00000014' X'yyyyzzzz' The OPEN request was unsuccessful using an internal service. The reason code contains the service's return code (yyyy) and reason code (zzzz).
X'00000018' X'nnnnnnnn' OPEN was not successful. The reason code is the return code from the OPEN macro.
X'00000024' X'0000002C' The OPEN request failed due to no available DDname for the allocation.
X'00000024' X'00000030' The token area contains invalid data.
X'0000002C' X'nnnnnnnn’ OPEN boot strap data set (BSDS) in output mode was not successful. The reason code is the return code from the OPEN macro.
X'00000030' X'yyyyzzzz' Dynamic allocation of IMS directory data set was not successful. The reason code contains S99ERROR (yyyy) and S99INFO (zzzz) from the DYNALLOC macro.
X'00000034' X'yyyyzzzz' Dynamic deallocation of boot strap data set (BSDS) was not successful. The reason code contains S99ERROR (yyyy) and S99INFO (zzzz) from the DYNALLOC macro.
X'00000038' X'yyyyzzzz' Dynamic allocation of concatenated directory data set was not successful. The reason code contains S99ERROR (yyyy) and S99INFO (zzzz) from the DYNALLOC macro.
X'0000003C' X'00000024' The member specified with the CATALIAS= parameter was not found.
X'0000003C' X'00000028' An error occurred when the LOAD macro attempted to load the member specified with the CATALIAS= parameter.
X'0000003C' X'00000104' The contents of the DFSMDA specified with the CATALIAS= parameter are invalid.
X'0000003C' X'00000108' Storage for the DFSMDA in IMSDALIB could not be obtained.
X'00000044' X'yyyyzzzz' Dynamic allocation of boot strap data set (BSDS) was not successful. The reason code contains S99ERROR (yyyy) and S99INFO (zzzz) from the DYNALLOC macro.