Type-1 AOI

Type-1 AO exit routine (DFSAOUE0)

IMS calls the type-1 exit routine, DFSAOUE0, for:

• System messages destined for the master terminal
• A subset of operator-entered commands
• Associated command responses

DFSAOUE0 can examine these messages and commands before IMS sends or executes them. IMS does not call DFSAOUE0 for system messages destined for terminals other than the master terminal or for certain commands and command responses.

DFSAOUE0 can handle both single-segment and multi-segment messages. You can write DFSAOUE0 to do the following:

• Modify IMS system messages. In addition to modifying a message, DFSAOUE0 can add up to 20 bytes of text to the end of a message. A copy of the modified message can be sent to an alternate destination.

  Messages issued by IMS after a command has been entered (for example, the DFS058command in progress message) are not really messages; they are command responses and cannot be modified.

• Delete an IMS system message and, optionally, send a copy of the message to an alternate destination.
• Ignore selected segments of a message or an entire message.
• Send a copy of system messages, commands, or command responses to an alternate destination.
• Send a new message to an alternate destination in response to receiving a system message, command, or command response.
• Modify a copy of a command or command response and send the copy to an alternate destination. Note that, unlike system messages, the exit routine can only modify a copy of commands and command responses.
• Enter a transaction to be placed on a message queue. This function lets DFSAOUE0 schedule an AO application program. For example, after receiving startup messages DFS680 and DFS994I, DFSAOUE0 could invoke an AO application program to enter a series of commands to start the network.
  Restriction: In a shared-queues environment, any transactions to be processed by the local IMS subsystem (rather than using the shared queues) must be defined as SERIAL. These transactions cannot be processed by other IMS subsystems in the sysplex.
• Request the edited command buffer (when the input is a command) to determine which command parameters succeeded or failed.

DFSAOUE0 can modify or delete system messages only. It can modify or delete the system message that the original destination (the master terminal) receives. It can also send a modified copy to an alternate destination. You cannot, however, use DFSAOUE0 to modify or delete the original command or command response. You can use it to modify a copy of a command or command response that it sends to an alternate destination, but not the copy that the primary destination receives.

Your AO exit routine must be a standalone, 31-bit, reentrant module.

Specify your exit requirements by linking the exit routines you want to use in the IMS.SDFSRESL concatenation. You can specify both type-1 and type-2 AO exit routines.

Type-1 AO application program (GU, GN, CMD and GCMD)

An AO application program can:

• Issue DL/I calls to retrieve messages from DFSAOUE0 (or AOIE type exit routines)
• Issue a subset of IMS commands
• Retrieve the responses to those commands

Retrieving messages (GU and GN call)

An AO application program receives control when IMS enqueues a message with the appropriate transaction code. The AO application program retrieves the message from DFSAOUE0 by issuing GU and GN calls.

Issuing commands and retrieving command responses (CMD and GCMD)

The AO application program issues a command using the CMD call. You can only use the CMD call if you also use the I/O PCB. PCB status codes indicate the results of a CMD call.

If there are more than one command response segments, the first one is returned to the I/O area. Use the GCMD call to retrieve subsequent segments. This call, similar to a GN call, places subsequent command response segments in the I/O area.

Security

You can secure the CMD call by using RACF® (or an equivalent product), the IMS Command Authorization exit routine (DFSCCMD0), or a combination of RACF and the exit routine. With the AOI= parameter on the TRANSACT system definition macro, you can specify which programs can issue operator commands. With RACF or DFSCCMD0, you can define which commands an AOI application program can issue.

Recovery

IMS puts messages sent from DFSAOUE0 to the AO application program on the IMS message queue. Therefore, all messages are recoverable at IMS restart.

Supported application program environments

The following table shows the types of application programs that can issue CMD and GCMD calls, by IMS environment.