Implementing the synchronous callout function

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

Input and output messages from IMS can be 32 KB or larger per segment for a synchronous callout request. However, the maximum segment size is 32 KB for a synchronous program switch request.

The following diagram shows the message flow of the synchronous callout function. The request starts with an IMS application that issues an ICAL call. The response is returned to the requesting IMS application.

Figure 1. Message flow of the synchronous callout function
An IMS application makes an ICAL call with SENDRECV subfunction to an IMS subsystem which contains the OTMA descriptor. For the send flow, the OTMA descriptor routes the request message to IMS Connect and then on to one of the following endpoints: to another IMS application program via synchronous program switch, to a user-written IMS Connect client application (such as SAP), to a Web Service provider (such as Microsoft .NET) via IMS Enterprise Suite SOAP Gateway, or to an EJB or MDB hosted on WebSphere Application Server via IMS TM Resource Adapter. The EJB or MDB passes the request on to a Web Service provider (such as Microsoft .NET). For the receive flow, the response is returned in the opposite direction to the IMS application that made the ICAL call, using the same flow path as for the send flow.

You can make concurrent ICAL calls from your IMS applications that are routed to the same or different IMS Connect destinations. By using the RESUME TPIPE call and the send-only protocol, the synchronous callout function allows the requests to be sent and the responses to be received in different connections and threads. You can have one connection for retrieving the callout requests and use other connections to return the response messages simultaneously.

A correlation token is created by IMS to correlate the response message back to the correct IMS transaction instance. The capability of having different threads and connections for pulling callout requests and for returning response messages provides maximum concurrency.

Correlation tokens are not used for synchronous program switch requests.

Your application can make an ICAL call with the RECEIVE subfunction code to get the complete response data for a previously incomplete ICAL call with the SENDRECV subfunction code. However, your application cannot retrieve the complete response data with a RECEIVE subfunction call after issuing a subsequent call with the SENDRECV subfunction. Issuing a subsequent ICAL call with the SENDRECV subfunction code clears the ICAL response buffer in the IMS control region for the previous ICAL call.

The following high-level steps provide an overview of implementing and deploying your synchronous callout application and function.

  1. Create or modify an IMS application for the ICAL call.
  2. Define the OTMA destination descriptor for one of the following callout request approaches:
    • Send the callout request to an external application viaIMS Enterprise SuiteIMS TM Resource Adapter.
    • Send the callout request to an external application viaIMS Enterprise Suite SOAP Gateway.
    • Send the callout request to a user-written IMS Connect client application.
    • Send a synchronous program switch request to another IMS application.
    The destination descriptor can be defined in the DFSYDTx member of the IMS.PROCLIB data set, or with the CREATE OTMADESC command.
  3. Restart IMS for the newly defined OTMA descriptor.
    This step is not required if the descriptor was dynamically added with the CREATE OTMADESC command.
  4. Run the IMS application that was created or modified in step 1 to issue the synchronous callout request.
The IMS application receives the response message from the synchronous callout target. If the response message does not fit in the allocated response area, the application can expand the available response data area and then issue an ICAL call with the RECEIVE subfunction code to get the complete response.

Example COBOL program implementation of the synchronous callout function

To issue the ICAL call in a COBOL program, use the CALL statement.

CALL 'AIBTDLI' USING ICAL, AIB, CA-REQUEST, SCA-RESPONSE.

The following example demonstrates the required AIB field declaration for the ICAL call in the COBOL program. A complete COBOL example (with part name DFSSSCBL) is provided with the callout IVP sample in the SDFSSMPL sample library.

01 AIB.
   02 AIBRID PIC x(8)  VALUE 'DFSAIB  '.
   02 AIBRLEN PIC 9(9) USAGE BINARY.
   02 AIBSFUNC PIC x(8) VALUE 'SENDRECV'.
   02 AIBRSNM1 PIC x(8) VALUE 'OTMDEST1'.
   02 AIBRSNM2 PIC x(8).
   02 AIBRESV1 PIC x(8).
   02 AIBOALEN PIC 9(9) USAGE BINARY VALUE 28.
   02 AIBOAUSE PIC 9(9) USAGE BINARY VALUE 30.
   02 AIBRSFLD PIC 9(9) USAGE BINARY VALUE 5000.
   02 AIBRESV2 PIC x(8).
   02 AIBRETRN PIC 9(9) USAGE BINARY.
   02 AIBREASN PIC 9(9) USAGE BINARY.
   02 AIBERRXT PIC 9(9) USAGE BINARY.
	...

The following example shows the CA-REQUEST and SCA-RESPONSE declarations in the COBOL program.

* ICAL Request Area
 01  CA-REQUEST.
     02  CA-MESSAGE   PIC  X(45) VALUE SPACES.

* ICAL Response Area
 01  SCA-RESPONSE.
     02  SCA-MESSAGE  PIC  X(100) VALUE SPACES.