CSLOMQRY: query request

CSLOMQRY parameters

CMDLANG=cmdlang

(Optional) - The language to be used for IMS command text that is returned on the request. This value defaults to the default established for the OM system specified on the OM startup parameter CMDLANG=. Currently the only accepted value is ENU for US English. If an invalid language is specified in OM, the default language is returned.

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 CSLOMQRY before using or examining any data returned by this macro (including the RETCODE and RSNCODE fields).

OUTLEN=symbol

OUTLEN=(r2-r12)

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

The output length is zero if no output is built, for example, if an error is detected before any output can be built.

OUTPUT=output

OUTPUT=(r2-r12)

(Required) - Specifies a field to receive the variable length output returned by the CSLOMQRY request. The output contains the command response output. The output length is returned in the OUTLEN= field.

The output address is zero if no output was built, for example, if an error was detected before any output could be built.

The output buffer is not preallocated by the caller. After the request returns it, this word contains the address of a buffer containing the update output. It is the caller's responsibility to release this storage by issuing the CSLSCBFR FUNC=RELEASE request when it is finished with the storage. The length of the output is returned in the OUTLEN= field.

PARM=symbol

PARM=(r2-r12)

(Required) - Four-byte input parameter that specifies the address of the storage used by the request to pass the parameters to SCI. The length of the parameter list must be equal to the parameter list length EQU value defined by OQRY_PARMLN.

PROTOCOL=RQST

PROTOCOL=MSG

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

• RQST - Send command to OM using the SCI request protocol.
• MSG - Send command to OM using the SCI message protocol.

RETCODE=symbol

RETCODE=(r2-r12)

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

The return code can be from OM (CSLOMQRY) 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, OM, or RM in the high order byte (X'01' for SCI, X'02' for OM, X'03' for RM).

RETNAME=symbol

RETNAME=(r2-r12)

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

RETTOKEN=symbol

RETTOKEN=(r2-r12)

(Optional) - Specifies a 16-byte output field to receive the OM SCI token returned to the caller. This is the OM SCI token for the target address space to which the request was sent.

RQSTTKN1=symbol

RQSTTKN1=(r2-r12)

(Optional) - Specifies a 16-byte user generated request token that is used to associate the request response with the request for asynchronous processing. RQSTTKN1 can include A-Z, 0-9, or printable characters (not case sensitive), except &, <, and >. OM returns the request token encapsulated in the <rqsttkn1></rqsttkn1> tags in the XML output. OM converts any invalid data to periods (.) before returning XML output to the client. For PROTOCOL=MSG requests, OM also returns the address of this token in the OM directive parameter list (mapped by CSLOMDIR macro) in the field ODIR_CQRT1PTR. This parameter must be 16 bytes and, if necessary, padded with blanks.

RSNCODE=symbol

RSNCODE=(r2-r12)

(Required) - Specifies a 4-byte field to receive the reason code on output. OM reason codes are defined in the CSLORR. SCI reason codes are defined in CSLSRR. Possible reason codes are described in the following table.

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.

TYPE=CMDCLIENTS

TYPE=CMDSYNTAX

(Required) - Four-byte input parameter that specifies the type of query to be performed by OM.

CMDCLIENTS

Requests that OM return a list of all clients (for example, IMS control regions) that have registered to OM for command processing.

The clients are returned encapsulated in <cmdclients> </cmdclients> tags.

• <mbr name=membername>

  The member name is the name of the client address space.

  • <typ> </typ>

    The member type is the type of the client address space.

  • <styp> </styp>

    The member subtype is the subtype of the client address space.

  • <vsn> </vsn>

    The member version is the version of the client address space.

  • <jobname> </jobname>

    The client jobname is the jobname or the started task for the client address space.

• </mbr>

CMDSYNTAX

Requests that OM return a list of the XML representing the command syntax for selected commands registered with OM. Additionally, the translatable text associated with the command syntax is returned.

The command syntax XML is returned encapsulated in <cmdsyntax> </cmdsyntax> tags. The command syntax DTD is returned encapsulated in <cmddtd> </cmddtd> tags. The command syntax translatable text is returned encapsulated in <cmdtext> </cmdtext> tags.

The command syntax and translatable text that is returned as a result of the CSLOMQRY QUERY TYPE(CMDSYNTAX) request includes information for type-2 commands.

CSLOMQRY return and reason codes

The following table lists the return and reason code combinations that can be returned on a CSLOMQRY request and that are unique to the CSLOMQRY request. Also included is the meaning of a reason code (that is, what possibly caused it).