Synchronous callout sample application

A simple application to test the synchronous callout message retrieval and response functions of the IMS Connect API for Java is provided in the archive samples.jar.

Prerequisites

  • Configure and start an instance of IMS Connect.
  • Create an IMS application program to issue the synchronous callout ICAL call. You can use the IMS IVP synchronous callout sample application (part DFSSSCBL invoked with job IV_S228J) or supply your own.
  • 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.

This sample application retrieves synchronous callout request messages sent by an IMS application and returns a message response. Unlike an inbound request message, a synchronous callout interaction must be initiated from the IMS host system.

Running the sample

To run the samples with your IMS systems, you must modify and recompile the sample with configuration settings for your environment, including the following API properties:

  • IMS Connect host name
  • IMS Connect port number
  • Client ID
  • IMS data store name
  • Location of the sample properties files provided with samples.jar

You can modify the log file location, and set the application to load from your own properties files. To use the sample application, build a JAR file containing the modified sample programs and add that JAR file to your classpath.

What the sample does

First, the sample application configures the API properties to prepare for interactions with IMS Connect:

  1. Activates logging for the API.
  2. A commented section is included to configure SSL properties for secure communication with IMS Connect. You must configure a keystore and truststore, and an SSL-enabled port on the IMS Connect host, to use SSL communications.
  3. Creates a ConnectionFactory object named myCF and configure it with the connection properties for the target IMS Connect host.
  4. Creates a Connection object named myConn from myCF and opens a socket connection to IMS Connect.

The application then prints a notification to the system console that it is attempting to retrieve a callous message. The notification text includes the API properties that are used for the interaction. Then the application does the following:

  1. Instantiates a new TmInteraction object named myTMInteraction from myConn and sets the interaction properties.
  2. Executes the interaction to retrieve the synchronous callout message from the IVP application from IMS Connect.
  3. Retrieves and prints the OutputMessage contents from the callout message.
  4. Configures myTMInteraction to send an acknowledgement response to IMS and sends the acknowledgement.
  5. A commented section is included to send a negative acknowledgement response instead of a positive ACK.

The application then prints a notification to the system console indicating whether the interaction succeeded or failed, along with the return and reason codes from IMS Connect. If the first interaction was successful, the application then prints a notification that it is starting another interaction to send a response to the callout message. Then the application does the following:

  • Configures myTMInteraction to send a synchronous callout response. The callout correlator token value is retained in myTMInteraction from the first interaction.
  • Builds the input message buffer for the response message.
  • Sends the response message.

After the response is sent, the application prints a notification with information about the final state of the interaction and then ends.

Commented sections are included that demonstrate the send-only with acknowledgement mode for the callout response message. When the interaction type is set to INTERACTION_TYPE_DESC_SENDONLYACK_CALLOUT_RESPONSE, the sample application receives an acknowledgement from IMS when the response message is received. See the code comments for more information