Linking to a program on a CICS server

Use the Interaction interface to link to a server program. The ECI resource adapter provides an implementation of the Interaction interface but you do not use this directly.

To define the properties of the interaction use the ECIInteractionSpec class directly.
  1. Set the FunctionName property to the name of the CICS® server program.
  2. Set the InteractionVerb to SYNC_SEND for an asynchronous call or SYNC_SEND_RECEIVE for a synchronous call. Use SYNC_RECEIVE to retrieve a reply from a asynchronous call.
    1. When a SYNC_SEND call has been issued with the execute() method of a particular ECIInteraction object, that instance of ECIInteraction cannot issue another SYNC_SEND, or SYNC_SEND_RECEIVE, until a SYNC_RECEIVE has been run.
    2. Simultaneous asynchronous calls to the same connection are permitted, provided they do not result in two asynchronous calls being outstanding in the same transaction scope. In that case an exception is thrown.
    3. If you are using the adapter in local mode with IBM® WebSphere® Application Server for IBM z/OS®, and you require transactional support, specify the SYNC_SEND_RECEIVE interaction type. If you use SYNC_SEND and SYNC_RECEIVE to issue asynchronous requests, the ECI requests are issued with SYNCONRETURN, and are outside the scope of the current global transaction. In remote mode, asynchronous calls work in the usual way.
  3. If you are using channels and containers, the program receiving the data does not need the exact size of the data returned. If you are using COMMAREAs, set the CommareaLength property to the length of the COMMAREA being passed to CICS. If it is not supplied, a default is used:
    Length of input record data
    The value of ReplyLength
  4. Set the ReplyLength property to the length of the data stream to be returned from the Gateway daemon to the JCA application. This value can reduce the data transmitted over the network if the data returned by CICS is less than the full COMMAREA size, and you know the size of the data in advance.

    The JCA application still receives a full COMMAREA of the size specified in CommareaLength, but the amount of data sent over the network is reduced. This method is equivalent to the setCommareaInboundLength() method available for the ECIRequest class.

    If you do not set ReplyLength, CICS Transaction Gateway automatically strips trailing zeros from the COMMAREA sent from the Gateway daemon to the JCA application, without needing the size of the data in advance.

    For more information on COMMAREA stripping, see ECI performance considerations when using COMMAREAs.

As with ECIConnectionSpec, you can set properties on the ECIInteractionSpec class at either construction time or by using setters. Unlike ECIConnectionSpec, the ECIInteractionSpec class behaves like a Java™ bean. So, in a managed environment, your server might provide tools to allow you to define these properties using a GUI without writing any code.

To specify a value for ECI timeout, set the ExecuteTimeout property of the ECIInteractionSpec class to the ECI Timeout value. Allowable values are:
No timeout default value.
A positive integer
Time in milliseconds.