Type-2 AOI

Type-2 AO exit routines (DFSAOE00 and other AOIE type exit routines)

IMS calls AOIE type exit routines for:

• IMS system messages destined for the master terminal
• Commands entered from a terminal and the responses to those commands
• Commands issued from an AO application program using the ICMD call
• IMS internal commands

IMS does not call AOIE type exit routines for:

• Command responses to internal commands
• Command responses to an AO application program ICMD call
• Commands issued from an AO application using the CMD call
• System messages for which the destination is not the master terminal

You can write AOIE type exit routines to complete the following tasks:

• Modify the text of IMS system messages. An AOIE type exit routine can also add up to 20 bytes of additional text to the end of a message.
• Delete IMS system messages. In a DBCTL environment, if a message is deleted or modified, IMS does not keep the original message sent to the z/OS® system console.
• Direct any system message, command, or command response to an AO application program.
• Filter the system messages sent to the secondary master terminal.
• Start a BMP job (for example, an AO application program). AOIE type exit routines can issue SVC 34 to start a BMP. You can use the APARM parameter of the EXEC statement to pass information to the AO application program. The AO application program can issue the DL/I INQY call to retrieve the value specified for the APARM parameter. You can use the START command to override the APARM parameter of the EXEC statement.

AOIE type exit routines must use IMS AOI callable services to communicate with an AO application program. AOI callable services let you:

• Direct messages, commands, and command responses to an AO application program
• Cancel messages previously directed to an AO application program but not yet sent

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-2 AO application program (GMSG, ICMD, and RCMD)

An AO application program can issue DL/I calls to:

• Retrieve messages from AOIE type exit routine (or DFSAOUE0)
• Issue a subset of IMS commands
• Retrieve the responses to those commands

Retrieving messages (GMSG call)

AOIE type exit routines do not use the IMS message queues to route messages to an AO application program. Thus, your AO application program can retrieve messages when you cannot or do not want to use the message queues.

The AO application program retrieves messages using the GMSG call, which associates an AOI token name with a message. The application program passes an 8-byte AOI token to IMS, and IMS returns to the program only those messages associated with the AOI token. By using different AOI tokens, AOIE type exit routines can direct messages to different AO applications programs. This use of the AOI token is similar to the use of transaction names using the other AO exit routine, DFSAOUE0.

The GMSG call, specifying an 8-byte AOI token, retrieves the first segment of a message associated with the token. Subsequent GMSG calls, with no AOI token specified, retrieve the second through the last segments of a multi-segment message, one segment at a time. If a program needs all segments of a multi-segment message, it must issue GMSG (with no AOI token) until all segments are retrieved before issuing another GMSG call with an AOI token. When the program issues a new GMSG call with an AOI token, IMS discards all remaining message segments from the previous call.

An application program can specify a wait in the GMSG call. If there are no messages currently available for the specified AOI token, the application is put into a wait state until a message is available. The decision to wait is specified by the program, unlike a WFI (wait-for-input) transaction where the wait is specified in the transaction definition.

Issuing commands and retrieving command responses (ICMD and RCMD calls)

The ICMD call issues an IMS command and retrieves the first command response segment if one exists. The RCMD call retrieves subsequent command response segments. When an ICMD call results in a multi-segment command response, you might not want to retrieve all segments. If you need all segments, you must issue RCMD calls until all segments are retrieved before issuing another ICMD call. When the program issues a new ICMD call, IMS discards all remaining message segments from the previous call.

Using AIBTDLI

The GMSG, ICMD, and RCMD calls do not require the AO application program to pass a PCB to IMS. The calls use the application interface block (AIB) interface (AIBTDLI), which lets an application issue DL/I calls without a PCB address. The AIBTDLI interface also lets IMS pass unique return and reason codes to the application in the AIB.

Security

You can secure the ICMD call using RACF® (or an equivalent product), the IMS Command Authorization exit routine (DFSCCMD0), or both. RACF lets you specify which commands an application program can issue. DFSCCMD0 and RACF also allow you to check authorizations during ICMD call processing.

Recovery

The messages directed from AOIE type exit routines to the type-2 AO application program are not written to the IMS message queues. Therefore, messages directed to the AO application program cannot be recovered during IMS restart.

Supported application program environments

The following table shows the types of application programs that can issue GMSG, ICMD, and RCMD calls for different IMS environments. In addition, these calls are supported for CPI Communications driven applications programs.