CIMS call

Format

Figure 0.

Parameters

aib

Specifies the application interface block (AIB) that is used for the call. This parameter is an input and output parameter.

These fields must be initialized in the AIB:

AIBID

Eye-catcher. This 8-byte field must contain DFSAIBbb.

AIBLEN

AIB lengths. This field must contain the actual length of the AIB that the application program obtained.

AIBRSNM1

Character value.

AIBSFUNC

Subfunction code. This field must contain one of the 8-byte subfunction codes as follows:

INIT

AIBRSNM2. A 4-character ID of the ODBA startup table.

CONNECT

AIBRSA1. Address of the CONNECT parameter list.

The following table shows the CIMS CONNECT parameter list format.

Table 1. CIMS CONNECT parameter list format

Offset	Length	Field	Usage description
X'00'	X'04'	Input	Count of connect request table entries.
X'04'	X'04'	Input	Address of the connect request table.

TERM

AIBRSNM2. A 4-character ID of the ODBA startup table that represents the IMS connection that is to be terminated.

TALL

Terminate all IMS connections.

Usage

The CIMS call is used by an application program that is running in an application address space to establish or terminate the ODBA environment.

INITbbbb

The CIMS subfunction INIT must be issued by the application to establish the ODBA environment in the z/OS application address space.

Optionally, AIBRSNM2 can specify the 4-character ID of the ODBA Startup table member. This member is named DFSxxxx0 where xxxx is equal to the 4-character ID. If AIBRSNM2 is specified, ODBA tries to establish a connection to the IMS specified in the DFSxxxx0 member after the ODBA environment is initialized in the z/OS application address space.

CONNECTb

Use the CIMS CONNECT call to establish multiple ODBA connections to IMS systems from the CSL Open Database Manager (ODBM).

A CIMS CONNECT call can be issued instead of, or in addition to, a CIMS INIT call. A CIMS CONNECT call will initialize ODBA if ODBA has not already been initialized. To complete initialization only, issue a CIMS CONNECT call with AIBRSA1 set to -1 (X'FFFFFFFF').

The connect request table contains one or more connect request entries in contiguous storage. Each entry contains the following fields:

• A 1- to 4-character alias name, left justified and padded on the right with blanks. The alias name is the value (cccc) taken from the startup properties table DFScccc0. This parameter is required.
• A 4-byte address of the connection properties table (DFSPRP) or 0.

  A value of 0 indicates that ODBA must load DFScccc0 to obtain the IMS connection properties. This member is constructed by specifying the DFSPRP macro in DFScccc0, and then assembling and linking the member. This member must be in the STEPLIB or JOBLIB of the ODBA application job.

  A nonzero value indicates that the caller is passing the address of the connection properties parameter table. The connection properties parameters are mapped by the DFSPRP macro.

• A 4-byte field to contain the connection request return code. The return code is one of the AIBRETRN codes.
• A 4-byte field to contain the connection request reason code. The reason code is one of the AIBREASN codes.
• A 4-byte field to contain the connection request error extension information code. The error extension contains additional diagnostic information specific to the return and reason codes.

The following table summarizes the CIMS CONNECT table entry format.

Table 2. CIMS CONNECT table entry format

Offset	Length	Field	Usage description
X'00'	X'04'	Input	1- to 4-character IMS alias name (cccc) from the startup properties table DFScccc0, where cccc is the alias name.
X'04'	X'04	Input	0 or the address of an ODBA startup properties table. A value of 0 indicates that ODBA must load a startup properties table named DFScccc0, where cccc is the supplied alias name. An address indicates that the caller is supplying the startup properties table. The table is mapped by the DFSPRP macro.
X'08'	X'04'	Output	Connect request return code for this entry.
X'0C'	X'04'	Output	Connect request reason code for this entry.
X'10'	X'04'	Output	Connect request error extension code for this entry.

TERMbbbb

The CIMS subfunction TERM can be issued to terminate one IMS connection. AIBRSNM2 specifies the 4-character ID of the startup table member that represents the IMS connection to be terminated. On completion of the TERM subfunction, the ODBA environment remains intact in the z/OS application address space.

Note: If the application that issued CIMS INIT chooses to return to the operating system following completion of the CIMS TERM, the address space will terminate with a system abend A03. This can be avoided by issuing the CIMS TALL prior to returning to the operating system

TALLbbbb

The CIMS subfunction TALL must be issued to terminate all IMS connections and terminate the ODBA environment in the application address space.