Synchronous program switch requests

To send a request to another IMS transaction and receive the response in the same unit of work, use the DL/I ICAL request. This usage of the ICAL interface is called a synchronous program switch request. Java™ application programs that use the Java dependent region resource adapter can also issue synchronous program switch requests with the JMS API.

The target transaction runs in a separate unit of work, so it is not eligible for two-phase commit or z/OS® Resource Recovery Services.

The target transaction can be in the same IMS system, a remote IMS system via multiple systems coupling (MSC), or an IMS system that is accessible via shared queues.

IMS schedules the transaction for the ICAL call as an OTMA transaction. You do not need to enable OTMA to make a synchronous program switch request.

To use the synchronous program switch function, you must first configure an OTMA destination descriptor with TYPE=IMSTRAN for the destination application. The destination descriptor can be set in the DFSYDTx member of the IMS.PROCLIB data set, or you can create it with the CREATE OTMADESC command.

The TMEMBER, TPIPE, and SMEM parameters behave differently for the IMSTRAN descriptor type than for other descriptor types. These parameters are used to optionally specify a default destination for late response messages from the target application program.

The following figure shows the five-step synchronous program switch processing model.

Figure 1. IMS synchronous program switch processing
The application program that is running in region 1 issues an ICAL to TRAN_A. The IMS control region reads the destination descriptor. The message is then routed to the message queue with commit mode 1 processing to region 2, where TRAN_A is scheduled. TRAN_A returns the synchronous response message to the IMS control region. The IMS control region routes the message back to the application program in region 1.
  1. The application program that is running in region 1 issues an ICAL to TRAN_A. The ICAL request is routed to the IMS control region.
  2. The IMS control region reads the destination descriptor specified in the request.
  3. The IMS message queue is used to schedule the TRAN_A transaction in region 2 using the send-then-commit (CM1) protocol. The OTMA routing function is used even if OTMA is not enabled in the IMS system.
  4. After the target application finishes processing, it returns the response message to the IMS control region.
  5. The IMS control region responds to the original DL/I ICAL call in region 1 with the response message from region 2.
Note: The dependent regions can be MPPs, JMPs, IFPs, BMPs, or JBPs.

IMS uses the OTMA message header format for synchronous program switch messages. In the state data header, the commit mode is set to 1 and the sync level is set to CONFIRM. The TMAMHCOR field is set to the LCRETOKN value from the IMS region where the ICAL call was issued. However, if the synchronous program switch originated from an OTMA transaction, IMS inserts information from the original transaction: TMAMHCOR is set to the original correlator value, TMAMHCID is set to the original client member name, and TMAMRTOD is set to the original tpipe name.

The user ID name from PSTUSID and the group name from PSTGRPNM are included in the security data header.

No user data header is needed if the original transaction is not an OTMA transaction and the OTMA destination descriptor for the message does not include any late message routing information. If the ICAL call is from an OTMA transaction that includes the user data header information, the same user data header information is used for the synchronous program switch message.

Restrictions:
  • The OTMA Input/Output Edit exit routine (DFSYIOE0) is not called for a synchronous program switch request or for response message.
  • The TM and MSC Message Routing and Control exit routine (DFSMSCE0) is not called for a synchronous program switch request.
  • The target transaction is not part of the RRS commit scope of the initiating application program.
  • BMP and JBP applications cannot make synchronous program switch requests in a DBCTL environment.
  • The target transaction has read-only access to Fast Path MSDBs.
  • The target transaction cannot be an IMS conversational transaction.
  • To use synchronous program switch in a shared queues environment, all of the participating IMS systems must be Version 13 or later.

Issuing synchronous program switch requests from Java applications

Synchronous program switch requests can also be issued from Java applications running in IMS Java dependent regions (JDRs). The IMS Java dependent region resource adapter uses the standard JMS API as a front end for synchronous program switch requests as well as other callout requests.