Sending messages to other IMS application programs

A program-to-program switch occurs when an IMS application running in an IMS dependent region sends a message to another IMS application running in an IMS dependent region.

To send a request to another IMS transaction and receive the response in the same unit of work, use the DL/I ICAL request. For more information, see Synchronous program switch requests.

You can issue a program-to-program switch to send and receive messages with any of the following types of IMS applications:

message processing program (MPP)
batch message processing (BMP) program
Java™ message processing (JMP) program
Java batch processing (JBP) program

To send a message to another online program, use an alternate program communication block (PCB) in a similar way as when sending messages to alternate terminals. If you send messages to only one application program, then you can define the alternate PCB with the transaction code for that application program during PSB generation. If you send messages to more than one application program, you can define the alternate PCB as modifiable.

If you use an alternate modifiable PCB, IMS TM makes a security check when you issue the CHNG call to set the destination of the alternate modifiable PCB. The terminal that enters the transaction code that causes the message switch must be authorized to enter the transaction code that the CHNG call places in the alternate modifiable PCB. IMS TM does not check for security when you issue the ISRT call.

When an IMS TM application program issues a CHNG call, the Resource Access Control Facility (RACF®) is invoked and a check is made to determine whether the originating terminal is authorized for the transaction code that was issued. If, instead of using the CHNG call, the program issues an ISRT call against a preset alternate PCB, no security check is made, regardless of the environment.

When you issue a program-to-program message switch, you have the same considerations as when you communicate with a logical terminal. Keep in mind the following points:

Create an I/O area large enough to hold the largest segment that you are sending.
Use an alternate PCB, not the TP PCB, to send the message.
Issue a CHNG call before the ISRT call to place the transaction code of the program in the first field of the alternate PCB. If the alternate PCB was set to this transaction code in the PSBGEN, issue the ISRT call.
IMS TM must know the transaction code. Define it at system definition.
A nonconversational program can do a program-to-program message switch to another nonconversational program, but not to a conversational program.
A conversational program can do a program-to-program message switch to either another conversational program or a nonconversational program.

Open Transaction Manager Access (OTMA) program-to-program switching has the following restrictions:

In a shared queues environment that has both synchronous APPC/OTMA support (AOS=Y on the DFSDCxxx PROCLIB member) and RRS support (RRS=Y on the startup procedure) enabled, an application program running on a back-end IMS system that initiates an outbound APPC protected conversation with another IMS system is restricted to a single program-to-program switch.
If an application program performs multiple program-to-program switches after allocating an APPC outbound protected conversation on another IMS system, the results are unpredictable and can include a WAIT-RRS/PC condition in the message processing region (MPR).

A message switch to another conversational program transfers the scratchpad area (SPA) and the responsibility to respond to the originating terminal to the new application program. A message switch to a nonconversational program does not change the responsibilities of the conversational program. The conversational program must still return the SPA to IMS TM (if the SPA has been modified) and must respond to the originating terminal. The following tables show the format for an output message to an application program.

Table 1. Message Format for program-to-program message switch for AIBTDLI, ASMTDLI, CBLTDLI, CEETDLI, CTDLI, and PASTDLI interfaces
Field Name	Field Length
LL	2
Z1	1
Z2	1
Text	Variable

Table 2. Message format for program-to-program message switch for the PLITDLI interface
Field Name	Field Length
LLLL	4
Z1	1
Z2	1
Text	Variable

The format is the same as for output messages to terminals. Z1 and Z2 are fields that must contain binary zeros. These fields are reserved for IMS. The text field contains the message segment that you want to send to the application program.

If the program that is processing the message expects the transaction code, include the transaction code of the recipient program as part of the message text of the first segment of the message, because IMS TM does not automatically include the transaction code in the first segment of a switched message. Including the transaction code in the message text of the first segment keeps the first segments of all messages in the same format, regardless of whether they are sent from terminals or other programs.