Programming with the Callout API

IMSCallout API

Use the IMSCallout class to issue Synchronous Callout (ICAL) DL/I calls directly from a Java-enabled dependent region with the IMS Universal JDBC driver IMSCallout API.

The following code shows a simple application using the IMSCallout to issue a callout request:

ByteBuffer icalRequestArea = null;
ByteBuffer icalResponseArea = null;
icalRequestArea = app.get31BitDirectByteBuffer(requestSize);
icalRequestArea.position(0);
icalRequestArea.put("CALLOUT FROM ICAL PGM".getBytes("CP1047"));
icalResponseArea = app.get31BitDirectByteBuffer(actualResponseBufferSize);

IMSCallout imsCallout = app.createImsCallout();

imsCallout.setOtmaDescriptor(otmaDescriptor)
.setRequestArea(icalRequestArea)
.setResponseArea(icalResponseArea)
.setSubFunction(IMSCallout.SubFunction.SENDRECV)
.setTimeout(10000)
.execute();

System.out.println(imsCallout.getReturnCode());
System.out.println(imsCallout.getReasonCode());
System.out.println(imsCallout.getErrorCodeExtension());
System.out.println(imsCallout.getOutputAreaUsed());

app.free31BitDirectByteBuffer(icalResponseArea);
        app.free31BitDirectByteBuffer(icalRequestArea);
app.end();

ByteBuffers and Type-2 Java applications

If your JDBC application is running in Type-2 mode, you can optimize JVM storage by obtaining Byte Buffers directly. When your specified work is complete, you must release the buffers.

Obtain direct storage in the following ways:

• If your application is running in a 31-bit JVM, you can obtain Byte Buffers directly by using the java.nio.ByteBuffer class. ByteBuffer.allocateDirect() works only in a 31-bit JVM.

  ByteBuffer directBuffer = ByteBuffer.allocateDirect(10);

• Use the Universal Drivers Application object to obtain direct 31-bit storage. If your application is running in the 64-bit JVM, you must use this method.

  Application app = new ApplicationFactory.createApplication();
            ByteBuffer directBuffer = app.get31BitDirectByteBuffer(20);
  

Release the buffers that were obtained with the Application class in the following ways:

• Specifically free the buffers with the free31BitDirectByteBuffer() method.

  Application app = new ApplicationFactory.createApplication();
  ByteBuffer directBuffer = app.get31BitDirectByteBuffer(20);
     // Doing work
  
  app.free31BitDirectByteBuffer(directBuffer);

• Use the end() method. IMS tracks all buffers that are allocated with the Application class and automatically releases them as part of the end() procedure.

  Application app = new ApplicationFactory.createApplication();
    ByteBuffer directBuffer = app.get31BitDirectByteBuffer(20);
    // Doing work
    app.end();
  

Java Message Service API

The IMSCallout API is the newer, IMS-specific way to issue synchronous callout requests from a Java dependent region. However, an IMS implementation of the Java Message Service (JMS) that uses JMS classes can provide limited support for synchronous callout requests from JMP or JBP applications.

Support is limited to the Point-to-Point (PTP) messaging domain, and is provided only for nontransacted QueueSession objects with Session.AUTO_ACKNOWLEDGE mode. Calling unsupported JMS methods or passing unsupported JMS arguments throws a JMSException exception.

The JMS API is included in the Java SDK. To use JMP and JBP support for synchronous callout, the JMS API (jms.jar) file must be on your classpath. Alternatively, IMS Enterprise Suite V3.2 is available for purchase, which includes the JMS API.

Use the following steps to send a message and synchronously receive a response:

1. Create a com.ibm.ims.jms.IMSQueueConnectionFactory object.
2. Create a JMS QueueConnection instance by calling the createQueueConnection method on the IMSQueueConnectionFactory object.
3. Create a JMS QueueSession instance by calling the createQueueSession method on the QueueConnection instance. In the method call, set the input parameter values to false and Session.AUTO_ACKNOWLEDGE to specify that the generated QueueSession instance is nontransacted and runs in AUTO_ACKNOWLEDGE mode.
4. Create a queue identity by calling the createQueue method on the QueueSession instance. In the method call, set the input parameter value to the OTMA descriptor name for the synchronous callout operation.
5. Create a JMS QueueRequestor instance and pass in the QueueSession instance from step 3 and the Queue instance from step 4 as input parameters to the QueueRequestor constructor method.
6. Create a TextMessage instance by calling the createTextMessage method on the QueueSession instance from step 3. Set the string that contains the message data.
7. To send the message and retrieve a response, call the request method on the QueueRequestor object from step 5. In the method call, pass in the TextMessage instance from step 6. Cast the return value from the request method call to a TextMessage instance. If the call is successful, the return value is the response to the synchronous callout request.

The following example shows a simple JMP or JBP application that sends a message to an external application and synchronously receives a response message. In the example, an IMSQueueConnectionFactory instance has a timeout value of 10 seconds and allocates 128 KB of space to hold response messages.

import javax.jms.JMSException;
import javax.jms.Queue;
import javax.jms.QueueConnection;
import javax.jms.QueueRequestor;
import javax.jms.QueueSession;
import javax.jms.Session ;
import javax.jms.TextMessage;
import com.ibm.ims.jms.IMSQueueConnectionFactory;

public class IMS_Sample
{
    public static void main(String argv[])
    {
        IMSQueueConnectionFactory jmsConnectionFactory 
           = new IMSQueueConnectionFactory();
        QueueConnection jmsConnection = null;
        QueueSession jmsQueueSession = null;
        Queue jmsQueue = null;
        QueueRequestor jmsQueueRequestor = null;
        
        try {
            jmsConnectionFactory.setTimeout(1000); 
                          // set the timeout to 10 seconds
            jmsConnectionFactory.setResponseAreaLength(128000); 
                          // allocate 128k to hold the response message
            jmsConnection = jmsConnectionFactory.createQueueConnection();
            jmsQueueSession 
            = jmsConnection.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
						// set session to be non-transacted and in AUTO_ACKNOWLEDGE mode
            jmsQueue = jmsQueueSession.createQueue("OTMDEST1"); 
						// pass in the OTMA descriptor name
            
            jmsQueueRequestor 
               = new QueueRequestor(jmsQueueSession, jmsQueue);
            TextMessage sendMsg = jmsQueueSession.createTextMessage();
            sendMsg.setText("MyMessage");
            System.out.println("Sending message: "+sendMsg.getText());
            TextMessage replyMsg 
               = (TextMessage)jmsQueueRequestor.request(sendMsg);
            
            System.out.println("\nReceived message: "+replyMsg.getText());
        } catch (JMSException e) {
            e.printStackTrace();
        }
    }
}