IBM WebSphere Developer Technical Journal: Transactional integration of WebSphere Application Server and CICS with the J2EE Connector Architecture

This article explains how the J2EE™ Connector Architecture (JCA) can be used to provide transactional integration of J2EE applications deployed within the JCA-managed environment of WebSphere® Application Server with existing applications deployed in CICS®.

Phil Wakelin (Phil_Wakelin@uk.ibm.com), CICS Transaction Gateway Technical Planner, IBM

Phil Wakelin is the CICS Transaction Gateway Technical Planner at IBM Hursley, and is responsible for the future development plans of this product, which provides connectivity from WebSphere Application Server to CICS. He joined IBM in 1990 and originally worked in the System Test department of IBM Hursley, where he worked on most platforms and versions of CICS before joining the Installation Support Center, as a pre-sales support specialist for CICS client-server. He then worked at the IBM International Technical Support Centre, in IBM San Jose, for 3 years where he was responsible for the development and publishing of 11 CICS related IBM Redbooks. He is an IBM Certified Solutions Expert, CICS Web Enablement, and a Senior IT Specialist, and holds a BSc degree in Applied Biology from the University of Bath, UK.



David Seager (SEAGER@uk.ibm.com), Web Services Gateway and WSIF L3 Service, IBM

David Seager joined IBM in 1997. He worked as a software developer and a system tester for the CICS Transaction Gateway before moving into his current role in the Web Services support team. In his time at IBM, David has worked with extensively with WebSphere Application Server extensively, and is the author of several articles on developerWorks WebSphere.



04 August 2004

Introduction

Get the products and tools used in this article

If you are a developerWorks subscriber, you have a single user license to use WebSphere Application Server, CICS Transaction Gateway, and other DB2®, Lotus®, Rational®, Tivoli®, and WebSphere products -- including the Eclipse-based WebSphere Studio IDE -- to develop, test, evaluate, and demonstrate your applications. If you are not a subscriber, you can subscribe today.

In this article, we will provide an overview of fundamental transactional concepts and then take a closer look at the transactional environments within CICS Transaction Server for z/OS® (CICS TS), the CICS Transaction Gateway (CICS TG), and WebSphere Application Server. We will provide a detailed analysis of the transactional controls available for servlet and EJB™ components within WebSphere Application Server, and explain how to use these controls to provide transactional integration between applications deployed in WebSphere Application Server and in CICS.

This article is written for application designers and architects who require an understanding of the transactional implications of using the JCA with CICS. It assumes a basic knowledge of both CICS and the JCA, and is not designed to cover other decision factors, such as connection management or security. (See Resources for more information on these topics.)


Transactions: what are they?

In the J2EE world, a transaction is a unit of activity within which multiple updates to recoverable resources are made atomic (that is, as an indivisible unit of work), such that either all or none of the updates are made permanent. In the CICS world, however, a "transaction" refers to the work performed by a CICS program (or sequence of programs) invoked by a specific transaction-identifier, and which runs under a specific CICS task. This CICS task can itself be composed of multiple recoverable units-of-work (also known as logical units of work) demarcated by synchronization points (syncpoints). These units-of-work are the recoverable atomic units, and as such are analogous to the transactions of the J2EE world.

Essential components

Within a transactional environment, all participants are classified as either resource managers or transaction managers. A resource manager is responsible for managing recoverable data, such as files or queues. A transaction manager has transactional responsibility and coordinates the outcome of the transactions across multiple resource managers. Between them, the transaction manager and the resource managers are responsible for reliably coordinating the updates to recoverable resources, such that the transactional rules of atomicity, consistency, isolation, and durability are maintained. To achieve this, it is necessary for each participant to implement a common architectural standard. In the next section, we will briefly look at the following standards and protocols:

  • CICS Intersystem Communication (ISC)
  • J2EE Connector Architecture (JCA)
  • Two-phase commit.

CICS itself has its own private transactional intersystem communication (ISC) protocol, which is predominantly based upon the LU6.2 SNA formats and protocols. The ISC protocol allows multiple CICS systems across different MVS systems or different platforms (such as iSeries or UNIX systems) to support extended units of work between CICS applications in these disparate systems. (For more information, see the CICS Intercommunication Guide, SC34-6243.)

The JCA is part of the J2EE standard and specifies the system contracts to be implemented by a resource adapter. These system contracts define the qualities of service that a resource adapter provides for transaction management, connection management, and security (see Figure 1).

Figure 1. JCA system contracts
Figure 1. JCA system contracts

In the J2EE architecture, a distributed transaction is referred to as a global transaction, and transactional systems that manage recoverable resources are known as resource managers, examples being CICS, IMS™, and DB2. These resource managers are categorized according to their support for transactions, into those that support two-phase coordination (by offering an XAResource interface), those that support only one-phase coordination (through a LocalTransaction interface), and those that are non-transactional.

For transaction management, the resource adapter is required to implement one of the following contracts, as defined in the resource adapter's deployment descriptor (ra.xml):

  • XAResource
    A transaction participant that is called during two-phase commit and which can influence the outcome of the transaction. Typically, an XAResource is implemented by a resource manager and is used to support the external coordination of the resource manager's transaction branch. Enlistment of an XAResource in a transaction is managed by the application server and is not a concern of the application.
  • LocalTransaction
    A resource adapter that can participate in transactions that are local to the resource manager, but cannot participate in two-phase commit transactions (other than as an only agent or a last participant). For the sake of clarity in this document and other WebSphere-related publications and papers, we use the term "resource manager local transactions" (RMLTs) to refer to a transaction that is local to a single resource manager.
  • NoTransaction
    A resource adapter with no transactional properties, this can participate in a transactional context but is not influenced by, and has no effect upon the outcome of the transaction.

The WebSphere Application Server transaction support provides coordination, within a transaction, for any number of two-phase capable resource managers. It also enables a single one-phase capable resource manager to be used within a transaction in the absence of any other transactional resource managers. Non-transactional resource managers may also be used within a global transaction but do not participate in the scope of the global transaction.

The CICS ECI resource adapter implements the LocalTransaction interface and so has limited support for global transactions. However, when running within WebSphere Application Server for z/OS, the CICS ECI resource adapter supports global transactions, if a local Gateway is used. This signifies the CICS Transaction Gateway runs within the WebSphere Application Server address space and so can use internal functions of the MVS Resource Recovery Services (RRS) available only on z/OS. This provides RRS global transaction support, and allows the CICS ECI resource adapter to participate in a global transaction in WebSphere Application Server for z/OS with any number of other two-phase capable resource managers.

The CICS EPI resource adapter, which can be used for access to 3270 terminal based programs, has no global transactional support. This is due to the nature of the CICS 3270 interface upon which it is based, and as such should not be used for transactional integration of CICS applications.

Two-phase commit

An essential part of all transactional standards is the two-phase commit process. This is an architected set of flows that transaction managers use to ensure all resource managers in a transaction can be reliably coordinated, irrespective of any failure. It is implemented by all transactional protocols and the fundamental concepts are essentially the same. The following description summarizes the flows according to the XA specification; other protocols such as CICS or LU6.2 may use different terminology and variants on the flows. (For further details on the CICS syncpoint flows refer to the CICS Intercommunication Guide, SC34-6243, Chapter 2: Recovery and restart in interconnected systems.)

In the first phase (or Stage 1), the transaction manager asks all the resource managers to prepare to commit recoverable resources (prepare), each resource manager can vote either positively (prepared) or negatively (rolled-back). If a resource manager is to reply positively, it records stably the information it needs to do so and replies prepared, and is then obliged to follow the eventual outcome of the transaction as determined at the next stage. The resource manager is now described as in-doubt, since it has delegated eventual transaction control to the transaction manager.

In the Stage 2, providing all the resource managers voted positively, the transaction manager replies to each resource manager with a commit flow. Upon receipt of the commit flow, the resource manager finalizes the updates to recoverable resources, and releases any locks held on the resources. The resource manager then responds with a final "committed" flow, which indicates to the transaction manager that it is no longer in-doubt. If the final committed flow is not received by the resource manager, the transaction manager must assume the commit was also not received by the resource manager, and so would need to re-transmit the commit.

Figure 2. Two-phase commit
Figure 2. Two-phase commit

Although the two-phase commit process is usually a prerequisite to distributed transactional support, there are certain instances where a single-phase commit process can be sufficient. Within the J2EE transactional environment, the last participant support (LPS) function of WebSphere Application Server Enterprise extends the global transaction model to allow a single one-phase commit resource to participate in a global transaction with any number of two-phase commit capable resources. At transaction commit, the application server first prepares the two-phase commit resource managers and, if this is successful, the one-phase commit-resource is then called to commit. The two-phase commit resources are then committed or rolled back depending on the response of the one-phase commit resource, effectively delegating transaction coordination to the one-phase commit resource.

Figure 3. Last participant support
Figure 3. Last participant support

Unlike a two-phase commit resource, there is no recovery from a communication failure with a one-phase commit resource. Such a communication failure during commit of the one-phase commit resource introduces the risk of a mixed outcome to the transaction. The two-phase commit resources are rolled back, but the outcome of the one-phase commit resource is unknown; it could have committed or rolled back. Applications must therefore be configured to accept the additional risk of such heuristic outcomes; further details are given in the discussion for question 5 in Transaction deployment scenarios.

Outside of WebSphere Application Server for z/OS, the CICS ECI resource adapter can only be used as a LocalTransaction capable resource adapter, and so can be used to good effect with the LPS function of WebSphere Application Server. With the use of LPS, the J2EE component does not need to be concerned with the order in which updates are made within the transaction, as the commit process is handled entirely by the application server container.

Recoverable logging

In order to implement recovery from failure scenarios, the transaction manager and the resource manager must be able to recover from a failure at any point in the transactional flow. This is achieved by using a transactional log, based on a recoverable media (such as physical DASD). If a critical failure occurs during any critical period of processing, then, upon restart, either the transaction or resource manager are able to replay work from the log to discover at what point processing previously terminated, and if any transactions were left in doubt. WebSphere Application Server on distributed platforms and CICS TS on z/OS both implement their own internal logging systems. WebSphere Application Server for z/OS and the CICS TG for z/OS both utilize the recoverable logging provided by the transactional services of RRS.


The CICS unit-of-work: transactions, tasks, and syncpoints

As discussed previously, the term "transaction" is highly overloaded. In this article, we refer to a CICS transaction as the work initiated in a CICS region, and which runs under a four-character transaction ID (tranid). These tranids are CICS resource definitions which name the initial program to be loaded and the properties of the CICS transaction under which the associated task will run. Historically, these were defined by macros which built a Program Control Table (PCT), but are nowadays defined in TRANSACTION definitions within the resource definition on-line (RDO) database. At transaction initiation, CICS implicitly starts a new task; this is the initial boundary of the transactional work to be undertaken. All updates to recoverable resources or requests to other transactional systems are now part of this unit-of-work, until a synchronization point (syncpoint) is reached within the CICS program. The syncpoint can be explicitly coded within the CICS application using the EXEC CICS SYNCPOINT command, or is implicitly reached when the task terminates. At the syncpoint, CICS, as the transaction manager, will prepare all the associated resource managers and coordinate an atomic result either as a successful commit or, if this is not possible, a rollback, where all recoverable updates are rolled back to their state prior to the start of the unit-of-work (see Figure 4).

Figure 4. CICS transactions
Figure 4. CICS transactions

In certain circumstances, such as if an intersystems distributed program link (DPL) request is used, the CICS transaction that is linked to can be coordinated by a remote CICS system. The CICS TG extends this situation by using the external call interface (ECI) to initiate and coordinate the CICS unit-of-work. Within the terms of the CICS Transaction Gateway, this is referred to as an extended logical unit of work. When a DPL request is used to invoke a CICS program, the CICS program is no longer permitted to execute a syncpoint command, since the transaction is coordinated by a remote system.

Figure 5. Extended unit-of-work
Figure 5. Extended unit-of-work

Additionally, the converse situation is also possible; this is where the invoked CICS transaction runs in a separate transactional context to that of the invoking application. This is referred to as running with sync-on-return, which refers to the fact that the controlling mirror transaction in CICS issues a syncpoint on returning control to the calling application (see Figure 6) . The use of a sync-on-return type link also allows the called CICS program to issue EXEC CICS SYNCPOINT commands, since it is not sub-ordinate to another transaction manager.

Figure 6. Link with sync-on-return
Figure 6. Link with sync-on-return

Transactional support with the CICS Transaction Gateway

When using the CICS Transaction Gateway to provide transactional integration from J2EE applications to CICS, the underlying connectivity is provided by the ECI, which allows the calling application (such as a J2EE servlet or EJB component) to coordinate the invoked CICS transaction. However, to understand the function provided, it is necessary to understand the transactional support provided by the CICS Transaction Gateway regarding the essential transaction components of two-phase commit network connections and recoverable logging.

When using the ECI protocol, there are potentially two different network connections to consider, namely the connection from the J2EE component into the CICS Transaction Gateway, and the network connection from the CICS Transaction Gateway into CICS (see Figure 7). A variety of network protocols are supported for these connections as follows:

  • J2EE component to CICS Transaction Gateway: TCP/IP, SSL or local bindings
  • CICS Transaction Gateway to CICS: SNA, TCP62, TCP/IP, EXCI.

Out of these possible options, the only protocol that supports two-phase commit transactional coordination for ECI flows is the External CICS Interface (EXCI). This is an interface provided by CICS TS for z/OS, and provides transactional support in conjunction with MVS™ Resource Recovery Services (RRS), when the CICS Transaction Gateway and the target CICS region are in the same MVS image. This support, together with the CICS Transaction Gateway local mode (a form of local bindings), provides two-phase commit global transaction support when running in local mode within WebSphere Application Server for z/OS. In all other circumstances, a one-phase commit connection has to be used, and so the CICS Transaction Gateway has to be considered a local transaction capable resource manager.

When the CICS Transaction Gateway is utilized as a mid-tier component in a JCA-based infrastructure, there are several components and associated connections involved in controlling the interaction with CICS. The Gateway daemon is at the centre of this, and interacts with both the WebSphere Pool Manager and the connected CICS system (see Figure 7).

Figure 7. Thread interactions for JCA connections
Figure 7. Thread interactions for JCA connections

When an ECI request is made from a J2EE component to the Gateway daemon, a connection must first be established from the CICS ECI resource adapter to the Gateway daemon. This connection is managed by the WebSphere Connection Management Pool Manager, which controls the allocation and pooling of the underlying connections to the Gateway daemon. Each connection represents a socket connection to the Gateway daemon, and at the Gateway daemon, this socket connection is managed by a dedicated Connection Manager thread for the lifetime of the socket. If this connection is lost, then the transactional context will be terminated, and the Gateway daemon and WebSphere Application Server will rollback any associated work.

For further details on Connection usage with the WebSphere Connection Management Pool Manager refer to Sharing Connections in WebSphere Application Server V5.


Transactional support in WebSphere Application Server

WebSphere Application Server provides differing qualities of services for the different types of J2EE components, achieved through the use of a set of containers. The four containers are the Web container, EJB container, client container and applet container. In WebSphere Application Server V5, JCA support is provided within the Web and EJB containers, both of which provide support for the JCA connection pooling mechanism and propagation of the transaction context from the J2EE component to a JCA interaction.

Web container

The principal function of the Web container is for servlet and JSP components, but it still provides global transaction support. There are, however, no container managed transaction services provided by the Web container, but applications can programmatically utilize either local transactions or bean-managed transactions (BMT). Resource manager local transactions can be controlled by invoking the method getLocalTransaction() on the Connection object obtained from the ECIConnectionFactory; this provides a programmatic transactional context specific to that instance of the JCA connection factory. BMT can be created by using the javax.transaction.UserTransaction interface to begin and end a transaction. Such applications have to commit the transaction by the end of the lifetime of the HTTP request. It is not possible, or desirable, to extend the lifecycle of a transaction over multiple HTTP requests to a servlet, and any global transactions not ended by the end of the servlet service() method are rolled-back by WebSphere Application Server.

EJB container

The EJB container provides full transactional support for global transactions, including container managed transactions (CMT) and bean managed transactions. Session beans and message-driven beans may employ either type; Entity beans are restricted to CMT only. Beans that employ BMT are responsible for transaction demarcation and must use the javax.transaction.UserTransaction interface to begin and end a transaction. CMTs are the preferred mechanism, as this delegates transactional control to the application server, allowing the developer to concentrate on developing the business logic, while still allowing the transactional properties of the application to be decided upon deployment. The key to transactional control with CMT is the EJB transaction attribute, which is discussed next.

Transaction attribute

The transaction attribute is set in the EJB deployment descriptor (the ejb-jar.xml file), and is the attribute for controlling under which circumstances a global transaction is started when a bean method is invoked. This transaction attribute appears in the <container-transaction> section and is specified with the <trans-attribute> tag. For example, the following XML defines that the remote execute() method on the CTGTesterCCI bean has the transaction attribute of Required.

<container-transaction>
   <method>
      <ejb-name>CTGTesterCCI</ejb-name>
      <method-intf>Remote</method-intf>
      <method-name>execute</method-name>
   </method>
   <trans-attribute>Required</trans-attribute>
</container-transaction>

The use of the WebSphere Studio Application Developer EJB Deployment Descriptor editor to define these settings is shown in Figure 8.

Figure 8. Transaction attribute in WebSphere Studio Application Developer
Figure 8. Transaction attribute in WebSphere Studio Application Developer

The possible values for the transaction attribute and their descriptions are provided in Table 1:

Table 1. EJB Transaction attributes

Transaction AttributeDescription
NotSupportedBean method does not execute within context of a transaction.
RequiredBean method must execute within context of a transaction.
RequiresNewBean method must execute within context of a new transaction.
SupportsBean method can execute with or without a transaction context.
MandatoryBean method must execute within context of EJB client's transaction.
NeverBean method must not be invoked in context of a transaction.

Local transaction containment

The EJB 2.0 specification does not specify the behavior of the container in the case where a method runs without a global transaction. This can happen for servlets, session beans using bean-managed-transactions, and a few other scenarios. In this case, the application is said to be executing under an "unspecified transaction" context. In order to implement consistency and portability, WebSphere Application Server implements this unspecified transaction context using a local transaction containment (LTC) policy. This LTC policy is effectively a scoping device used by the Web and EJB containers to demarcate the beginning and end of work dispatched outside a global transaction. Any access to a resource manager (such as CICS) within such a LTC is via a resource manager local transaction (RMLT) that must be resolved by the end of the LTC. There is no programmatic control of the LTC possible, and the way LTC scoping affects a J2EE application is controlled by three extended deployment descriptors (XDDs) which can be set on the J2EE component at deployment, as follows:

  • Boundary
    This can have the value BeanMethod (default) or ActivitySession. ActivitySession is an extension to the EJB container available only in WebSphere Application Server Enterprise Version 5. It provides an extended unit-of-work scope beyond the method boundary for local transaction based resource managers. (See Transactional services in WebSphere Application Server Enterprise V5, REDP3759 for more information.)
  • Resolver
    This can have the values ContainerAtBoundary or Application (default). When an ECI request is made from the EJB container outside of a global transaction context (such as with a transaction attribute of Never), then if the Resolver attribute is set to Application, the ECI call type will be non-extended. Conversely, if the Resolver attribute is set to ContainerAtBoundary, then a resource manager local transaction will be started, and the ECI call type will be extended and be resolved by the container at the EJB method boundary.
  • UnresolvedAction
    This can have the value Commit or Rollback (default). It can be specified for the EJB or Web containers, and signifies how the container should clean up any Connections with an outstanding RMLT at the LTC boundary. This is the only configurable LTC setting for Web components (servlets), and applies to bean managed transactions using the LocalTransaction.begin() method on a Connection. All container managed transactions are auto-committed after the interaction completes, and so this attribute is not used by container managed transactions in the Web container.

The following should be noted about the usage of the LTC policy:

  • LTC scope is local to each J2EE component; thus if EJB component A is dispatched under LTC A and then calls EJB component B, component B will be dispatched under a separate LTC.
  • The container always establishes a LTC scope if an application executes outside a global transaction, unless Web components or BMT enterprise beans are at a level prior to J2EE 1.3.

Transactional deployment scenarios

In this section, we explain the transactional implications of deploying servlet and EJB components into the WebSphere Application Server environment, and how the transactional controls can be effectively utilized. For both the Web container and EJB container environments, we have posed a set of frequently asked questions and provide practical solutions to the questions or scenarios posed:

  1. Can I make multiple ECI requests from a servlet, within the same transactional scope?
  2. Can I use a global transaction with ECI requests in the Web container?
  3. Can I make multiple ECI requests from an EJB component, within the same transactional scope?
  4. Can I use two different connection factories and make multiple ECI requests within the same transactional scope?
  5. How can I make an ECI request to CICS part of a global transaction?
  6. If I use WebSphere Application Server on z/OS, is the support any different?
  7. What if I use the CICS TG ECIRequest class or the VisualAge for Java Common Connector Framework (CCF) classes within WebSphere Application Server?

Deployment to the Web container

Servlet components deployed in the Web container lack most of the transactional attributes of EJB components. However, the Web container does support both RMLTs and the LTC containment policy, and both of these can be used with some affect for JCA requests made by the ECI resource adapter.

  1. Can I make multiple ECI requests from a servlet, within the same transactional scope?

    If the execute() method is invoked twice on an interaction, this will invoke two corresponding ECI calls to CICS. This is illustrated in the following code sample:

    Context ic = new InitialContext();
    cxfn = (ConnectionFactory) ic.lookup("java:comp/env/eis/ECICICS");
    Connection cxn= cxnf.getConnection();
    Interaction ixn= cxn.createInteraction();
    ECIInteractionSpec ixnSpec= new ECIInteractionSpec(SYNC_SEND_RECEIVE,"CICSPROG");
    JavaStringRecord jsr = new JavaStringRecord()
    
    jsr.setText("DATA1");
    ixn.execute(ixnSpec, jsr, jsr);
    ...
    jsr.setText("DATA2");
    ixn.execute(ixnSpec, jsr, jsr);
    ...
    ixn.close();
    cxn.close();

    However, rather than the two requests to CICS running under the same transactional context, you will find that they each run as a separate unit-of-work in CICS, and will use a separate instance of the CICS mirror transaction. This is because, within the Web container, each Interaction is auto-committed before a subsequent request is issued.

    If you require that two such requests to CICS run in the same transactional scope, then there are two solutions you can consider. The first is to use the transactional controls of the EJB container as discussed in question 3, the second is to programmatically create and control the RMLT. This is illustrated in the following code sample:

    Context ic = new InitialContext();
    cxfn = (ConnectionFactory) ic.lookup("java:comp/env/eis/ECICICS");
    Connection cxn= cxnf.getConnection();
    Interaction ixn= cxn.createInteraction();
    ECIInteractionSpec ixnSpec= new ECIInteractionSpec(SYNC_SEND_RECEIVE,"CICSPROG");
    JavaStringRecord jsr = new JavaStringRecord()
    
    LocalTransaction tran = cxn.getLocalTransaction();
    tran.begin();
    
    jsr.setText("DATA1");
    ixn.execute(ixnSpec, jsr, jsr);
    ...
    jsr.setText("DATA2");
    ixn.execute(ixnSpec, jsr, jsr);
    ...
    tran.commit();
    ixn.close();
    cxn.close();

    When controlling such a set of interactions, the transactional context is local to a single Connection and thus to the underlying ConnectionFactory and CICS region that it references. Therefore, a global transaction context is not necessary to maintain transaction integrity, as there is only one resource manager within the transaction. However, the addition of any other recoverable updates within the transactional scope is not supported, as a global transaction would then be required.

  2. Can I use a global transaction with ECI requests in the Web container?

    If the ECI resource adapter is being used in local mode on WebSphere Application Server for z/OS, the CICS Transaction Gateway RRS support does allow an ECI request to participate in a bean-managed global transaction. However, as the Web container does not support container management of global transactions, all servlet global transactions must be controlled using the javax.transaction.UserTransaction interface (that is, a bean-managed transaction). However, in other deployment scenarios (such as when using WebSphere Application Server on distributed platforms) global transactions are not supported in the Web container because of the restriction that the ECI resource adapter only supports the LocalTransaction interface.

Deployment to the EJB container

The EJB container in WebSphere Application Server is ideally suited to the deployment of transactional components, and provides support for both container and bean managed transactions. Container managed transactions provide the advantage that all transactional coordination is carried out by the J2EE server, and the application developer can concentrate on the development of business logic rather than transactional logic. In order to control the behavior of transactional components, the EJB container offers a set of attributes that can be used to control the transactional behavior of container managed components. In this section, we will describe these attributes and illustrate how they can be used in conjunction with the CICS ECI resource adapter.

  1. Can I make multiple ECI requests from an EJB component, within the same transactional scope?

    Both the setting of the transaction attribute, and whether or not a global transaction context is present, will affect the ECI call type and the resulting transactional scope in CICS. Table 2 describes the resulting ECI call type and the transactional scope of the CICS mirror task. A long running CICS mirror task indicates an extended unit-of-work in CICS, whereas a synconreturn mirror task signifies that the CICS transaction runs in a separate CICS transaction context to that of the EJB component, and the mirror task terminates after the end of each ECI call.

    Table 2. ECI call type for EJB transaction attributes

    AttributeECI call typeCICS mirror task transactional scope
    NotSupportedNon-extendedSynconreturn
    RequiredExtended logical unit-of-workLong running
    RequiresNewExtended logical unit-of-workLong running
    SupportsDepends on existing transaction context; the bean method is executed either under the caller's transaction context, and the ECI call will used an extended logical unit-of-work, or, if there is none present, then it executes under an unspecified transaction context. If under an unspecified transaction context, then the LTC settings control the resulting ECI call type. (See Local transaction containment.)Synconreturn or long running
    MandatoryExtended logical unit-of-work or Exception thrown; the bean method is executed under the caller's transactional context. If the caller does not supply a context (in other words there is no global transaction active), then the execute fails with an exception. If there is a global transaction active, the ECI call will used an extended logical unit-of-work. Long running
    NeverNon-extendedSynconreturn
  2. Can I use two different connection factories and make multiple ECI requests within the same transactional scope?

    When two different connection factories are used, they are both considered as separate transactional resources (even if they reference the same CICS TG or CICS region). A code sample using two such connection factories is shown below:

    Context ic = new InitialContext();
    // Create first connection factory and get connection
    cxfn1 = (ConnectionFactory) ic.lookup("java:comp/env/eis/ECICICS1");
    Connection cxn1 = cxnf1.getConnection();
    // Create first interactin and flow to CICS
    Interaction ixn1 = cxn1.createInteraction();
    ECIInteractionSpec ixnSpec1 = new ECIInteractionSpec(SYNC_SEND_RECEIVE,"CICSPROG");
    JavaStringRecord jsr = new JavaStringRecord()
    ixn1.execute(ixnSpec, jsr, jsr);
    
    cxfn2 = (ConnectionFactory) ic.lookup("java:comp/env/eis/ECICICS2");
    Connection cxn2 = cxnf2.getConnection();
    Interaction ixn2 = cxn2.createInteraction();
    ECIInteractionSpec ixnSpec2 = new ECIInteractionSpec(SYNC_SEND_RECEIVE,"CICSPROG");
    jsr.setText("DATA2");
    ixn2.execute(ixnSpec, jsr, jsr);
    
    ixn1.close();
    cxn1.close();
    
    ixn2.close();
    cxn2.close();

    When this code is executed within WebSphere Application Server for z/OS, the RRS global transaction support provided by the CICS ECI resource adapter allows any number of ECI connections to be used in a global transaction scope.

    In WebSphere Application Server on distributed platforms, the JCA LocalTransaction contract supported by the CICS ECI resource adapter provides RMLT support only. Therefore, if this code is executed, the ECI resource adapter will try to create a unique RMLT for each Connection -- and this will fail since, within the EJB container, it is only possible to have a single RMLT within a global transaction scope because of the one-phase nature of a RMLT.

  3. How can I make an ECI request to CICS part of a global transaction?

    There are three ways of achieving this outcome depending on the application server environment and if there are any other XAResource capable resource managers participating in the global transaction:

    1. When the CICS ECI resource adapter is used within WebSphere Application Server for z/OS, the RRS global transaction support provided by the CICS ECI resource adapter allows any number of ECI connections to be used in a global transaction scope.
    2. If there is no XAResource capable resource manager (such as a JDBC data source) enlisted within the transaction, then an interaction with CICS can be part of the global transaction and will be committed when the EJB container commits the global transaction. This is possible because global transactions provide a one-phase optimization of the two-phase commit protocol, in which a one-phase commit flow is used by the transaction manager if there is only a single resource manager branch (that is, only a single resource) involved in the transaction. This is sometimes referred to as "only agent optimization". While this is primarily a performance optimization, it means that it is also possible to support a single one-phase commit resource manager (such as a CICS ECI Connection) in a global transaction that does not need to be prepared.
    3. If an XAResource capable resource manager is enlisted within the global transaction along with a CICS ECI Connection, then usually at commit time an exception occurs within the EJB container with a message saying

      An illegal attempt to enlist a one phase capable resource with existing two-phase capable resources has occurred.

      This is because the EJB container cannot commit a one-phase commit resource together with two-phase commit resources in a global transaction. However, there is a solution to this in the form of the Last Participant Support (LPS) provided in WebSphere Application Server Enterprise Version 5. This allows a single one-phase commit capable resource (such as a CICS ECI Connection) to participate in a global transaction with any number of two-phase commit capable resource managers.

      The LPS function is enabled for a given EJB component via an extended deployment descriptor (XDD). The application assembly tool provides a tab for WebSphere Application Server Enterprise on which there is an Accept heuristic hazard checkbox. Applications deployed with this box checked may use LPS. WebSphere Studio Application Developer Integration Edition provides an Extended Services tab on the J2EE Application Deployment Descriptor editor, on which there is a Last participant support checkbox (see Figure 9).

      Figure 9. WebSphere Studio Application Developer: Last participant support
      Figure 9. WebSphere Studio Application Developer: Last participant support
      The WebSphere Application Server Enterprise transaction service can also be configured to write an extra log entry prior to committing a one phase commit resource in order to ensure proper heuristic reporting during recovery. This is done on the Transaction Configuration tab of the Administration console. The option is enableLoggingForHeuristicReporting from the Application Servers => Server => Server properties => Transaction Service menu.
  4. If I use WebSphere Application Server on z/OS, is the support any different?

    In local mode on WebSphere Application Server for z/OS, global transactions are supported by the CICS ECI resource adapter using internal RRS functions. This means that when using global transactions, any number of CICS ECI Connections can participate in a global transaction with other two-phase commit resources. Also in local mode on z/OS, it is forbidden to start a resource manager local transaction (RMLT) by invoking the method getLocalTransaction() on the Connection object obtained from the CICS ECI Connection.

    However, if a remote Gateway is used on WebSphere Application Server for z/OS (that is, a non local GatewayURL is specified in the ConnectionFactory) then the ECI Connection becomes only one-phase commit capable. In this circumstance, WebSphere Application Server for z/OS permits the usage of a single one-phase commit capable resource with any RRS-capable resources in the same transaction. Unlike WebSphere Application Server on distributed platforms, it is not required to specify the LPS XDD properties to utilize this behavior. Also, if a remote Gateway is used, then creating a RMLT is allowed.

  5. What if I use the CICS TG ECIRequest class or the VisualAge for Java Common Connector Framework (CCF) classes within WebSphere Application Server?

    In WebSphere Application Server V5, the ECIRequest class and the CCF classes are only supported within the Web container and only for use with non-extended logical units of work. In addition, they are not able to participate in the JCA-managed environment provided by WebSphere Application Server, and so are not able to participate in the scope of RMLTs or global transactions. Thus, any transactional request applications using these classes will have to be carefully designed and adequate compensation logic utilized to ensure a consistent outcome.


Conclusion

In this article, we reviewed the transactional support provided by both WebSphere Application Server and CICS, and explained how the CICS ECI resource adapter can be used to provide transactional coordination between the two environments. Key to this integration is the JCA transaction management contract, between the resource adapter and the J2EE application server. This contract can be affected by a variety of factors, including usage of the Web or EJB container, the EJB transaction attribute, the LTC settings, and the usage of RRS with WebSphere Application Server on z/OS.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=13480
ArticleTitle=IBM WebSphere Developer Technical Journal: Transactional integration of WebSphere Application Server and CICS with the J2EE Connector Architecture
publish-date=08042004