Common Client Interface (CCI)

You can create an application to use the IMS™ TM resource adapter to interact with IMS using the Common Client Interface (CCI).

To access IMS transactions through the IMS TM resource adapter, you can write the source code for applications yourself and not use the application code generated by the development environment. This is different from using a development environment such as Rational® Application Developer to generate applications for you so that coding is unnecessary.

To write the code yourself your application must use the Common Client Interface (CCI) programming interface. The CCI API provides access from J2EE clients, such as enterprise beans, JavaServer Pages (JSP) technology, and servlets, to backend enterprise information systems (EIS) such as IMS.

Applications that follow the CCI programming interface model have a common structure, independent of the EIS that is being used. The (J2EE Connector Architecture (JCA) specification defines two objects which are necessary for the application: These objects allow an application server to manage security, transaction context, and connection pools for a resource adapter. An application that uses the IMS TM resource adapter's CCI programming interface starts by obtaining an IMSConnectionFactory object. The IMSConnectionFactory object can be obtained in two ways:

IMS Connections

An IMSConnection object can then be created from that IMSConnectionFactory object. The properties of the IMSConnection object can either be specified in an IMSConnectionSpec object passed as a parameter to the getConnection method or the default values defined in the IMSConnectionFactory will be used. After an IMSConnection has been obtained, an IMSInteraction can be created from that IMSConnection. An IMSInteraction represents the interaction that is going to be executed on that connection. As with the Connection, Interactions can have custom properties taken from the IMSInteractionSpec class.

Input and output

To perform the interaction, the application makes a call to the execute() method of the IMSInteraction object, passing it input and output objects to hold the data. An input byte array must be created containing values for each field in the input message to IMS. Likewise, an output byte array must also be created to hold the response message returned by IMS. The value of each field in the output message is extracted from the output byte array.

You can write the input and output byte arrays yourself, or you can use the J2C options in Rational Application Developer (RAD) to create Java™ data bindings for the input and output messages of your CCI application even if you do not plan to use RAD for your application development.

Requirements for applications that retrieve data from an IMS system:
  • Use the IMSConnectionFactory object to create an IMSConnection object.
  • Use the IMSConnection object to create an IMSInteraction object.
  • Use the IMSInteraction object to execute transactions on the backend IMS system.
  • Close the IMSInteraction and IMSConnection objects.

Sample CCI application code

The following example shows the use of the J2EE CCI interfaces to execute a command on an EIS:
public void execute() {
try {
   ConnectionFactory cf = null;
   if (isManaged) {
//Use JNDI lookup to get ConnectionFactory instance - assumes connection factory has JNDI name of MyIMS
      Context ic = new InitialContext();
      cf = (ConnectionFactory) ic.lookup("MyIMS");
   } else {
//Create and set values for ManagedConnectionFactory
      IMSManagedConnectionFactory mcf = new IMSManagedConnectionFactory();
      mcf.setDataStoreName("MyDSName");
      mcf.setHostName("myHostNm");
      mcf.setPortNumber(new Integer(1234));
//Create connection factory from ManagedConnectionFactory
      cf = (IMSConnectionFactory) mcf.createConnectionFactory();
   }
   Connection connection = cf.getConnection();

//Create interaction with IMS to run IVTNO transaction
   IMSInteraction interaction = (IMSInteraction) connection.createInteraction();
   IMSInteractionSpec ixnSpec = new IMSInteractionSpec();
   ixnSpec.setInteractionVerb(IMSInteractionSpec.SYNC_SEND_RECEIVE);

//Create new input record 
   input = new PhoneBookInputRecordField("cp037");
   input.setIn__ll((short)59);
   input.setIn__zz((short) 0);
   input.setIn__trcd("IVTNO");
   input.setTranCodeLength(10);
   input.setIn__command("DISPLAY");
   input.setIn__name1("LAST3");
   input.setIn__name2("");
   input.setAllFieldsGiven(false);
   PhoneBookOutputRecordField

//Create new output record 
   output = new PhoneBookOutputRecordField("cp037");

//Execute interaction
   interaction.execute(ixnSpec, input, output);

//Display output
   System.out.println ("Output is: ");
   System.out.println("\nMessage: "
      + output.getOut__mesg()
      + "\nName:"
      + output.getOut__name1()
      + " "
      + output.getOut__name2()
      + "\nExtension: "
      + output.getOut__extn()
      + "\nZipcode: "
      + output.getOut__zip());

} catch (Exception e) {
   e.printStackTrace();
} finally {
//Close both the interaction and the connection
   interaction.close();
   connection.close();
}
}

Feedback