CSLDMI: ODBM application program interface

Application programs written in assembler and running on z/OS® can access IMS databases managed by IMS DB in DBCTL and DB/DC systems in an IMSplex by using the CSL Open Database Manager (ODBM) CSLDMI API.

The CSLDMI API supports all of the DL/I calls supported by the IMS ODBA interface, global and local transaction processing, and security.

Prior to issuing the CSLDMI request, the ODBM client must first register with ODBM by issuing the CSLDMREG request.

The CSLDMI API includes the following function calls:

BACKOUT

Backs out a local unit of work for local transactions. A local unit of work consists of a single APSB call that has work, such as DL/I calls, associated with the APSB thread.

COMMIT

Commits a local unit of work for local transactions. A local unit of work consists of a single APSB call that has work, such as DL/I calls, associated with the APSB thread.

DSECT

Includes equate (EQU) statements in an application program for the length of a CSLDMI parameter list and for CSLDMI return and reason codes.

ODBMCI

To issue DL/I calls to IMS databases, use the ODBMCI function. DL/I calls are passed to IMS by using the DLIFUNC parameter of the ODBMCI function.

Prior to issuing an ODBMCI function call, you must ensure that the AIB fields are coded appropriately for the DL/I calls that are being passed in the DLIFUNC parameter.

The following parameters are specific to the ODBMCI function and cannot be specified on other CSLDMI function calls:

AIB
CLIENTID
CLIENTIDLEN
CTXTOKEN
DLIFUNC
GROUPNAME=
GROUPNAMELEN=
IOAREA
IOAREALEN
PCB
PCBLEN
SECTKNLEN
SECTOKEN
SSA1 through SSA15
SSA1LEN through SSA15LEN
URTOKEN
USERID=
USERIDLEN=

READYSYNCPT

Prepares for syncpoint processing for each of the multiple APSB calls within a global unit of work.

The READYSYNCPT function of the CSLDMI API must called before initiating syncpoint processing for global transactions, such as those that contain multiple APSB threads within a single unit of work. The ODBM client must issue FUNC=READYSYNCPT for each APSB that is represented by an APSBTOKEN in a global unit of work (UOW). This pertains to the URTOKEN parameter. See the URTOKEN parameter for more description.

Before initiating syncpoint processing, the caller must issue FUNC=READYSYNCPT for each APSB call in the global UOW. CSLDMI uses an APSB token (APSBTOKEN) to represent each APSB call.

Subsections:

CSLDMI FUNC=BACKOUT syntax
CSLDMI FUNC=COMMIT syntax
CSLDMI FUNC=DSECT syntax
CSLDMI FUNC=ODBMCI syntax
CSLDMI FUNC=READYSYNCPT syntax
CSLDMI function parameters
CSLDMI return and reason codes

CSLDMI FUNC=BACKOUT syntax

CSLDMI FUNC=COMMIT syntax

CSLDMI FUNC=DSECT syntax

CSLDMI FUNC=ODBMCI syntax

CSLDMI FUNC=READYSYNCPT syntax

CSLDMI function parameters

The CSLDMI parameters specify the ODBM values required for communicating with ODBM and accessing IMS databases.

The addresses can be specified as either a symbol or a register from 2 to 12.

Parameters that are supported only when the ODBMCI function is specified are noted in the description of the parameters. Parameters that are not noted as being supported by ODBMCI only, can be specified on all CSLDMI functions other than DSECT.

The following parameters can be specified on one or more functions of the CSLDMI API:

AIB=symbol | (r2-r12)

(Required) - Specifies the address of the application interface block (AIB). The AIB parameter is required on both input to and output from ODBM. This parameter is supported only on the ODBMCI function call.

When the SCI message protocol (PROTOCOL=MSG) is specified on a CSLDMI request, ODBM returns the address of the AIB in the DDIR_DMIRAIBPTR field of the ODBM directive parameter list, which is mapped by the CSLDMDIR macro.

Prior to issuing CSLDMI FUNC=ODBMCI, the AIB fields required by each DL/I call being passed on the DLIFUNC parameter must be set. The fields of the AIB are mapped by the DFSAIB macro and described in Specifying the AIB mask for ODBA applications.

If the AIB is specified as a register, the register must contain the address of the AIB area. If the AIB is specified as a symbol, the symbol must be the label of the AIB area.

APSBTOKEN=symbol | (r2-r12)

(Required) - Specifies an address for a 16-byte ODBM APSB token. An APSB token is returned by CSLDMI on the initial APSB thread request and is required on all subsequent calls targeted to this thread.

On an APSB request, APSBTOKEN specifies the address of the field to receive the token from ODBM. The length of APSBTOKEN field must be 16 bytes as defined by DMI_APSBTKNLEN in the CSLDMI macro.

For all subsequent requests associated to this thread, APSBTOKEN specifies the address of this 16-byte token.

When the SCI message protocol (PROTOCOL=MSG) is specified on a CSLDMI request, ODBM returns the address of the APSB token in the DDIR_DMIRAPSBTPTR field of the ODBM directive parameter list, which is mapped by the CSLDMDIR macro.

If the APSBTOKEN parameter is specified as a register, the register must contain the address of the token field. If the APSBTOKEN parameter is specified as a symbol, the symbol must be the label of the token field.

CLIENTID=symbol | (r2-r12)

(Optional) - Specifies the end user client application ID as defined by the end user client.

If the CLIENTID parameter is specified as a register, the register must contain the address of the client ID field. If the CLIENTID parameter is specified as a symbol, the symbol must be the label of the client ID field.

CLIENTIDLEN=symbol | (r2-r12)

(Required when CLIENTID is specified) - Specifies the length of the client ID.

If the CLIENTIDLEN parameter is specified as a register, the register must contain the length of the client ID. If the CLIENTIDLEN parameter is specified as a symbol, the symbol must be the label of a fullword containing the length of the client ID.

CTXTOKEN=symbol | (r2-r12)

(Optional) - Specifies a 16-byte RRMS Context Services context token. This may be the native context token, or a private token obtained by calling the Context Services Begin_Context service (CTXBEGC).

CTXTOKEN can be used to setup a global unit of work made up of multiple APSB calls within one commit scope on a single LPAR. If specified, the same CTXTOKEN must be included on each APSB call within the global unit of work.

CTXTOKEN and URTOKEN will be mutually exclusive if you do not install the PTF PH23803. After you install PH23803, if the call only specifies a CTXTOKEN, caller must ensure that the private context token specified on the CTXTOKEN has been disassociated from the current dispatchable unit, such as a TCB, prior to passing the private context token to ODBM. This is done using Context Services Switch_Context (CSXSWCH). ODBM associates this context to its DU for the duration of the call and disassociates it on return to the ODBM client.

If the caller specifies a CTXTOKEN and a URTOKEN, the context token can be native or private. The caller does NOT need to disassociate from the current DU. ODBM will express interest in the CTXTOKEN and create a cascaded UR child. The caller is responsible for initiating sync point processing using the appropriate z/OS Resource Recovery Services services, such as, ATRAPRP, ATRACMT, ATRCMIT, ATRBACK, and so forth. The ODBM client must establish an RRS WID (work identifier) if needed. Usually, the WID (Work Identifier) is an XID. ATRSWID2 is used to set a work identifier and the WID is set based on the context token specified on this CTXTOKEN parameter.

If the CTXTOKEN parameter is specified as a register, the register must contain the address of the private context token field. If the CTXTOKEN parameter is specified as a symbol, the symbol must be the label of the private context token field.

DLIFUNC=symbol | (r2-r12)

(Required) - Specifies the 4-byte DL/I call. Any DL/I call that is supported by the Open Database Access (ODBA) callable interface can be specified. This parameter is supported only on the ODBMCI function call.

Prior to issuing CSLDMI FUNC=ODBMCI DLIFUNC, the AIB fields required by each DL/I call being passed on the DLIFUNC parameter must be set. The fields of the AIB are mapped by the DFSAIB macro and described in Specifying the AIB mask for ODBA applications in IMS Version 15.3 Application Programming.

If the DLIFUNC parameter is specified as a register, the register must contain the address of the DLI function code. If the DLIFUNC parameter is specified as a symbol, the symbol must be the label of the DLI function code.

ECB=symbol | (r2-r12)

(Optional) - Specifies an MVS event control block (ECB) that is used for asynchronous requests. When the request is complete, the ECB specified is posted.

If an ECB is not specified, the task is suspended until the request is complete. If an ECB is specified, the ODBM client that invokes the CSLDMI macro must invoke the z/OS WAIT macro (or equivalent) after receiving control from CSLDMI before using or examining any data returned by CSLDMI, including the RETCODE and RSNCODE fields.

If the ECB parameter is specified as a register, the register must contain the address of the ECB. If the ECB parameter is specified as a symbol, the symbol must denote the start of the ECB storage.

GROUPNAME=symbol | (r2-r12)

(Optional) - Specifies a group name for RACF® or an equivalent security product. The group name pertains to the APSB call only (DLIFUNC=APSB) and is ignored for all other DL/I calls.

If the GROUPNAME parameter is specified as a register, the register must contain the address of the group name field. If the GROUPNAME parameter is specified as a symbol, the symbol must be the label of the group name field.

GROUPNAMELEN=symbol | (r2-r12)

(Required when GROUPNAME is specified) - Specifies the length of the group name.

If the GROUPNAMELEN parameter is specified as a register, the register must contain the length of the group name. If the GROUPNAMELEN parameter is specified as a symbol, the symbol must be the label of a fullword containing the length of the group name.

IOAREA=symbol | (r2-r12)

(Conditionally required) - Specifies an I/O area that is used for the input or output data related to a database DL/I call. The IOAREA and IOAREALEN parameters are required only when a DL/I call that requires input data or that returns output data is specified on the DLIFUNC parameter. This parameter is supported only on the ODBMCI function call.

When the SCI message protocol (PROTOCOL=MSG) is specified on a CSLDMI request, ODBM returns the address of the I/O area in the DDIR_DMIRIOAPT field of the ODBM directive parameter list, which is mapped by the CSLDMDIR macro.

If the IOAREA parameter is specified as a register, the register must contain the address of the I/O area. If the IOAREA parameter is specified as a symbol, the symbol must be the label of the I/O area.

IOAREALEN=symbol | (r2-r12)

(Conditionally required) - Specifies the length of the I/O area specified by the IOAREA parameter. The IOAREA and IOAREALEN parameters are required only when a DL/I call that requires input or that returns output is specified on the DLIFUNC parameter. This parameter is supported only on the ODBMCI function call.

The length specified on the IOAREALEN parameter must also be specified on the AIBOALEN field of the AIB mask. For information about the AIB mask, see Specifying the AIB mask .

If the IOAREALEN parameter is specified as a register, the register must contain the length of the I/O area. If the IOAREALEN parameter is specified as a symbol, the symbol must be the label of a fullword containing the length of the I/O area.

ODBMNAME=symbol | (r2-r12)

(Required) - Specifies the 8-byte ODBM name to which to the CSLDMI request is to be sent.

If the ODBMNAME parameter is specified as a symbol, the symbol must be the label of the ODBM field. If the ODBMNAME parameter is specified as a register, the register must contain the address of the ODBM name field.

PARM=symbol | (r2-r12)

(Required) - Specifies the address CSLDMI parameter list. The length of the parameter list must be at least as long as the value assigned to DMI_PARMLN in the CSLDMI macro.

Use CSLDMI FUNC=DSECT to include equate (EQU) statements in your application program for the length of the CSLDMI parameter list

If the value of PARM is specified as a register, the register must contain the address of the parameter list. If the value of PARM is specified as a symbol, the symbol must denote the start of the parameter list storage.

PCB=symbol | (r2-r12)

(Optional) - An output parameter that specifies the address of a fullword storage area to receive the address of the program communication block (PCB) returned by IMS after processing a DL/I call. The PCB contains the status codes related to a DL/I call and other fields. This parameter is supported only on the ODBMCI function call.

The PCB storage is not preallocated by the caller. Upon return from the request, the address in the PCB parameter contains the address of a storage buffer that contains the PCB. After the ODBM client is finished with the PCB, the ODBM client must release the PCB storage buffer by issuing the SCI request CSLSCBFR FUNC=RELEASE.

When the SCI message protocol (PROTOCOL=MSG) is specified on a CSLDMI request, ODBM returns the address of the PCB storage in the DDIR_DMIRPCBPTR field of the ODBM directive parameter list, which is mapped by the CSLDMDIR macro.

If specified as a register, the register must contain the address of a fullword to contain the address of the PCB. If specified as a symbol, the symbol must be the label of a fullword to contain the address of the PCB.

PCBLEN=symbol | (r2-r12)

(Conditionally required) - Specifies the length of the PCB returned by DL/I call processing. The PCBLEN parameter is required when the PCB parameter is specified. This parameter is supported only on the ODBMCI function call.

If specified as a register, the register must contain the address of a fullword to contain the length of the PCB. If specified as a symbol, the symbol must be the label of a fullword to contain the length of the PCB.

PROTOCOL=MSG | RQST

(Optional) - Specifies the SCI protocol for sending the request to ODBM.

MSG: Specifies that CSLDMI sends input requests to ODBM by using the SCI message protocol, which uses a one-way send of the data to the other IMSplex members and does not support output parameters. The ODBM client does not wait for output from ODBM and any output generated by the requests that use the MSG protocol is handled asynchronously.
RQST: Specifies that CSLDMI sends input requests to ODBM by using the SCI request protocol. The SCI request protocol supports both input and output parameters. The ODBM client waits for output from ODBM and process it synchronously. RQST is the default.

RETCODE=symbol | (r2-r12)

(Required) - Specifies a 4-byte field to receive the return code on output. ODBM return codes are defined in the CSLDRR. SCI return codes are defined in CSLSRR.

The return code can be from ODBM (CSLDMI) or SCI (CSLSCMSG or CSLSCRQS). If an ECB is specified, the value of RETCODE is not valid until the ECB is posted. All return codes contain the SCI-member-type indicator for either SCI or ODBM in the high order byte (X'01' for SCI or X'04' for ODBM).

RQSTTKN1=symbol | (r2-r12)

(Conditionally optional) - Specifies a 16-byte user-generated request token that correlates an output response to its associated input request for asynchronous processing. ODBM returns the address of this token in the DDIR_DMIRQT1PTR field of the ODBM directive parameter list that is mapped by CSLDMDIR.

RQSTTKN1 is supported only when the SCI message protocol is specified by PROTOCOL=MSG.

If specified as a register, the register must contain the address of the request token field. If specified as a symbol, the symbol must be the label of the request token field. The request token field must be 16 bytes in length, left justified, and padded with blanks if necessary.

RSNCODE=symbol | (r2-r12)

(Required) - Specifies a 4-byte field to receive the reason code on output. ODBM reason codes are defined in the CSLDRR macro. SCI reason codes are defined in CSLSRR.

SCITOKEN=symbol | (r2-r12)

(Required) - Specifies a 16-byte field containing the SCI token. This token uniquely identifies this connection to SCI. The SCI token is returned by a successful CSLSCREG FUNC=REGISTER request.

If the SCITOKEN parameter is specified as a register, the register must contain the address of the SCI token field. If the SCITOKEN parameter is specified as a symbol, the symbol must be the label of the SCI token field.

SECTKNLEN=symbol | (r2-r12)

(Conditionally required) - Specifies the length of the security token. The SECTKNLEN parameter is required when the SECTOKEN parameter is specified. This parameter is supported only on the ODBMCI function call.

If the SECTKNLEN parameter is specified as a register, the register must contain the length of the security token. If the SECTKNLEN parameter is specified as a symbol, the symbol must be the label of a fullword containing the length of the security token.

SECTOKEN=symbol | (r2-r12)

(Conditionally optional) - Specifies the address of a variable length security token that is used for security checking by RACF or an equivalent security product. The security token applies only to the APSB DL/I call that is specified by DLIFUNC=APSB. The security token is ignored for all other DL/I calls. This parameter is supported only on the ODBMCI function call. This security token is used only if the client address space is an authorized caller. If the client address space is unauthorized, the user ID is obtained automatically from z/OS control blocks.

The security token must be a security object. For example, if RACF is used, the security token must be a RACO (RACF Object). ODBM invokes RACROUTE REQUEST=VERIFY,ENVIR=CREATE with ENVRIN= to establish a security environment with a RACF accessor environment element (ACEE) for the APSB thread. IMS uses the ACEE during ODBA or RAS security authorization for the PSB.

If the SECTOKEN parameter is specified as a register, the register must contain the address of the security token field. If the SECTOKEN parameter is specified as a symbol, the symbol must be the label of the security token field.

SSAn=symbol | (r2-r12)

(Optional) - Specifies the segment search arguments (SSAs) for a DL/I call. A maximum of 15 SSAs can be specified: SSA1 through SSA15. This parameter is supported only on the ODBMCI function call.

If the parameters SSA1 through SSA15 are specified as registers, each register must contain the address of an SSA. If the parameters SSA1 through SSA15 parameters are specified as symbols, each symbol must be the label of a fullword that contains the address of an SSA.

SSAnLEN=symbol | (r2-r12)

(Conditionally required) - Specifies the length of the corresponding SSA list area. For every SSAn parameter specified, a corresponding SSAnLEN parameter is required, specified as SSA1LEN up through SSA15LEN. This parameter is supported only on the ODBMCI function call.

If the parameters SSA1LEN through SSA15LEN are specified as registers, the registers must contain the length of the SSA list areas. If the parameters SSA1LEN through SSA15LEN are specified as symbols, the symbols must be the labels of a fullword containing the length of the SSA list areas.

URTOKEN=symbol | (r2-r12)

(Optional) - Specifies a 16-byte RRS parent unit of recovery (UR) token obtained by calling the RRS Express_UR_Interest service that supports cascaded transactions (ATREINT2 or higher).

A URTOKEN is required in order to setup a global unit of work made up of multiple APSB calls within one commit scope on a single LPAR. If specified, the same URTOKEN must be included on each initial APSB call within the global unit of work.

CTXTOKEN and URTOKEN will be mutually exclusive before you install the PTF PH23803. After you install PH23803, if the call only specifies a URTOKEN, caller must ensure that the UR token supports cascading. ODBM will create a new context and create a cascaded child UR. If the caller specifies a URTOKEN and a CTXTOKEN, ODBM will express interest in the CTXTOKEN, create a new context, and create a cascaded UR child. The caller is responsible for initiating sync point processing using the appropriate RRS services, such as, ATRAPRP, ATRACMT, ATRABCK, ATRCMIT and so forth. Caller must establish an RRS WID (work identifier) if needed. Usually, the WID is an XID. ATRSWID2 is used to set a work identifier. The WID is set based on the parent UR token specified on this URTOKEN parameter.

If the URTOKEN parameter is specified as a register, the register must contain the address of the RRS UR token field. If the URTOKEN parameter is specified as a symbol, the symbol must be the label of the RRS UR token field.

USERID=symbol | (r2-r12)

(Optional) - Specifies the user ID to be used by RACF or an equivalent security product. Use this parameter only if your client address space has been authorized for this request. If your client is not authorized, the user ID is obtained automatically from z/OS control blocks. The user ID pertains to the APSB call only (DLIFUNC=APSB) and is ignored for all other DL/I calls.

If the USERID parameter is specified as a register, the register must contain the address of the user ID field. If the USERID parameter is specified as a symbol, the symbol must be the label of the user ID field.

USERIDLEN=symbol | (r2-r12)

(Required when USERID is specified) - Specifies the length of the user ID.

If the USERIDLEN parameter is specified as a register, the register must contain the length of the user ID. If the USERIDLEN parameter is specified as a symbol, the symbol must be the label of a fullword containing the length of the user ID.

CSLDMI return and reason codes

The return and reason codes in the following table can be returned on a CSLDMI macro request.

Table 1. CSLDMI return and reason codes
Return code	Reason code	Meaning
X'00000000'	X'00000000'	The CSLDMI request completed successfully.
X'04000004'	X'00001004'	The Input user exit rejected the request.
X'04000008'	X'00002018'	Invalid AIB parameter.
	X'0000201C'	Invalid value is specified in the AIBRSNM1 field of the AIB mask.
	X'00002020'	Unsupported DL/I function.
	X'00002024'	The Input user exit incorrectly set the AIBOALEN field of the IAB mask to a value that is greater than the value that is specified on the IOAREALEN parameter.
	X'00002060'	The DRDA code point sent by the client was not found in the table of ODBM supported DRDA code points.
X'04000010'	X'00004000'	Unable to locate the alias name.
X'04000010'	X'00004004'	The client is not registered.
	X'00004008'	The data store was not acquired.
X'04000014'	X'00005004'	Unable to obtain an APSB control block.
	X'00005008'	Unable to obtain an AIB control block.
	X'00005014'	Hash table ADD failed for APSB block.
	X'00005018'	Hash table FIND failed for APSB block.
	X'00005034'	OUTPUT buffer allocation failed.
	X'00005040'	RRS0_ASSOCCTX failed.
	X'00005044'	RRS0_DISCTX failed.
	X'00005048'	RRS0_COMMIT3_DMIR failed.
	X'0000504C'	RRS0_SUSI failed.
	X'00005050'	RRS0_BACKOUT3_DMIR failed.
	X'00005054'	APSB token length error.
	X'00005058'	APSB hash table RELEASE failed.
	X'0000505C'	RRS0_ASSOCCTX3 failed.
	X'00005060'	RRS0_CASCADE3 failed.
	X'00005064'	RRS0_GETCTX2 failed.
	X'00005068'	RRS0_ENDCTX2 failed.
	X'0000506C'	SEC0_CREATE call failed.
	X'00005070'	SEC0_DELETE call failed.
	X'00005074'	An APSB call failed to schedule a PSB.
	X'00005078'	PSB Name error.
	X'00005080'	PAPL block allocation failed.
	X'00005084'	RRS not active for global transaction.
	X'0000507C'	Failed to obtain DMI IOA storage.
	X'00005094'	BPETCBSW to an ORRS TCB failed.
	X'00005098'	BPETCBSW to an ODRA TCB failed.
	X'0000509C'	Failed to obtain an ORRS TTE.