The CICS® Transaction
Gateway provides resource adapters that implement the Common Client Interface
(CCI) for interactions with CICS.
Common Client Interface
The CCI is a high level interface defined by the JCA and is available to
J2EE developers using the External Call Interface (ECI) to communicate with
programs running on a CICS server.
The CCI has two distinct class types:
- Generic CCI classes: Generic CCI classes are used to request a
connection to an EIS such as CICS, and execute commands on that EIS, passing input
and retrieving output. These classes are generic in that they do not pass
information that is specific to a particular EIS. Connection and ConnectionFactory
are examples of generic CCI classes.
- CICS-specific CCI classes: CICS-specific classes are used to pass
specific information between the Java™ Client application and CICS. Examples
of CICS-specific classes are:
- ECIConnectionSpec
- ECIInteractionSpec
Applications that follow the programming interface model using the CCI
have a common structure, independent of the EIS that is being used. The JCA
defines Connections and ConnectionFactories that represent the connection
to the EIS. These objects allow an application server to manage security,
transaction context, and connection pools for the resource adapter. An application
must start by obtaining a ConnectionFactory from which a Connection can be
obtained. The properties of this Connection can be overridden by a ConnectionSpec
object. The ConnectionSpec class is CICS-specific, such as the ECIConnectionSpec.
After an connection has been obtained, an Interaction can be created from
the Connection in order to make a particular request. As with the Connection,
Interactions can have custom properties set by the CICS-specific InteractionSpec
class (ECIInteractionSpec). To perform the Interaction, the application makes
a call to the execute() method and uses CICS-specific Record objects to hold
the data.
- Connection Factory: The ConnectionFactory can be obtained in two
ways:
- Managed: If you are using an application server, the ConnectionFactory
is normally created from the resource adapter by means of an administration
interface. This ConnectionFactory has custom properties set for it, for example
the Gateway to be used would be set as a ConnectionURL. When the ConnectionFactory
has been created, it can be made available for use by any enterprise applications
through JNDI. This type of environment is called a managed environment. A
managed environment allows an application server to manage the qualities of
service of the connections.
- Nonmanaged: If you are not using an application server, you must
create a ManagedConnectionFactory and set its custom properties. You can then
create a ConnectionFactory from the ManagedConnectionFactory. This type of
environment is called a non-managed environment. A non-managed environment
does not allow an application server to manage connections.
In order to retrieve data from the CICS server, your J2EE application:
- Uses the ConnectionFactory object to create a Connection object.
- Uses the Connection object to create an Interaction object.
- Uses the Interaction object to execute commands on the EIS.
- Closes the Interaction and Connection.
The following example shows the use of the J2EE CCI interfaces to execute
a command on an EIS:
ConnectionFactory cf = [Lookup from JNDI namespace]
Connection conn = cf.getConnection();
Interaction int = conn.createInteraction();
int.execute([Input output data]);
int.close();
conn.close();