CSLDMREG: ODBM client registration request

The CSLDMREG request registers an ODBM client with ODBM.

With the CSLDMREG request, an ODBM client, such asWebSphere® Application Server for z/OS® or Db2 for z/OS, can register with an instance of ODBM.

The CSLDMREG request registers an application program with ODBM as an ODBM client. The register command must be the first request that a client issues to ODBM.

Use the CSLSCQRY request to obtain the names of all ODBMs in the IMSplex.

CSLDMREG DSECT syntax

Use the DSECT function of a CSLDMREG request to include equate (EQU) statements in your program for the CSLDMREG parameter list length and return and reason codes.

Request protocol syntax

CSLDMREG parameters

The CSLDMREG parameters specify the ODBM values required for registration with ODBM.

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

The CSLDMREG command includes the following parameters:

ECB=symbol

ECB=(r2-r12)

(Optional) - Specifies the address of a z/OS event control block (ECB) 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 invoker of the macro must issue a WAIT (or equivalent) after receiving control from CSLDMREG before using or examining any data returned by this macro (including the RETCODE and RSNCODE fields).

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

ODBMNAME=symbol

ODBMNAME=(r2-r12)

(Optional) - Specifies the 8-byte ODBM name to which to send the command registration request.

Either the ODBMNAME parameter or the RETNAME parameter, but not both, must be specified on a CSLDMREG request.

Use the ODBMNAME parameter to connect the ODBM client to a specific, known instance of ODBM.

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

OUTLEN=symbol

OUTLEN=(r2-r12)

(Required) - Specifies a 4-byte field to receive the length of the output returned by the CSLDMREG request. OUTLEN contains the length of the output pointed to by the OUTPUT= parameter.

If no output is built, the output length is zero, as is the case when an error is detected before building the output.

If the value of OUTLEN is specified as a register, the register must contain the address of the output length field. If the value of OUTLEN is specified as a symbol, the symbol must be the label of the output length field.

OUTPUT=symbol

OUTPUT=(r2-r12)

(Required) - Specifies a 4-byte field to receive the variable length output returned by the CSLDMREG request. The output length is returned in the OUTLEN= field.

If no output is built, the output address is zero, as is the case when an error is detected before building the output.

The CSLDREGO macro maps the output that is returned. The output buffer contains the ODBM version, count of the aliases, and a list of the 4-byte alias names.

The output buffer is not preallocated by the caller. Upon return from the request, this word contains the address of a buffer containing the update output.

After the ODBM client no longer needs the buffer storage, the ODBM client must release the storage by issuing the CSLSCBFR FUNC=RELEASE request.

If the value of OUTPUT is specified as a register, the register must contain the address of a field to contain the output address. If the value of OUTPUT is specified as a symbol, the symbol must be the label of a field to contain the output.

PARM=symbol

PARM=(r1-r12)

(Required) - Specifies the address of the CSLDMREG parameter list. The length of the parameter list must be equal to the parameter list length EQU value defined by DREG_PARMLN.

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

RETCODE=symbol

RETCODE=(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 (CSLDMREG) or SCI (CSLSCMSG or CSLSCRQS). If ECB is specified, the 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 and X'04' for ODBM).

If the value of RETCODE is specified as a symbol, the symbol must be the label of the return code field. If the value of RETCODE is specified as a register, the register must contain the address of the return code field.

RETNAME=symbol

RETNAME=(r2-r12)

(Optional) - Specifies the eight-byte output field to receive the ODBM name. This is the CSL member name of the target address space to which SCI sent the request.

Either the RETNAME parameter or the ODBMNAME parameter, but not both, must be specified on a CSLDMREG request.

Use the RETNAME parameter if you do not know the name of an ODBM instance or if the ODBM client does not require a connection to a specific instance of ODBM. When RETNAME is specified, SCI connects to any available instance of ODBM and returns the name of that ODBM in the RETNAME output field.

RSNCODE=symbol

RSNCODE=(r2-r12)

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

If the value of RSNCODE is specified as a symbol, the symbol must be the label of the reason code field. If the value of RSNCODE is specified as a register, the register must contain the address of the reason code field.

SCITOKEN=symbol

SCITOKEN=(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 value of SCITOKEN is specified as a register, the register must contain the address of the SCI token field. If the value of SCITOKEN is specified as a symbol, the symbol must be the label of the SCI token field.

CLSDMREG return and reason codes

The return and reason codes in the following table can be returned on a CSLDMREG macro request. The hexadecimal value 04 represents the SCI member type for ODBM.

Table 1. CSLDMREG return and reason codes
Return code	Reason code	Meaning
X'00000000'	X'00000000'	The CSLDMREG request completed successfully.
X'04000010'	X'0000401C'	The client is already registered.
X'04000010'	X'00004020'	The parameter list version of the parameter list specified on the PARM= parameter is invalid.
X'04000014'	X'0000502C'	Unable to obtain a CSLDREGO feedback area.
X'04000014'	X'0000503C'	Unable to obtain a CLNT control block.