Command exit routine

The Command exit routine allows external subsystem commands to be entered from IMS terminals and Automated Operator Interface (AOI) applications.

IMS activates the optional external subsystem Command exit routine when IMS discovers the subsystem's unique command recognition character (CRC) as the first non-blank character in the text portion of the /SSR command.

IMS passes the command output destination name (LTERM name) to the exit routine. The external subsystem can send a command response to this destination by using the IMS Message Service.

For commands from an AOI program or from an input-only device not associated with an output device, the output destination is the IMS MTO; otherwise it is the inputting terminal.

IMS also provides the user ID associated with the command, if any, that the external subsystem might use for security authorization checking.

IMS sends message DFS3612I to the inputting terminal if an /SSR command is entered and a Command exit routine was not provided by the external subsystem.

Subsections:

Activating the routine

The exit routine is activated in key 7, supervisor state. The EEVT prefix (EEVTP) indicates a control region environment (control region TCB). The following table explains the contents of the EPL.

Table 1. EPL contents

Offset

Offset (decimal) Content
X'0' 0 Address of the parameter count field. The count field contains the value F'5'.
X'4' 4 Address of EEVT prefix.
X'8' 8 Address of the variable length external subsystem command input. See the next table for the format of the command input.
X'C' 12 Address of the 8-byte alphanumeric destination name (that is, LTERM name) where the command response message, if any, is to be sent. The name is left justified and padded with blanks on the right.
X'10' 16 Address of the 8-character user ID associated with the command input message. The user ID is left justified and padded with blanks on the right. If IMS extended security (SIGNON|SIGNOFF) is not active, or the inputting terminal did not sign on, the user ID field contains the output destination LTERM name.
X'14' 20 Address of the 8-byte RACF® group name for the user ID that entered the command. The name is left justified and padded with blanks on the right. The area contains blanks if RACF checking is not in effect.
Table 2. Command input format
Offset Offset (decimal) Name Length/Alignment Description
X'0' 0 MSGLL 2 record length
X'2' 2 MSGZZ 2 reserved length
X'4' 4 CRC 1 command recognition character
X'5' 5 CMDDATA nnn external subsystem command

Contents of register 15 on return

Processing of return codes received from the exit routine:
Return code Meaning
0 Command exit routine successful. The Command exit routine accepted the command input message.
4 Command exit routine unsuccessful. The Command exit routine rejected the command input message.
20 Should not occur.