CSLOMCMD: command request

By using the CSLOMCMD request, your AOP client application that is running on the host can issue requests and send commands to OM.

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

CSLOMCMD syntax

The syntax for CSLOMCMD can vary depending on what the automated operator client intends to perform.

DSECT syntax

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


>>-CSLOMCMD--FUNC=DSECT----------------------------------------><

Request protocol syntax

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


>>-CSLOMCMD--FUNC=COMMAND--+---------+--CMD=cmdinput------------>
                           '-ECB=ecb-'                 

>--CMDLEN=cmdinputlen--+------------------+--OUTPUT=output------>
                       '-OPTION=aopoutput-'                  

>--OUTLEN=outputlen--------------------------------------------->

>--+----------------------------------------+------------------->
   '-ROUTE=routelist--ROUTELEN=routelistlen-'   

                               .-TIMEOUT=300----------.   
>--+------------------------+--+----------------------+--------->
   '-RQSTTKN1=requesttoken1-'  '-TIMEOUT=timeoutvalue-'   

                                 .-PROTOCOL=RQST-.   
>--+---------------+--PARM=parm--+---------------+-------------->
   '-USERID=userid-'                                 

>--RETCODE=returncode--RSNCODE=reasoncode----------------------->

>--+--------------------+--+----------------------+------------->
   '-RETNAME=returnname-'  '-RETTOKEN=returntoken-'   

>--SCITOKEN=scitoken-------------------------------------------><

The response is passed back to the client after the request is completed.

Message protocol syntax

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


>>-CSLOMCMD--FUNC=COMMAND--CMD=cmdinput--CMDLEN=cmdinputlen----->

>--+------------------+----------------------------------------->
   '-OPTION=aopoutput-'   

>--+----------------------------------------+------------------->
   '-ROUTE=routelist--ROUTELEN=routelistlen-'   

                               .-TIMEOUT=300----------.   
>--+------------------------+--+----------------------+--------->
   '-RQSTTKN1=requesttoken1-'  '-TIMEOUT=timeoutvalue-'   

>--+---------------+--PARM=parm--PROTOCOL=MSG------------------->
   '-USERID=userid-'                            

>--RETCODE=returncode--RSNCODE=reasoncode----------------------->

>--+--------------------+--+----------------------+------------->
   '-RETNAME=returnname-'  '-RETTOKEN=returntoken-'   

>--SCITOKEN=scitoken-------------------------------------------><

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.

CSLOMCMD parameters

CMD=symbol

CMD=(r2-r12)

(Required) - 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 controls 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).

CMDLEN=symbol

CMDLEN=(r2-r12)

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

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

OPTION=aopoutput

OPTION=(r2-r12)

(Optional) - Use 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.

If OPTION is specified as a register, the register must contain the option value. For example, the value of AOPOUTPUT is 1. Therefore, the register must contain a 1.

The CSLOMCMD request contains the equate for the value of AOPOUTPUT. The DSECTS for the output of CSLOMCMD when OPTION=AOPOUTPUT are described in the DISPLAY macro in the IMS.SDFSMAC data set.

OUTLEN=symbol

OUTLEN=(r2-r12)

(Required for RQST) - Specifies a 4-byte field to receive the length of the output returned by the CSLOMCMD 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 for RQST) - Specifies a 4-byte field to receive the address of the variable length output returned by the CSLOMCMD 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=(r1-r12)

(Required) - Specifies the CSLOMCMD parameter list. The length of the parameter list must be equal to the parameter list length EQU value defined by OCMD_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 (CSLOMCMD) 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.

ROUTE=symbol

ROUTE=(r2-r12)

(Optional) - Specifies a route list that identifies OM clients (for example, IMS control regions) in the IMSplex to which the command is sent. If you do not specify ROUTE, OM routes to all clients that are registered and ready to process commands. If the route list specified consists of a SYSID of an OM client that is not registered for the specified command, then the command will fail with return and reason codes indicating the client is not registered for the command. For example, if a QUERY IMSPLEX command with ROUTE=IMS1 is processed by the OM address space and the IMS control region IMS1 is not registered for this command, then the command fails.

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.

Note: Use commas to separate a list of client names.

ROUTELEN=symbol

ROUTELEN=(r2-r12)

(Optional) - Specifies the length of the list specified in the ROUTE= parameter.

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.

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.

TIMEOUT=timeoutvalue

TIMEOUT=symbol

TIMEOUT=(r2-r12)

(Optional) - Specifies a 4-byte command timeout value in seconds. If the TIMEOUT value is reached during OM command processing and 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 is unable to 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.

If TIMEOUT is specified as a symbol, the symbol must be an EQU symbol equated to the timeout value. If TIMEOUT is specified as a number, the number must be the timeout value.

USERID=symbol

USERID=(r2-r12)

(Optional) - Specifies the 8-byte 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 unauthorized, the user ID is obtained automatically 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-aligned, and, if necessary, padded with blanks.

Table 1. CSLOMCMD return and reason codes
Return code	Reason code	Meaning
X'00000000'	X'00000000'	The request completed successfully.
X'02000004'	Any code	This return code indicates 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 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 you specified the TIMEOUT option, make sure that the interval is long enough to allow the command to process. All command response information that is collected prior to the timeout is returned. This reason code is also returned if CSL members such as SCI or RM are not active on the local or remote z/OS image and cannot process the request or return a response. To obtain more information, issue QUERY IMSPLEX to determine which CSL members are inactive. Restart those members and re-issue the request. If this reason code is returned after an INIT OLC or TERM OLC command, issue QUERY MEMBER to determine the online change status of the IMS systems participating in the online change and take action based on their status.
	X'00001004'	The INPUT exit rejected the command specified 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'00001014'	Command completed with warnings. Check return codes. At least one client member returned return code 4 to the Operations Manager. All other clients returned a return code not greater than 4. Refer to the completion codes returned on the request for further information. 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 either explicitly (in other words, the user specified a route list) or implicitly (in other words, the user did not specify a route list so the command was routed to ALL) received reason code x'00001000' (IRSN_NOTMSTR) for return code x'00000004', then the overall OM return/reason codes will be WARNING (02000004) / WARNING (00001014)
X'02000008'	Any code	This return code indicates 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 command specified in the CMD field contains a keyword that is invalid with that command.
	X'00002028'	The command string specified in the CMD field contains an invalid keyword.
	X'0000202C'	BPE detected an unknown positional parameter in the command string specified in the CMD field.
	X'00002030'	The command string specified in the CMD field contains a keyword with an equals sign when a sublist was expected. For example, `keyword=` was specified instead of `keyword()`.
	X'00002034'	The command string specified in the CMD field contains an incomplete keyword or keyword parameter.
	X'00002038'	The command string specified in the CMD field is missing a keyword.
	X'0000203C'	The command string specified in the CMD field contains an invalid keyword parameter.
	X'00002040'	The command string specified in the CMD field contains a duplicate keyword.
	X'00002044'	The command contains invalid syntax. Text containing the syntax error is returned in the <message></message> XML tags in the error log.
	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 indicates a list error. The request might or might not have processed. Refer to the <cmderr> section and the completion codes for each command processing client listed in the <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 to the SPOC. Refer to the completion codes, CC field, for further information.
	X'00003004'	The command was routed to multiple clients. None of the clients were able to process the request successfully. No command response data or response messages were returned.
	X'00003008'	The command was routed to multiple clients. None of the clients that processed the command returned a return code and reason code to the 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'00003010'	There are no active clients in the route list. Refer to message CSLN022I.
X'02000010'	Any code	This return code indicates an environmental error. The request could not be processed due to the current environment. This condition might be temporary.
	X'00004000'	The command specified in the CMD field could not be processed by the client indicated in the corresponding <mbr></mbr> tags in the <cmderr> section because the client was not yet ready to process commands.
	X'00004004'	The command specified 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 specified 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 specified 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 an invalid PADEF grammar.
	X'00004010'	The command specified in the CMD field could not be processed. The client that issued the command is not authorized. Examine the <cmdsecerr> section in the error log to determine why the client is not authorized.
	X'00004020'	This version of the parameter list is invalid.
X'02000014'	Any code	This return code indicates a system error. An internal error occurred. The command was not processed.
	X'00005000'	An internal OM error occurred while allocating a CMD block for processing of the command specified in the CMD field. Contact IBM® Software Support.
	X'00005004'	An internal OM error occurred while allocating a CRSP block to process the command specified in the CMD field. Contact IBM Software Support.
	X'00005008'	An internal OM error occurred while allocating the command input buffer to process the command specified in the CMD field. Contact IBM Software Support.
	X'0000500C'	An internal OM error occurred while processing of the command specified in the CMD field. Contact IBM Software Support.
	X'00005010'	An internal OM error occurred while obtaining storage for the parsed output blocks to parse the command specified in the CMD field. Contact IBM Software Support.
	X'00005014'	An internal OM error occurred while adding the CMD block to the command instance hash table during processing of the command specified in the CMD field. Contact IBM Software Support.
	X'00005018'	An internal OM error occurred while accessing the CMD block in the command instance hash table during processing of the command specified in the CMD field. Contact IBM Software Support.
	X'0000501C'	An internal OM error occurred while scanning for the CMD block in the command instance hash table during processing of the command specified in the CMD field. Contact IBM Software Support.
	X'00005020'	An internal OM error occurred while processing the command specified in the CMD field. The command was not processed by the command processing client. See the <cmderr> section of the error log for the member name of the command processing client, and contact IBM Software Support.
	X'00005024'	An internal OM error occurred while processing the command specified in the CMD field. The command was not processed by the command processing client. See the <cmderr> section for the member name of the command processing client, and contact IBM Software Support.
	X'00005028'	An internal OM error occurred while parsing the command specified in the CMD field. Contact IBM Software Support.