DL/I ICAL call and Java API enhancements for synchronous program switch

Start of changeIn IMS™ Version 13, the DL/I ICAL call can be used to send a request to another IMS application and receive the response in the same unit of work for the original application. The Java™ dependent region resource adapter includes a Java Message Service (JMS) interface that can be used by Java applications for the same functionality in Java dependent regions.End of change

Synchronous program switch

The IMS application program that initiates a synchronous program switch can run in an MPP, BMP, JMP, JBP, or IFP region.

The target application program can be in the same IMS system, a remote IMS system via 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.

To issue a synchronous callout request from your IMS application, issue the ICAL call and specify the OTMA descriptor name. The ICAL call can also be issued through a REXXTDLI call, or from a Java application that runs in a JMP or JBP region.Optionally, you can also specify a timeout value (the maximum time to wait for the response to return).

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.
  2. The IMS control region reads the destination descriptor.
  3. IMS routes the message to the destination application 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 with the response message. Optionally, if the originating application already timed out, IMS can enqueue the late response message in a pre-specified tpipe for later retrieval.

Synchronous program switch in Java dependent regions

IMS™ provides support for synchronous program switch functionality from Java™ message processing (JMP) or Java batch processing (JBP) applications through an IMS implementation of the Java Message Service (JMS).

DL/I ICAL RECEIVE subfunction

The RECEIVE subfunction of the DL/I ICAL is added to enable applications to efficiently receive large messages that did not fit into the initially specified response area.

When a send/receive (SENDRECV) subfunction call returns too much data to fit in the allocated response area, IMS:
  • Truncates the data and returns only the data that fits in the allocated response area
  • Puts the actual length of the response message into the AIBOALEN field
  • Keeps the entire response message in an internal control region buffer for a certain length of time
The application can take the following actions:
  • Ignore the truncated message
  • Issue another SENDRECV ICAL call with the larger, correct response area size
  • Issue a RECEIVE ICAL call with a correct response area size to get the complete response message from the internal buffer
The complete response data for the original ICAL call is held in the IMS control region buffer until one of the following events occurs:
  • The application issues a new ICAL call with the SENDRECV subfunction code is issued
  • The IMS application reaches a sync point or terminates
  • The IMS application issues a ROLB or CHECKPOINT call

Migration considerations

No impact.

Coexistence considerations

Start of changeTo use the synchronous program switch function in a shared queues environment, all participating systems must be IMS Version 13 or later systems.End of change

Log record changes

The ’67D0’ log record is changed to include a new error reason code for the synchronous program switch enhancement.


The synchronous callout program switch enhancement has the same hardware and software requirements as the base IMS Version 13 product.


  • The OTMA Input/Output Edit exit routine (DFSYIOE0) is not called for a synchronous program switch request or 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 and have a MINVERS value of 13.1
  • Start of changeIMS schedules synchronous program switch transactions as OTMA transactions, using the OTMA security setting (NONE, CHECK, or FULL). The DFSBSEX0 exit routine is not called for the target transaction.End of change

Impact to installing and defining IMS

OTMA destination descriptor information is enhanced with the new IMSTRAN type of destination for IMS synchronous program switches.

The TMEMBER, TPIPE, SMEM, SYNTIMER, and EXIT parameters are valid for TYPE=IMSTRAN descriptors. The following additional parameters are also valid:

Specifies a logical terminal name used to override the name specified in the I/O PCB of the IMS application program. This parameter is optional.
Specifies whether originating IMS detects if the target IMS application replies to the IOPCB. When REPLYCHK=YES and the target application does not reply to the IOPCB (or issue an ICAL request for synchronous program switch to a third application), IMS issues return and reason codes to the application instead of a timeout to the ICAL call. This parameter is optional and the default is YES.

When REPLYCHK=NO, IMS does not check to see whether the target application replies to the I/O PCB or if it issues a synchronous program switch to another transaction.

Specifies whether the destination TPIPE for the late messages needs to be created as a synchronized TPIPE. This parameter is optional and the default is NO.

Impact to administering IMS

New topics are added and existing topics are revised in the communications and connections information about using OTMA destination descriptors for IMS synchronous program switches.

Impact to programming for IMS

Existing application programming topics are enhanced to include updates to the:
  • ICAL call information
  • Callout approach concepts
  • Callout implementation information

Impact to troubleshooting for IMS

The diagnosis information is enhanced with OTMA trace entry information for synchronous program switches.

The following new messages are added:
An error occurred during synchronous program switch processing for a DL/I ICAL call. The message includes a short summary of the underlying cause of the error.
A /PSTOP AOITOKEN or /PSTOP REGION SYNC command was issued, but the region was not waiting for the specified AOI token or ICAL response.

Additional reasons for having the A1 status code returned to application programs are added.

For a complete list of the new, changed, and deleted messages and abend codes in IMS Version 13, see Message and code changes in IMS Version 13.

Impact to IMS reference information

Impact to commands

Synchronous program switch information is added to the following commands:

  • /PSTOP

Impact to exit routines

Synchronous program switch information is added to the following exit routines:
  • OTMA Destination Resolution exit routine (DFSYPRX0)
  • Message Control/Error exit routine (DFSCMUX0)
  • OTMA User Data Formatting exit routine (DFSYDRU0)

Impact to utilities

This enhancement does not affect utilities.

Documentation changes for the DL/I ICAL call enhancements

The following publications contain new or changed information for the synchronous program switch enhancement. Publications that are not impacted by the enhancement are not included in the table.

Table 1. Synchronous program switch documentation
Publication Links to topics
System definition Changed topic:
Communications and connections New topics:
Changed topics:
Application programming New topics:
Changed topics:
Application programming APIs Changed topics:
Diagnosis New topic:
Messages and codes New topics:
Changed topics:
Commands: Volumes 1-2 (CR1 and CR2) Changed topics:
Exit routines Changed topics: