Calling existing IMS transactions with optimized local adapters over OTMA

(ZOS) Calling existing IMS transactions with optimized local adapters over OTMA

Existing unchanged IMS™ transactions that run as Message Processing Programs (MPPs) or fast path programs (IFPs) can be called using the WebSphere Application Server for z/OS optimized local adapters over Open Transaction Manager Access Callable Interface (OTMA C/I) support. This support is provided by a new set of native modules introduced with optimized local adapters that use the IMS OTMA C/I.

Applications deployed on WAS for z/OS and must call existing IMS transactions, use the ola.rar file to reach the OTMA C/I interfacing modules. There are several new connection factory attributes that allow applications to supply the name of the target IMS system and the associated OTMA XCF information. There is also an attribute added that allows the application to set the Sync Level used for the exchange. See the topic Connection factory considerations for optimized local adapters for more details about these parameters.

IMS global transactions are supported in versions 8.5.0.2 and later. Applications that execute in a global transaction with WAS as the commit coordinator, that call existing IMS applications using the WOLA over OTMA support, can include the IMS transactions in the same global transaction context.

See the section Global transactions - WebSphere applications calling IMS applications for more information about this support.

Message Format Requirements

Prior to the support for multi-segment messages in v8, request and response messages had to be single segment, with maximum send and receive segment size no larger than 32760 bytes, including the message header.

The following is the message format expected for calls to IMS from applications in WAS:
<----------------- HEADER ---------------->   <------ DATA ------>
LL        + ZZ        + IMS Transaction Name + Message request data
(2 bytes) | (2 bytes) | (8 bytes)            | (up to 32744 bytes)
The Transaction Name in the message is used for the call to OTMA C/I and must be a transaction defined and reachable in either an IMS MPR or fast path dependent region.

Prior to V8, response data is always returned with the following format:
<----- HEADER ----->   <------------------ DATA ----------------->
LLLL                  + Message response data
(4 bytes)             | (up to 32756 bytes) 
The CICS/IMS Java Data Binding wizard in Rational Application Developer is used to create helper classes with setter and getter methods used to handle the mapping of data to and from both Java objects and binary forms. This mapping of data applies for both messages sent to IMS from WAS and response data.
Prior to v8, where single-segment messages were only supported, the response message is always preceded by the 4 byte integer message length, followed by the response message that is the area mapped by the Data Binding wizard.

Multi-segment message support

IMS multi-segment messages supports request and response messages to be larger than the prior 32744 bytes for request messages and 32756 for response messages. However, a single segment can be no larger than 32768 bytes, including the message header.

There are two connection factory attributes added with this support:

OTMAMaxSegments
OTMAMaxSegments represents the largest number of segments supported for sending and receiving IMS messages on the current connection. If a value is not specified, the default is 1.

OTMAMaxRecvSize
OTMAMaxRecvSize represents the largest possible message that can be returned from IMS using the WebSphere optimized local adapters over OTMA support. If a value is not specified, the default is 32768.

Both of these attributes can be changed dynamically for a connection using the associated methods, setOTMAMaxSegments() and setOTMAMaxRecvSize().

Global transactions - WebSphere applications calling IMS applications

Starting with v8.5.0.2, when a WebSphere application is executing in a global transaction, that application can call existing IMS programs using the WOLA over OTMA support, and cause the updates performed by the IMS program to be coordinated by the same global transaction which the WebSphere application is participating in. To use this functionality, ensure that:

The application to use a connection configured to use OTMA, and the RRSTransactional managed connection factory attribute is set to True (or 1). Setting the RRSTransactional attribute to True (or 1) enables RRS transactions for connections.
The WAS for z/OS server is running with the ola_rrs_context_propagate_otma environment variable installed, and set to True (or 1).
The IMS environment is running with RRS=YES configured.

If we need to implement any of these configuration settings, we must restart the WAS for z/OS server, and your IMS environment before applications running in a global transaction with WAS will have their transaction context coordinated with applications running in IMS.

Message format requirements for multi-segment messages

For multiple-segment messages, the default is LLZZ for requests from WebSphere optimized local adapters to IMS. The default LLLL+message data for responses from IMS to WAS remains the same.

There are methods provided with this support that allow for changing these defaults. The setOTMARequestLLZZ() and setOTMARequestLLLL() methods provide the ability to set the length prefix style for message requests from WAS to IMS. The methods, setOTMAResponseLLZZ() and setOTMAResponseLLLL(), provide the ability to set the message prefix style to LLZZ or LLLL for message responses. The following example is the message format expected for calls to IMS from applications in WAS.

LLZZ Requests (setOTMARequestLLZZ(1) and setOTMARequestLLLL(0)):
<----------------- HEADER ------------------>   
LL        + ZZ        + IMS Transaction Name + 
(2 bytes) | (2 bytes) | (8 bytes)            
<-------------------------- DATA SEGMENT 1 ---------------------->
Message segment 1 data  
(up to 32756 bytes)    
<-------------------------- DATA SEGMENT 2 ---------------------->
+ LL        + ZZ      + Message segment 1 data 
(2 bytes) | (2 bytes) | (up to 32764 bytes)
…
<-------------------------- DATA SEGMENT N ---------------------->
+ LL        + ZZ      + Message segment N data 
(2 bytes) | (2 bytes) | (up to 32764 bytes)
LLLL Requests (setOTMARequestLLLL(1) and setOTMARequestLLZZ(0)):
<----------------- HEADER ------------------>   
LLLLZZ    + IMS Transaction Name + 
(6 bytes) | (8 bytes)            
<-------------------------- DATA SEGMENT 1 ---------------------->
Message segment 1 data  
(up to 32754 bytes)    
<-------------------------- DATA SEGMENT 2 ---------------------->
+ LLLLZZ  + Message segment 1 data 
(6 bytes) | (up to 32762 bytes)
…
<-------------------------- DATA SEGMENT N ---------------------->
+ LLLLZZ  + Message segment 1 data 
(6 bytes) | (up to 32762 bytes)
LLZZ Responses (setOTMAResponseLLZZ(1) and setOTMAResponseLLLL(0)):
<----- HEADER ----->   <----------- DATA SEGMENY 1 ------------>
+ LL        + ZZ      + Message segment 1 data 
(2 bytes) | (2 bytes) | (up to 32764 bytes)
<-------------------------- DATA SEGMENT 2 ---------------------->
+ LL        + ZZ      + Message segment 2 data 
(2 bytes) | (2 bytes) | (up to 32764 bytes)
…
<-------------------------- DATA SEGMENT N ---------------------->
+ LL        + ZZ      + Message segment N data 
(2 bytes) | (2 bytes) | (up to 32764 bytes)
LLLL Responses (setOTMAResponseLLLL(1) and setOTMAResponseLLZZ(0)):
-- HEADER -->   <----------- DATA SEGMENT 1 ------------>
+ LLLLZZ        + Message segment 1 data 
(6 bytes)       | (up to 32762 bytes)
<-------------------------- DATA SEGMENT 2 ---------------------->
+ LLLLZZ   + Message segment 2 data 
(6 bytes)  | (up to 32762 bytes)
…
<-------------------------- DATA SEGMENT N ---------------------->
+ LLLLZZ  + Message segment N data 
(6 bytes) | (up to 32762 bytes)
Planning to use optimized local adapters for z/OS
Connection factory considerations for optimized local adapters