Callout interactions are initiated from an IMS application program rather than the
IMS Connect API for Java client
application. In a synchronous callout interaction, the IMS application program that sends the
callout request remains scheduled in the IMS dependent region while the request is processed by the
IMS Connect API for Java client
application.
Prerequisites:
- Configure and start an instance of IMS Connect.
- Create an IMS application program to issue the synchronous callout
ICAL call.
- Create an OTMA destination descriptor for the IMS Connect instance and destination tpipe. See
OTMA destination descriptors in
IMS Version 14 Communications and Connections Guide.
Use the ConnectionFactory interface
to obtain Connection objects that handle the communication
with IMS Connect. Use the Connection.createInteraction method
to obtain a TmInteraction instance that represents
an interaction with IMS Connect.
The TmInteraction instance
must be configured to retrieve synchronous callout request messages
from an IMS Connect tpipe.
To implement a synchronous callout
interaction:s
- Optional: If you are loading the connection
and interaction properties from a file, set the connection and interaction
property values in the properties file.
- In your Java application, import the com.ibm.ims.connect package.
- Create a ConnectionFactory instance.
- Optional: Load the initial connection property
values from a text file or set the connection properties by using
the setter methods of the ConnectionFactory class.
You can specify a set of default connection property values
and use these values to configure a ConnectionFactory object.
When creating new Connection objects from the ConnectionFactory,
you must configure the properties that differ from the default ConnectionFactory values
on the new Connection objects.
- Instantiate a Connection object from
the ConnectionFactory instance.
You
can modify the connection properties by loading a properties file
or by using the setter methods of the
Connection interface.
The following properties must be set when establishing a connection
to IMS Connect:
- hostName
- TCP/IP host name of the IMS Connect instance.
- portNumber
- IMS Connect listening port number.
- clientID
- Name of the tpipe in the OTMA destination descriptor used by your
IMS application.
- Instantiate and configure a TmInteraction object
from your Connection instance.
You can
modify the interaction properties by loading a properties file or
by using the setter methods of the
TmInteraction interface.
The following
TmInteraction properties must be
set for a synchronous callout interaction:
- interactionTypeDescription: set this property to
INTERACTION_TYPE_DESC_RESUMETPIPE
- resumeTPipeRetrievalType: set this property to
RETRIEVE_SYNC_CALLOUT_ONLY
or RETRIEVE_SYNC_CALLOUT_OR_ASYNC_OUTPUT
- Call the execute method of the TmInteraction object.
The API retrieves a callout message from the specified tpipe
and instantiates an OutputMessage object that contains
the callout message.
- Send the ACK or NAK response to IMS.
- Configure the TmInteraction object
to send the ACK or NAK response.
If you negatively acknowledge
the message, you can choose to either discard or retain the callout
message and the RESUMETPIPE call.
- To positively acknowledge the message and proceed with the interaction,
set interactionTypeDescription to
INTERACTION_TYPE_DESC_ACK
.
- To negatively acknowledge the message, discard the message, and
end the RESUMETPIPE call, set the interactionTypeDescription property
to
NAK_DISCARD_SYNC_CALLOUT_REQUEST_END_RESUMETIPE
.
- To negatively acknowledge the message, discard the message, and
keep the RESUMETPIPE call open, set the interactionTypeDescription property
to
NAK_DISCARD_SYNC_CALLOUT_REQUEST_CONTINUE_RESUMETIPE
.
- To negatively acknowledge the message, retain the message, and
end the RESUMETPIPE call, set the interactionTypeDescription property
to
NAK_RETAIN_SYNC_CALLOUT_REQUEST_END_RESUMETIPE
.
- Optional: Use the setNakReasonCode method
of your TmInteraction object to set a 2-digit hexadecimal
reason code between 2001 and 3000 (X’7D1’ - X’BB8’) for a NAK response.
The IMS application receives this code along with the NAK response.
- Call the execute method of the TmInteraction object
to send the ACK or NAK response to IMS.
A NAK response ends the callout interaction.
- Retrieve the callout message data from the OutputMessage object.
The callout message format is user-defined and must be understood
both by the IMS application and your client application.
- Set the response message data in the InputMessage object.
- Configure your TmInteraction object
to send the response message.
- Use the setCalloutResponseMessageType method
of your TmInteraction object to set the callout
response message type value to
CALLOUT_RESPONSE_MESSAGE
.
To return an error instead of a normal callout response message,
set the callout response message type value to CALLOUT_ERROR_RESPONSE_MESSAGE
.
- Optional: For an error response, you can
use the setNakReasonCode method of your TmInteraction object
to set a reason code between X’7D1’ and X’BB8’ for the error.
- Use the setInteractionTypeDescription method
of your TmInteraction object to set the interaction
type value to
INTERACTION_TYPE_DESC_SENDONLY_CALLOUT_RESPONSE
.
Tip: If you want your
application to receive an explicitly acknowledgement that the response
was received by the IMS application, use the INTERACTION_TYPE_DESC_SENDONLYACK_CALLOUT_RESPONSE
interaction
type value instead.
- Call the execute method of your TmInteraction object
to send the response message to IMS.
- When you finish your interactions with IMS Connect, close
the socket connection to IMS Connect by calling the disconnect method
of your Connection instance.