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:
Procedure
Retrieve callout requests by using the RESUME TPIPE call.
When 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.
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.
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:
Code 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.
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
