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

Start of change In 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.

The application program that is running in region 1 issues an ICAL to TRAN_A.
The IMS control region reads the destination descriptor.
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.
After the target application finishes processing, it returns the response message to the IMS control region.
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 change To 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.

Requirements

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

Restrictions

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
IMS 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.

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:

LTERMOVR: 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.
REPLYCHK=YES | NO: 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.
SYNCTP=YES | NO: 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:

DFS4687E: 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.
DFS1190I: 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:

CREATE OTMADESC
/DISPLAY ACTIVE
/DISPLAY OTMA
/PSTOP
QUERY OTMADESC
/SECURE
/STOP OTMA
/STOP TMEM
UPDATE OTMADESC

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: OTMA destination descriptor syntax and parameters
Communications and connections	New topics: Synchronous program switch requests Administering OTMA tmembers Sending type-1 commands from an OTMA client
Communications and connections	Changed topics: OTMA support for callout requests Capabilities of OTMA OTMA destination descriptors OTMA routing of asynchronous callout requests General OTMA security considerations Using DL/I calls in an OTMA environment Dependent region occupancy and OTMA Message-control information section Synchronous callout requests
Application programming	New topics: Issuing synchronous program switch requests from a Java dependent region
Application programming	Changed topics: Callout requests for services or data Callout request approaches Implementing the synchronous callout function Implementing the asynchronous callout function
Application programming APIs	Changed topics: ICAL call
Diagnosis	New topic: OTMA trace entry for synchronous program switch
Messages and codes	New topics: 0100/0110 DFS4687E
Messages and codes	Changed topics: DFS1190I 0100/000C A1 AX About AIB return and reason codes
Commands: Volumes 1-2 (CR1 and CR2)	Changed topics: /PSTOP command /DISPLAY OTMA command CREATE OTMADESC command UPDATE OTMADESC command QUERY OTMADESC command /DISPLAY ACT command /STOP OTMA command /STOP TMEM command /SECURE command
Exit routines	Changed topics: OTMA Destination Resolution user exit (DFSYPRX0 and other OTMAYPRX type exits) Message Control/Error exit routine (DFSCMUX0) OTMA User Data Formatting exit routine (DFSYDRU0) TM and MSC Message Routing and Control User exit routine (DFSMSCE0)