CSLOMI: API request

With the CSLOMI request, your AOP client can communicate with a z/OS® address space that acts as an OM AOP client. You can then issue OM requests and send QUERY commands to OM.

With the CSLOMI request, a z/OS automated operator client can issue an IMS command to or request OM-specific information from an OM. The CSLOMI macro interface is designed for use by system management address spaces that receive input from a workstation or other z/OS address space and must pass the request to OM. In this case the workstation application builds the input string and passes it to the z/OS address space. The z/OS address space passes the input string to OM on the INPUT= parameter.

Commands which are submitted through the OM API or REXX SPOC API use the address space identifier (ASID) USERID for authorization.

Commands which are submitted from a program using the OM API while executing in a TSO session use the TSO USERID for authorization.

Commands which are submitted from a program using the OM API while executing in a message processing program (MPP) region or batch message processing program (BMP) region use the IMS MPP/BMP dependent region USERID for authorization. In this environment, the actual transaction userid can be used for authorization if the user's installation uses the IMS Build Security Environment exit routine (DFSBSEX0) or OTMA/APPC SECURITY FULL (for example, the user's installation issues the /SECURE OTMA/APPC FULL command).

CSLOMI syntax

The syntax for CSLOMI can vary, depending on how the automated operator client wants to receive the command response. If the client does not have an input exit and wants to receive the command output as a response, use the request syntax. If the client does have an input exit and wants to receive the command output as a message, use the message syntax.

CSLOMI request protocol syntax

For automated clients that want to wait for output from the OM request, use this syntax.

After control is returned to the client (if ECB is not specified), or the ECB is posted (if an ECB is specified), the response is available to the client.

CSLOMI message protocol syntax

For automated clients that want to receive command output through their user exit, use this syntax:

The response is passed back to the client using the SCI Input exit. The client must have specified an SCI Input exit (INPUTEXIT=) on the SCI registration request (CSLSCREG) to receive a response.

CSLOMI Input= parameter syntax

For other applications or workstations that do not communicate directly with OM, use this syntax.

This syntax is used for the INPUT= parameter. The application builds the command or query, and passes it to a z/OS address space that communicates with OM directly.

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

INLEN=symbol

INLEN=(r2-r12)

(Required) - Specifies the length of the input buffer.

INPUT=symbol

INPUT=(r2-r12)

(Required) - Specifies the address of the input buffer.

The following shows an example of the input buffer that is passed to CSLOMI. The input buffer is the character field MYINPUT and specifies three parameters: a command string of QRY TRAN SHOW(ALL), a timeout value of 360 seconds, and a route list consisting of one element, IMSA:

CSLOMI FUNC=OMAPI,INPUT=MYINPUT,INLEN=INPUTLEN
INPUTLEN DC    A(MYINPUTL)
MYINPUT  DC    C'CMD (QRY TRAN SHOW(ALL) TIMEOUT(360) ROUTE(IMSA)'
MYINPUTL EQU   *-MYINPUT

OUTLEN=symbol

OUTLEN=(r2-r12)

(Required for RQST) - Specifies a 4-byte field to receive the length of the output returned by the CSLOMI 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=symbol

OUTPUT=(r2-r12)

(Required) - Specifies a field to receive the variable length output returned by the CSLOMI 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) - Specifies the CSLOMI parameter list. The length of the parameter list must be equal to the parameter list length EQU value defined by OI_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 (CSLOMI) 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.

USERID=symbol

USERID=(r2-r12)

(Optional) - Specifies the 8-byte user ID that should be used for security checking for the command and keyword combination. This user ID is used only if the client address space is an authorized caller. If the client address space is unauthorized, the user ID is obtained from z/OS control blocks. This user ID is intended for use by authorized system management address spaces that can issue an OM request on behalf of another address space or remote client. In this case, the user ID of the client address space is not the user ID of the actual client, so it must be passed to OM. This parameter must be 8 bytes, left-justified, and, if necessary, padded with blanks.

CSLOMI Input= parameters

The parameters for the CSLOMI input option are for applications and workstations that do not communicate directly with OM.

CMD(command)

(Required if QUERY is not specified) - Specifies the command input buffer. This can be any IMS command that can be specified through the OM API. The first character of the command does not need to be a command recognition character (for example, /). The command recognition character does not control command routing in OM. The ROUTE keyword is used to control which IMSplex members receive a command. If a command recognition character is entered in the command string, it is ignored. The first character in the command is considered a command recognition character if it is not a character between A-Z (either uppercase or lowercase).

CMDLANG(cmdlang)

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 text in the OM default language is returned.

OPTION(AOPOUTPUT)

(Optional, valid only for CMD()) - Specify the AOPOUTPUT option to return the format identifiers (FID) in the output from command processing clients. For example, when a type-1 /DISPLAY command is sent to an IMS command processing client, you can request that the FID be returned in each output line. The FID indicates to an AOI program how to map the line of output. The FID can be useful if you are converting existing AOI programs to OM AOI programs.

QUERY(querytype)

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 list of clients is returned encapsulated in <cmdclients> </cmdclients> tags. querytype can be one of the following.

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

ROUTE(routelist)

(Optional) - Specifies a route list that identifies OM clients (for example, IMS control regions) in the IMSplex to which the command is sent. In the list, the clients are separated by commas. If you do not specify ROUTE, OM routes to all clients that are registered and ready to process commands.

To explicitly route the command to all command processing clients that have registered for and are ready to process commands, specify ROUTE(*).
To route the command to the first command processing client which is READY and has MASTER capability, specify ROUTE(%). With ROUTE(%), OM routes the command to only one command processing client that OM chooses.

RQSTTKN2(requesttoken2)

(Optional) - Specifies a 16-byte user generated request token that is used to associate the request response with the request for asynchronous processing. RQSTTKN2 can include A-Z, 0-9, or printable characters (not case sensitive), except &, <, and >. OM returns the request token encapsulated in the <rqsttkn2></rqsttkn2> tags in the XML output. OM converts any invalid data to periods (.) before returning XML output to the originating 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_CQRT2PTR.

TIMEOUT(timeoutvalue )

(Optional) - Specifies a 4-byte command timeout value in seconds. If the TIMEOUT value is reached during OM command processing before all clients have responded to the command, OM terminates the command and returns all available responses. If too small a value is specified, an incomplete response is returned. The TIMEOUT value ensures a response is returned even if a client processing the command cannot respond. The TIMEOUT keyword is ignored if no CMD keyword is specified. If a command is requested but no timeout value is specified, a timeout value of 5 minutes is used.

CSLOMI return and reason codes

The following table lists the return and reason codes that can be returned on a CSLOMI macro request. Also included is the meaning of a reason code (that is, what possibly caused it).

Table 1. CSLOMI return and reason codes
Return code	Reason code	Meaning
X'00000000'	X'00000000'	The request completed successfully.
X'02000004'	Any code	This return code represents a warning. All or part of the request might have completed successfully. Additional information is returned with the response to the request.
	X'00001000'	The specified command timed out before all of the command response information could be collected. One or more clients might not be responding, or a client might have needed more time to process the command. If a TIMEOUT value is specified, ensure the value is long enough to allow for the command to be processed. All command response information that is collected prior to the timeout is returned.
	X'00001004'	The INPUT exit rejected the command contained in the CMD field. The command was not processed.
	X'00001008'	The client (specified in the corresponding XML <mbr></mbr> tags in the <cmderr> section) was specified in the ROUTE list for the command specified in the CMD field. The command was not routed to the command processing client because the client is not the master.
	X'00001010'	The text file could not be loaded in the language specified on the CMDLANG parameter. The default language is used.
	X'00001014'	The command completed with warnings. Check the return codes. At least one client member returned a return code 4 to the Operations Manager. All other clients returned a return code not greater than 4. If the command was successfully processed by one command processing client as designed, but all other command processing clients to which the command was routed received reason code X'00001000' (IRSN_NOTMSTR) for return code X'00000004', then the overall OM return and reason codes will be: WARNING (X'02000004') WARNING (X'00001014') Refer to the completion codes returned on the request for further information.
X'02000008'	Any code	This return code represents a parameter error. The request was not processed due to the error.
	X'00002000'	The command specified in the CMD field is invalid.
	X'00002004'	The primary keyword specified in the CMD field is invalid with the command specified.
	X'00002028'	An invalid keyword was specified in the CMD field.
	X'0000202C'	BPE detected an unknown positional parameter in the command in the CMD field.
	X'00002030'	A keyword was specified with an equal sign (KEYWORD=) when a sublist was expected (KEYWORD()) in the command in the CMD field.
	X'00002034'	An incomplete keyword or keyword parameter was specified in the command in the CMD field.
	X'00002038'	A keyword is missing from the command in the CMD field.
	X'0000203C'	The value of a keyword parameter specified in the command was invalid.
	X'00002040'	A duplicate keyword was specified in the command in the CMD field.
	X'00002044'	Text containing the syntax error is returned in the XML <message></message> tags.
	X'00002048'	More than one filter was specified.
	X'00002050'	The caller of the service attempted to pass an invalid parameter list. The request is rejected.
X'0200000C'	Any code	This return code represents a list error. The request might or might not have been processed due to the error. Refer to the XML tag <cmderr> section and the completion codes for each command processing client listed in the XML tag <cmdrspdata> section.
	X'00003000'	The command was routed to multiple clients. At least one client was able to process the request successfully and return either command response data or a response message. Refer to the completion codes returned on the request for further information.
	X'00003004'	The command was routed to multiple clients. None of the clients was able to process the request successfully. No command response data or response messages were returned by any client.
	X'00003008'	The command was routed to multiple clients. None of the clients that processed the command returned a return code 0 and reason code 0 to OM. At least one command client returned either command response data or a response message.
	X'0000300C'	The command was routed to multiple clients. Not all of the clients that processed the command returned a return code 0 and reason code 0 to the OM. Also, at least one client returned a return code 4. Refer to the completion codes returned on the request for additional information.
X'02000010'	Any code	This return code represents an environmental error. The request could not be processed at this time due to the current environment. This condition might be temporary.
	X'00004000'	The command contained in the CMD field could not be processed by the client indicated in the corresponding XML <mbr></mbr> tags in the <cmderr> section because the client was not yet ready to process commands.
	X'00004004'	The command contained in the CMD field could not be processed by the client indicated in the corresponding XML <mbr></mbr> tags in the <cmderr> section because the client was not registered for the command.
	X'00004008'	The command contained in the CMD field could not be processed by the client indicated in the corresponding XML <mbr></mbr> tags in the <cmderr> section because the client is not active in the IMSplex.
	X'0000400C'	The command contained in the CMD field could not be processed by the client indicated in the corresponding XML <mbr></mbr> tags in the <cmderr> section because the client registered for the command with invalid PADEF grammar.
	X'00004010'	The command contained in the CMD field could not be processed. The client that issued the command is not authorized. Examine the <cmdsecerr> section in the XML file to determine why the client is not authorized.
	X'00004014'	A data set allocation error occurred; the data set specified by the CMDTEXT= DSN parameter could not be allocated.
	X'00004018'	A data set read error occurred; a member in the data set specified by the CMDTEXT= DSN could not be read. The member name is CSLOT concatenated with the 3-character CMDLANG value.
	X'00004020'	The parameter list version is invalid.
X'02000014'	Any code	This return code represents a system error. An internal error occurred, and the command was not processed.
	X'00005000'	An OM internal error occurred. Due to a storage shortage, OM was unable to allocate a CMD block to process the command in the CMD field.
	X'00005004'	An OM internal error occurred. Due to a storage shortage, OM was unable to allocate a CRSP block to process the command in the CMD field.
	X'00005008'	An OM internal error occurred. Due to a storage shortage, OM was unable to allocate the command input buffer to process the command in the CMD field.
	X'0000500C'	An OM internal error occurred. OM was unable to obtain the VERB latch while processing the command in the CMD field.
	X'00005010'	An OM internal error occurred. Due to a storage shortage, OM was unable to obtain storage for the parsed output blocks to parse the command in the CMD field.
	X'00005014'	An OM internal error occurred. OM was unable to add the CMD block to the command instance hash table while processing the command in the CMD field.
	X'00005018'	An OM internal error occurred. OM was unable to find the CMD block in the command instance hash table while processing the command in the CMD field.
	X'0000501C'	An OM internal error occurred. OM was unable to scan for the CMD block in the command instance hash table while processing the command in the CMD field.
	X'00005020'	An OM internal error occurred. OM was unable to obtain a system AWE while processing the command in the CMD field. The command was not processed by the command processing client. Refer to the <cmderr> section in the XML file for the member name of the command processing client.
	X'00005024'	An OM internal error occurred. OM was unable to queue a system AWE while processing the commanding the CMD field. The command was not processed by the command processing client. Refer to the <cmderr> section of the XML file for the member name of the command processing client.
	X'00005028'	An OM internal error occurred. OM was unable to parse the command contained in the CMD field due to a BPEPARSE internal error.
	X'0000502C'	An OM internal error occurred. The command output header allocation failed.
	X'00005030'	An OM internal error occurred. The command output response allocation failed.
	X'00005034'	An OM internal error occurred. The OUTPUT buffer allocation failed.
	X'00005038'	An OM internal error occurred. The VERB hash table add failed.
	X'0000503C'	An OM internal error occurred. The CLNT block could not be obtained.
	X'00005040'	An OM internal error occurred. The CSLSCQRY request failed.
	X'00005044'	An OM internal error occurred. OM could not obtain storage to pass a copy of the command grammar to the BPEPARSE service.