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

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 further details 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.