Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 9 Accessing IMS Via the OTMA Callable Interface : Programming for OTMA

Programming for OTMA
Requirements
To communicate with IMS using TIBCO Object Service Broker OTMA, you need the following:
 
GET @OTMA_MAP(address_of_@OTMA_MAP)
request after each use of the $OTMA tool. All parameters and data passed to OTMA must be set by updating this control block before calling the $OTMA tool.
Other user‑defined MAP tables that map the RECEIVE and possibly the SEND buffers used to transfer data between TIBCO Object Service Broker and OTMA.
You have to consult your IMS application documentation to understand the data format to be used in running an IMS transaction via OTMA and to map the output returned to your OTMA client.
Sample Rules Provided
To understand the elements of a basic TIBCO Object Service Broker application that uses OTMA, you can use some of the sample rules in the COMMON library. These rules execute the IMS TM PART installation verification transaction. Refer to the IBM Installation Volume 1: Installation and Verification manual, in the “IMS Sample Application” section, to find details of the PART Message Processing Program (MPP) transaction.
The main rule is called
SAMPLE_OTMA_CALL
and executes the following OTMA steps by calling other rules:
1.
2.
Issue OTMA OPEN to connect with IMS and identify the XCF group, client member name, OTMA server name and other attributes necessary to perform the otma_open operation.
3.
This request issues the otma_allocate operation and you use it to specify the transaction or command to run, the synchronization level you want to use, and the RACF group name to be used for OTMA transactions and commands.
4.
5.
Set the transaction or command data into the SEND buffer and issue the OTMA SEND request to transfer the request to the OTMA server via an otma_send_receive interface call. Data is returned in your RECEIVE buffer.
You must set various fields in @OTMA_MAP to define: the length and address of your SEND and RECEIVE buffers and the required transaction or command data in your SEND buffer.
6.
Map the returned data via your user‑defined RECEIVE MAP table. Issue a
 
GET user_RECEIVE_TBL(address_of_RECEIVE_bufr)
to cause your MAP table to reflect the data returned via your OTMA RECEIVE buffer.
At this point, you can display or process the data in your OTMA client application. If no further transactions or IMS commands are to be run, you can dismantle your OTMA structure by:
1.
Issuing an OTMA FREE request to free the OTMA session via an otma_free request. This releases the session created by the OTMA ALLO request.
2.
Issuing an OTMA CLOS request to leave the XCF group and free up storage used for communication with OTMA. This invokes the otma_close interface call.
The SESSION storage allocated for SEND, RECEIVE, and @OTMA_MAP MAP tables are freed automatically when the client OTMA session is terminated.
Session Termination
After each call of the $OTMA interface tool, check the return codes in @OTMA_MAP to ensure that the operation completed successfully. If you decide to terminate the session, perhaps because of an error, release the OTMA resources in the reverse order they were acquired. The sample rules @OTMA_CHKRETRSN and @OTMASIGNAL attempt to implement this recovery by signalling various failures back to the invoking rule's “ON condition” routine.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved