Using the local ECI resource adapter to link to a program in CICS

Running a program in CICS® using the JCA local ECI resource adapter is done by using the execute() method of the ECIInteraction class.

About this task

Stabilized feature:

Consider updating applications to use JCICS Link as an alternative. See also Stabilization notices and discontinued functions.

6.3 beta The JCA ECI adapter in Liberty JVM server is removed as of CICS TS 6.3.

6.16.2The JCA ECI adapter in Liberty JVM server is stabilized.

This task shows an application developer how to use the JCA local ECI resource adapter to run a CICS program passing in a COMMAREA using a JCA record. For more information on how to extend the Record interface to represent a CICS COMMAREA, see Using the JCA local ECI resource adapter with COMMAREA and for details on how to link to a CICS program that uses channels and containers, see Using the JCA local ECI resource adapter with channels and containers.

1. Use JNDI to look up the ConnectionFactory object named eis/defaultCICSConnectionFactory.
2. Get a Connection object from the ConnectionFactory.
3. Get an Interaction object from the Connection.
4. Create a new ECIInteractionSpec object.
5. Use the set methods on ECIInteractionSpec to set the properties of the execution, such as the program name and COMMAREA length.
6. Create a record object to contain the input data (see COMMAREA/Channel topics) and populate the data.
7. Create a record object to contain the output data.
8. Call the execute method on the Interaction, passing the ECIInteractionSpec and two Record objects.
9. Read the data from the output record.

   package com.ibm.cics.server.examples.wlp;
   
   import java.io.ByteArrayInputStream;
   import java.io.ByteArrayOutputStream;
   import java.io.IOException;
   import java.io.InputStream;
   import java.io.OutputStream;
   
   import javax.annotation.Resource;
   import javax.resource.cci.Connection;
   import javax.resource.cci.ConnectionFactory;
   import javax.resource.cci.Interaction;
   import javax.resource.cci.Record;
   import javax.resource.cci.Streamable;
   import javax.servlet.ServletException;
   import javax.servlet.annotation.WebServlet;
   import javax.servlet.http.HttpServlet;
   import javax.servlet.http.HttpServletRequest;
   import javax.servlet.http.HttpServletResponse;
   
   import com.ibm.connector2.cics.ECIInteractionSpec;
   
   /**
     * Servlet implementation class JCAServlet
     */
   @WebServlet("/JCAServlet")
   public class JCAServlet extends HttpServlet
   {
       private static final long serialVersionUID = 4283052088313275418L;
   
       // 1. Use JNDI to look up the connection factory
       @Resource(lookup = "eis/defaultCICSConnectionFactory")
       private ConnectionFactory cf;
   
       protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException
       {
           try
           {
               // 2. Get the connection object from the connection factory
               Connection conn = cf.getConnection();
   
               // 3. Get an interaction object from the connection
               Interaction interaction = conn.createInteraction();
   
               // 4. Create a new ECIInteractionSpec
               ECIInteractionSpec is = new ECIInteractionSpec();
   
               // 5. Use the set methods on ECIInteractionSpec to set the properties of execution.
               // Change these properties to suit the target program
               is.setCommareaLength(20);
               is.setFunctionName("PROGNAME");
               is.setInteractionVerb(ECIInteractionSpec.SYNC_SEND_RECEIVE);
   
               // 6. Create a record object to contain the input data and populate data
               // Change the contents to suit the data required by the program
               RecordImpl in = new RecordImpl();
               byte[] commarea = "COMMAREA contents".getBytes();
               ByteArrayInputStream inStream = new ByteArrayInputStream(commarea);
               in.read(inStream);
   
               // 7. Create a record object to contain the output data
               RecordImpl out = new RecordImpl();
   
               // 8. Call the execute method on the interaction
               interaction.execute(is, in, out);
   
               // 9. Read the data from the output record
               ByteArrayOutputStream outStream = new ByteArrayOutputStream();
               out.write(outStream);
               commarea = outStream.toByteArray();
           }
           catch (Exception e)
           {
              // Handle any exceptions by wrapping them into an IOException
              throw new IOException(e);
           }
       }
   
       // A simple class which extends Record and Streamable representing a commarea.
       public class RecordImpl implements Streamable, Record
       {
           private static final long serialVersionUID = -947604396867020977L;
   
           private String contents = new String("");
   
           @Override
           public void read(InputStream is)
           {
               try
               {
                   int total = is.available();
                   byte[] bytes = null;
                   if (total > 0)
                   {
                       bytes = new byte[total];
                       is.read(bytes);
                   }
   
                   // Convert the bytes to a string.
                   contents = new String(bytes);
               }
               catch (Exception e)
               {
                   // Log the exception
                   e.printStackTrace();
               }
           }
   
           @Override
           public void write(OutputStream os)
           {
               try
               {
                   // Output the string as bytes
                   os.write(contents.getBytes());
               }
               catch (Exception e)
               {
                   // Log the exception
                   e.printStackTrace();
               }
           }
   
           @Override
           public String getRecordName()
           {
               // Required by Record, unused in this sample
               return "";
           }
   
           @Override
           public void setRecordName(String newName)
           {
               // Required by Record, unused in this sample
           }
   
           @Override
           public void setRecordShortDescription(String newDesc)
           {
               // Required by Record, unused in this sample
           }
   
           @Override
           public String getRecordShortDescription()
           {
               // Required by Record, unused in this sample
               return "";
           }
   
           @Override
           public Object clone() throws CloneNotSupportedException
           {
               // Required by Record, unused in this sample
               return super.clone();
           }
       }
   }

Results

You have successfully linked to a program in CICS using the ECI resource adapter.