IMS Resource Adapter Reroute Support Update
This TechNote is an update to an earlier TechNote that described how reroute worked in previous versions of the IMS resource adapter. This TechNote describes how undelivered output messages are rerouted using versions 2.2.5, 22.214.171.124 and 126.96.36.199.2 of the IMS resource adapter.
To obtain the functionality described by this TechNote, the above versions of the IMS resource adapter must be used with IMS Connect and IMS with the following APARs applied:
- IMS Connect v2.2 with APAR PK12012 and IMS v8.1 with APAR PK09542
- IMS Connect v9.1 with APAR PK12013 and IMS v9.1 with APAR PK09543
There are three cases that this enhancement applies to: Undelivered messages from Program-to-Program switching, undelivered messages from IMS application programs that return multiple output messages, and rerouting by Open Transaction Manager Access (OTMA) when IMS Connect is not available.
Case 1: Program-to-Program switching
The IMS resource adapter supports both commit mode 1 and commit mode 0 interactions with IMS. A transaction that is scheduled by these interactions can request a program-to-program switch which results in the scheduling of one or more additional transactions. For more background information for program-to-program switch please see:
In normal circumstances and when reroute is set to TRUE, the primary output of an IMS interaction is returned to the Java client and the secondary output from a program-to-program switch application is queued on the TPIPE associated with the reroute destination.
The following detailed scenarios describe how secondary output is rerouted when the reRoute property is set to TRUE:
- Commit Mode 1. Secondary output from a program-to-program switch will be rerouted if it is spawned by a SYNC_SEND_RECEIVE interaction with commit mode 1 and syncLevel NONE. Regardless of whether the primary output is returned to the Java client or discarded due to execution timeout, IMS Connect considers the secondary output messages as undeliverable and will queue them to the TPIPE associated with the reroute destination.
- Commit Mode 0. Since syncLevel CONFIRM is required for commit mode 0 interactions, the IMS resource adapter internally issues an ACK to IMS Connect after receiving the primary output. A very small timeout value is set internally on the ACK. The IMS resource adapter then waits until the timeout occurs to return the primary output to the Java client. After timeout occurs, since the IMS resource adapter only processes one output per interaction, all secondary output messages are considered undeliverable and are queued to the TPIPE associated with the reroute destination.
If timeout doesn’t occur on the ACK of the primary output message, and instead IMS Connect returns a secondary output message, IMS resource adapter then issues a NAK and the secondary output message is queued to the TPIPE associated with the reroute destination. A very small timeout value is also set internally on the NAK, If timeout occurs on the NAK, IMS resource adapter returns the primary output; Otherwise, IMS connect tries to return another secondary output and IMS resource adapter issues another NAK, and so on. The NAK is repeated in a loop until IMS resource adapter receives the timeout notification instead of an output message. As a result, all of the secondary output messages will be rerouted.
If execution timeout occurs before the IMS resource adapter receives the primary output, the primary output will be rerouted, as well as all secondary output messages, since they are all considered undeliverable.
Program-to-Program Express PCB considerations
If express PCBs are used, the output from the IMS transaction initiated by the Java client is not guaranteed to be the primary output message for the original commit mode 1 or commit mode 0 interaction or the secondary output for commit mode 0 interactions. However, if the reroute property is set to TRUE, the first returned output message will be sent to the Java client; the remaining output messages will be rerouted.
Case 2: Reroute of multiple output messages
A single IMS application can generate multiple output messages by issuing multiple ISRT IOPCB calls.
- Commit mode 1. Multiple output messages will be delivered to the IMS resource adapter by IMS Connect together as a single output message with multiple segments. If the multi-segment output message cannot be delivered to the IMS resource adapter -- for example, if execution timeout occurs -- it will be discarded, since reroute does not apply to commit mode 1 interactions.
- Commit mode 0. Multiple output messages will be delivered to IMS resource adapter from IMS Connect separately as multiple individual output messages per single interaction. The IMS resource adapter only returns one output message per interaction to the Java client. As mentioned earlier, the IMS resource adapter always issues an ACK for the primary output and issues NAK in a loop for any secondary output. Hence the reroute behavior for multiple messages from an IMS application program is the same as for multiple messages from program-to-program switches. If execution timeout occurs on the primary output, then the primary output and the all secondary output will be rerouted. If execution timeout occurs on the internal ACK or NAK issued by the IMS resource adapter, the primary output will be returned to the Java client and all secondary output will be rerouted.
Case 3: Reroute of undelivered output messages from OTMA to IMS Connect
When OTMA cannot deliver output messages to IMS Connect and the reroute property is set to TRUE, the undelivered output messages will be queued onto the TPIPE associated with the reroute destination specified on the initiating interaction of the Java client.
Known limitations and problems
- The reroute function applies to interactions on shareable persistent socket connections that use IMS interaction verb SYNC_SEND_RECEIVE. The reroute function is not applicable for interactions that use other IMS interaction verbs on shareable persistent socket connections or any interactions on dedicated persistent socket connections.
- The reroute function applies to commit mode 0 interactions only. It does not apply to commit mode 1 interactions. However, if a commit mode 1 interaction executes a program-to-program switch, the spawned program will run commit mode 0 and therefore the reroute support will apply.
- When the IMS resource adapter sends an ACK or NAK to IMS Connect it waits for the next output or an execution timeout notification. If IMS Connect terminates just as the IMS resource adapter sends the ACK or NAK, an exception will be returned to the IMS resource adapter. This exception will be returned to the Java client instead of the primary output. The primary output will not be returned and will not be queued to the TPIPE associated with the reroute destination if reroute is set to TRUE. All the secondary output messages will be queued to the TPIPE associated with the reroute destination if reroute is set to TRUE. A future enhancement is under investigation in which the primary output instead of an exception will be returned to the Java client.