Configuring user-written IMS Connect clients for synchronous callout requests

To support synchronous callout requests, user-written IMS Connect clients must be configured to retrieve new callout requests from IMS, acknowledge the receipt of the callout request (ACK or NAK), and to return the synchronous callout responses to IMS through IMS Connect.

Synchronous callout request messages are handled by IMS Connect and OTMA in much the same way as asynchronous output. That is, synchronous callout request messages are retrieved by issuing a RESUME TPIPE call. Many of the same rules and guidelines for retrieving asynchronous output also apply to retrieving synchronous callout request messages.

IMS provides various sample application programs to test callout support. For more information, see Samples for the callout function.

The high-level steps for configuring a user-supplied IMS Connect client to support synchronous callout messages include coding the client to:

  1. Retrieve callout requests by using the RESUME TPIPE call.
    Start of changeWhen retrieving new synchronous callout requests, a user-written IMS Connect client usually issues the RESUME TPIPE call with a very long timeout value or no timeout value. In the IRM for the RESUME TPIPE request, the client can optionally indicate that the client application supports control data from the ICAL callout message.

    If a synchronous callout request message is queued when the RESUME TPIPE call is received by IMS, OTMA sends it to the client through IMS Connect. If no callout message is queued, the IMS Connect client waits in a receive state and OTMA sends the next callout request to the client immediately upon arrival at the output queue.

    End of change
  2. Acknowledge the successful (ACK) or unsuccessful (NAK) receipt of synchronous callout requests.
    To acknowledge the receipt or the rejection of a synchronous callout request, the user-written IMS Connect client must send an ACK or a NAK response to IMS to free the output queue for new callout messages. If an ACK or NAK is not received before the timeout value specified for either the synchronous callout request or the acknowledgment message itself, OTMA discards the callout request and frees the output queue.
  3. Return a response message to IMS Connect by using the synchronous callout option of the send-only protocol. The response must include the correlator token that IMS Connect included in the original callout request.
    The response can be either the data requested by the IMS application or an error message.

In addition to these steps for configuring the IMS Connect client, the following additional steps are required to complete the configuration of your installation for synchronous callout support:

  • Start of changeCode an IMS application program to initiate a synchronous callout request by issuing the DL/I ICAL call. You can optionally add control data in the ICAL call to specify the URL for the port, user token, security information, or any other information. End of change
  • Code an OTMA destination descriptor to route the synchronous callout request to the IMS Connect client.

The following figure shows the flow of a synchronous callout request between IMS and a user-written IMS Connect client.

Figure 1. Flow of a synchronous callout request between an IMS application and a user-written IMS Connect client
User-written client issues resume tpipe to OTMA through IMS Connect to wait for a synchronous callout request. Callout request arrives at tpipe hold queue and is sent with a correlation token by OTMA to the client through IMS connect. Client sends ACK. Client returns callout response with correlation token to IMS application through IMS Connect and OTMA.