Implementing a synchronous callout interaction with the IMS Connect API for Java

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

  1. Optional: If you are loading the connection and interaction properties from a file, set the connection and interaction property values in the properties file.
  2. In your Java application, import the com.ibm.ims.connect package.
  3. Create a ConnectionFactory instance.
  4. 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.
  5. 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.
  6. 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
  7. 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.
  8. Send the ACK or NAK response to IMS.
    1. 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.
    2. 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.
    3. Call the execute method of the TmInteraction object to send the ACK or NAK response to IMS.
    A NAK response ends the callout interaction.
  9. 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.
  10. Set the response message data in the InputMessage object.
  11. Configure your TmInteraction object to send the response message.
    1. 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.

    2. 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.
    3. 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.
  12. Call the execute method of your TmInteraction object to send the response message to IMS.
  13. When you finish your interactions with IMS Connect, close the socket connection to IMS Connect by calling the disconnect method of your Connection instance.