IBM WebSphere Developer Technical Journal: Exploiting the J2EE Connector Architecture

Integrating CICS and WebSphere Application Server using XA global transactions

The integration of CICS® applications with modern J2EE™ components is now a challenge facing many enterprises. This article explains how the J2EE Connector Architecture (JCA) and the CICS Transaction Gateway can be used to provide transactional integration of CICS applications and J2EE components deployed within IBM®WebSphere® Application Server. Updated for WebSphere Application Server V6.x.

Share:

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.



Peter Masters (pmasters@uk.ibm.com), Software Engineer, WebSphere Message Broker Development team, IBM

Peter Masters has worked for IBM for 13 years at the IBM Software Lab in Hursley Park, United Kingdom. His product expertise includes CICS, WebSphere Application Server, and WebSphere Message Broker. You can contact Peter at pmasters@uk.ibm.com.



26 July 2006 (First published 04 August 2004)

Also available in

From the IBM WebSphere Developer Technical Journal.

Introduction

CICS applications are synonymous with transactional qualities of service; the integration of these applications with modern J2EE components is a common challenge today for many enterprises. The J2EE Connector Architecture (JCA) and the CICS Transaction Gateway can be used to provide transactional integration of CICS applications and J2EE components deployed within WebSphere Application Server.

In showing you how to achieve this integration, we will start with an overview of fundamental transactional concepts, then take a closer look at the transactional environments within IBM WebSphere Application Server, CICS Transaction Server for z/OS™ (CICS TS), and the CICS Transaction Gateway (CICS TG), including the new XA, two-phase commit support in CICS TG V6.1 for z/OS. 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 different levels of transactional integration between applications deployed in WebSphere Application Server and CICS.

This article is intended 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.


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:

  • J2EE Connector Architecture (JCA)
  • Two-phase commit.

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 (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 systems that manage recoverable resources are known as resource managers, examples being CICS, IMS™, and DB2®. These resource managers are categorized based on their support for transactions, being that they either support two-phase coordination (by offering a XAResource interface), support only one-phase coordination (through a LocalTransaction interface), or 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 (the ra.xml file):

  • XA Transaction -- A resource adapter that can participate fully in a two-phase commit process, and which can influence the outcome of the global transaction.

  • LocalTransaction -- A resource adapter that can participate in transactions that are local to the resource manager (in our case, the CICS region), but does not have any two-phase commit transactional capability. For the sake of clarity in this document (as in 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.

WebSphere Application Server transaction support provides coordination, within a transaction, for any number of two-phase capable (XA Transaction) resource managers. It also enables a single one-phase capable (Local transaction) resource manager to be used within a transaction in the absence of any other resource managers.

Two-phase commit

An essential part of distributed transaction processing is the two-phase commit process. This is an architected set of flows used to ensure all resource managers in a transaction can be reliably coordinated, irrespective of any failure. The two-phase commit 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.)

Prior to the two-phase commit process, all work performed during the transaction is said to be in-flight, and failure during this period will lead to a rollback of work. The updates only become hardened once the transaction manager initiates the two-phase commit process.

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

In the first phase (or Stage 1) of the two-phase commit process:

  1. The transaction manager asks all the resource managers to prepare to commit recoverable resources (prepare).
  2. 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, replies prepared, and is then obliged to follow the eventual outcome of the transaction, as determined at the next stage.
  3. The resource manager is now described as in-doubt, since it has delegated the eventual outcome of the transaction to the transaction manager and is now in-doubt about the actual outcome of the transaction.

In the second phase (or Stage 2), assuming all the resource managers replied positively:

  1. The transaction manager replies to each resource manager with a commit flow. However, if a resource manager fails to reply, the transaction manager may re-transmit the prepare flow before assuming the transaction should be aborted.
  2. Upon receipt of the commit flow, the resource manager finalizes the updates to recoverable resources, and releases any locks held on the resources or open files.
  3. The resource manager then responds with a final committed flow, which indicates to the transaction manager that it is no longer in-doubt.
  4. If the final committed flow is not received by the transaction manager, the transaction manager must assume the commit did not arrive at the resource manager, and so would need to re-transmit the commit, until a positive reply is received.

Should the transaction manager fail during the commit processing, the transaction may be left in-doubt in the resource managers. Upon restart, the transaction manager will resynchronize with the resource managers, to discover the state of the transactions, and then continue commit processing to either commit or back out transactions as necessary.

Last participant support

Within the J2EE transactional environment, the last participant support function of WebSphere Application Server extends the global transaction model to enable 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 from the one-phase commit resource. This process effectively delegates transaction coordination to the one-phase commit resource.

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

Last participant support is provided as part of WebSphere Application Server Enterprise V5, and is available as a base function in WebSphere Application Server V6 and later.

Unlike a two-phase commit process, there is no recovery from a communication failure with a one-phase commit resource. Thus, a communication failure during commit of the one-phase commit resource introduces the risk of a mixed outcome to the transaction (the heuristic hazard). 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 provided later in this article.


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

As discussed earlier, 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 that 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 online (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 it 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 (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 TG, this is referred to as an extended logical unit of work (Figure 5). Be aware that 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 (Figure 6) . The use of a sync-on-return type link also enables the called CICS program to issue EXEC CICS SYNCPOINT commands, since it is not subordinate 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 enables 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 CICS TG 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. A variety of network protocols are supported for these connections as follows:

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

Of the possible options for connecting from the CICS Transaction Gateway to CICS, the only protocol that provides two-phase commit transactional coordination for ECI flows is the External CICS Interface (EXCI), which is an interface provided by CICS TS for z/OS for batch MVS™ applications, and provides transactional support in conjunction with MVS Resource Recovery Services (RRS). This support is referred to as Transactional EXCI and requires that the MVS batch application (in this case, CICS Transaction Gateway) and the target CICS region are in the same MVS image.

The XA support of CICS TG V6.1 builds on top of the transactional EXCI support by providing global transaction support for requests to CICS via the new CICS ECI XA resource adapter. This provides two-phase commit global transaction support for either local J2EE applications running in WebSphere Application Server on z/OS, or for remote J2EE applications running in WebSphere Application Server on a distributed platform, such as AIX.

However, when CICS TG is running on a distributed platform, a one-phase commit connection still has to be used, and so CICS TG has to be considered a local transaction capable resource manager.

CICS resource adapters

CICS TG now provides three different JCA resource adapters that can be used for outbound communication from a supported J2EE application server to CICS:

  • CICS ECI resource adapter -- This resource adapter implements the LocalTransaction interface and provides support for resource manager local transactions (where the transaction is local to a single resource manager, such as a CICS region). Both JCA 1.0 and 1.5 versions are available for use with J2EE V1.3 and J2EE V1.4 application servers, respectively. This resource adapter is supplied with the CICS Transaction Gateway on z/OS and on multi-platforms, and can be used with any version of CICS on any platform.

  • CICS ECI XA resource adapter -- This resource adapter implements XA transaction support, and has full support for global two-phase commit transactions. It is available only at the JCA 1.5 version and is supplied with CICS Transaction Gateway v6.1 for z/OS, for use within WebSphere Application Server V6 in conjunction with CICS TG for z/OS and CICS TS for z/OS.

  • CICS EPI resource adapter -- This resource adapter can be used for access to 3270 terminal based programs. It has no global transaction support 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. Both JCA 1.0 and 1.5 versions are supplied, although it can only be used with CICS Transaction Gateway on multi-platforms.

RRS transaction support in WebSphere Application Server on z/OS

When using WebSphere Application Server for z/OS, the CICS ECI resource adapters support global transactions through the use of an additional RRS transactional mode. This RRS transactional mode is automatically exploited when a local gateway is used. The use of a local gateway is signified by the setting "local" in the CICS ECI connection factory ConnectionURL parameter, and signifies that the resource adapter should directly invoke the CICS Transaction Gateway EXCI interface within the WebSphere Application Server JVM, thus bypassing the need for a standalone gateway. This method of co-existence provides the dual performance benefits of reduced pathlength and delegation of two-phase commit processing to MVS Resource Recovery Services (RRS).

RRS transactional support is available when using either the CICS ECI resource adapter or the CICS ECI XA resource adapter, and is supported with both JCA 1.0 and JCA 1.5 resource adapters running in WebSphere Application Server V5, V5.1, or V6.


Transactional support in WebSphere Application Server

WebSphere Application Server provides differing qualities of services for different types of J2EE components. This is achieved through the use of a set of isolated run time environments termed containers. The four containers are the Web container, the EJB container, the client container, and the applet container. In WebSphere Application Server V5 and V6, 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.

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, although applications can programmatically control the transaction scope if desired. Resource manager local transactions can be controlled by invoking the method getLocalTransaction() on the Connection object obtained from the ConnectionFactory; this provides a one-phase commit transactional context specific to a single instance of the JCA connection factory (that is, CICS region). A two-phase commit transaction context can also be created by using the javax.transaction.UserTransaction interface to begin and end a transaction. Such applications have to commit the transaction within 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 (BMT). 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 UserTransaction interface to begin and end a transaction. CMT are the preferred mechanism, as this delegates transactional control to the Application Server, enabling the application developer to concentrate on developing the business logic, while still letting the transactional properties of the application 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 (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 have 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 EJB Deployment Descriptor editor in IBM Rational® Application Developer to define these settings is shown in Figure 7.

Figure 7. Transaction attribute in Rational Application Developer
Figure 7. Transaction attribute in Rational 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 will execute within context of a transaction.
RequiresNewBean method will 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 will 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 for a few other scenarios. In this case, the application is said to be executing under an "unspecified transaction" context. 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 means of programmatic interaction with the LTC scope; instead 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 V5. 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. How do I link to a CICS program that issues SYNCPOINT commands?
  3. Can I make multiple ECI requests from an EJB component, within the same transactional scope?
  4. How can I make an ECI request to CICS part of a global transaction?
  5. If I use WebSphere Application Server on z/OS, is the transactional support any different?
  6. What are the advantages of deploying the CICS TG on z/OS?
  7. What happens if there is a network connection failure during two-phase commit processing?
  8. Are there any circumstances when a one-phase commit protocol provides benefits over a two-phase commit protocol?
  9. What failure will occur if a local transaction capable resource adapter (such as the CICS ECI resource adapter) is enlisted in a global transaction?
  10. What support is provided, if I use the ECIRequest class or the Common Connector Framework (CCF) classes within WebSphere Application Server?
  11. What happens if the CICS region or transaction fails unexpectedly?

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, both linked to using the CICS SYNCONRETURN option. 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, recommended approach is to use the transactional controls of the EJB container (see Question 3), and the second is to programmatically create and control the transaction scope with a bean-managed transaction (BMT). This can be achieved with any version of the CICS Transaction Gateway, using the local transaction support of the connection factory, as 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 the Connection object, and thus to the underlying ConnectionFactory and CICS region that it references. This enables multiple requests to be made to CICS, as long as they are all initiated on the same CICS, and are accessed via the same CICS Transaction Gateway.

    If updates are required to multiple resource managers, such as two different CICS systems, then a global transaction context is required. This necessitates the use of the CICS ECI XA resource adapter and the CICS Transaction Gateway V6.1 for z/OS. The BMT must be controlled using the Java Transaction API and the UserTransaction interface, which provides the necessary XA transaction support across multiple connections, if required.

    try  {
    
    Context ic = new InitialContext();
    utx = (UserTransaction) ic.lookup("java:comp/UserTransaction");
    cxfn = (ConnectionFactory) ic.lookup("java:comp/env/eis/ECICICS");
    
    utx.begin();
    
    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);
    
    utx.commit();
    ...
    ixn.close();
    cxn.close();
    } catch (ResourceException re) {
    try {
    userTransaction.rollback();
    }
  2. How do I link to a CICS program that issues SYNCPOINT commands?

    A CICS program that issues a SYNCPOINT command (with or without the rollback option) cannot be subordinate to another transaction manager, and thus cannot be part of an extended or global transaction. This transaction manager could be another CICS system issuing a DPL request, or, in our case, could be the WebSphere Application Server transaction manager which is making a CCI request for the CICS ECI resource adapter. The reason for this restriction is because the linked-to program is effectively a resource manager in a global transaction, and only the transaction manager (the original caller) can control transaction coordination.

    Therefore, to link to CICS programs that issue a SYNCPOINT command, the SYNCONRETURN must be specified on the LINK command; this signifies that the CICS server program will run in its own unit-of-work independent of the client. The use of the SYNCONRETURN behavior on a CCI call is dynamically controlled by the CICS ECI resource adapter in conjunction with WebSphere Application Server. For calls from servlets in the Web container, LINK with SYNCONRETURN is the default behavior for requests (see Question 1), whereas in the EJB container, the container can be exploited by defining a non-transactional property (such as Never) on the EJB transaction attribute, as shown in Table 2.

    The use of this SYNCONRETURN option can be useful, as it frees the CICS program from any transactional control by the remote transaction manager (in our case, WebSphere Application Server) and delegates the outcome of the transaction to CICS. This may sometimes be necessary for application design reasons, and as long as CICS itself is managing all the recoverable updates (such as updates via CICS/DB2 or CICS/VSAM), then transactional integrity within CICS will still be maintained.

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?

    The transaction attribute and the initial presence of a transaction context both affect the ECI call type and the resulting transactional scope of the call to CICS. Table 2 describes the resulting ECI call types 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 mirror task with the synconreturn option signifies that the CICS transaction runs in a separate 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
    RequiredXA transactionLong running
    RequiresNewXA transactionLong running
    SupportsDepends on existing context; the bean method either executes under the caller's transaction context and the ECI call uses an XA transaction, 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
    MandatoryXA transaction 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, then the ECI call type will use an XA transaction.Long running
    NeverNon-extendedSynconreturn
  2. How can I make an ECI request to CICS part of a global transaction?

    There are four ways to achieve this outcome, depending on the application server environment and if there are any other XA capable resource managers participating in the global transaction.

    1. The XA support of the CICS TG for z/OS V6.1 can be exploited to provide global transaction support between any number of CICS regions and other XA compliant resources. The CICS ECI XA resource adapter can be used within any WebSphere Application Server V6 configuration.

    2. The RRS global transaction support within WebSphere Application Server for z/OS, can be exploited to provide global transaction support between any number of CICS regions and other XA or RRS compliant resource managers. This function is based on RRS, requires that CICS, CICS TG, and WebSphere Application Server are used on the same z/OS system, and is applicable to all supported versions of WebSphere Application Server for z/OS and the CICS TG for z/OS.

    3. If there is no XA capable resource manager (such as a JDBC data source) enlisted within the transaction, then the local transaction support of the CICS ECI resource adapter can be used within a 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 connection using the CICS ECI resource adapter) in a global transaction that does not need to be prepared.

    4. The last participant support provided in WebSphere Application Server V6 (and WebSphere Application Server Enterprise V5) enables a single one-phase commit capable resource manager (such as a connection from the CICS ECI resource adapter) 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 enterprise application settings in WebSphere Application Server provides a Last participant support properties page on which there is a Accept heuristic hazard checkbox (Figure 8).

      Figure 8. WebSphere Application Server: Last participant support
      Figure 8. WebSphere Application Server: Last participant support

      The WebSphere Application Server V6 transaction service can also be configured to write an extra log entry prior to committing a one-phase commit resource to ensure proper heuristic reporting during recovery. This should be enabled via the administration console by navigating to Application Servers => Server => Server properties => Transaction Service, then select the Enable logging for heuristic reporting checkbox.

  3. If I use WebSphere Application Server on z/OS, is the transactional support any different?

    When the CICS Transaction Gateway is used in local mode in WebSphere Application Server for z/OS, global transactions are supported by the CICS ECI resource using internal RRS functions. This support is optimized for the z/OS environment and does not require the overhead of the XA transaction flows required for two-phase commit when using a remote Gateway.

    In addition, 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, specifying the LPS XDD properties to utilize this behavior is not required.

    Be aware that the RRS global transaction support provided by CICS Transaction Gateway for WebSphere Application Server for z/OS does not support the use of bean managed local transactions. This means that using the LocalTransaction interface of the CICS ECI connection factory, as detailed in Question 1, is not supported.

  4. What are the advantages of deploying the CICS TG on z/OS?

    CICS TG on z/OS makes use of the EXCI to provide high speed cross memory access to CICS, a mechanism not available on other platforms as it is an MRO-based communications mechanism. The use of the EXCI protocol also enables MVS Resource Recovery Services (RRS) to be used to provide two-phase commit transactional support, which is available via the XA support in CICS TG V6.1.

    CICS TG V6.1 for z/OS also supports TCP/IP load balancing across cloned CICS Transaction Gateway daemons, which enables TCP/IP port sharing to be exploited to provide high throughput and high availability.

  5. What happens if there is a network connection failure during two-phase commit processing?

    If a TCP/IP network connection to the CICS Transaction Gateway daemon is broken while a transaction is in-flight (before the commit processing starts), then the transaction will be marked for rollback in RRS by the CICS Transaction Gateway daemon once it is informed of the outage. However, if the connection is broken during commit processing, then the transaction may be suspended in the in-doubt phase, and the daemon will await a commit or back-out response from the transaction manager (WebSphere Application Server) once a connection is re-established.

  6. Are there any circumstances when a one-phase commit protocol provides benefits over a two-phase commit protocol?

    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, or even preferred:

    • If only a single call to CICS is made and there are no other updates to recoverable resources within the transaction, then it is not necessary to use a global transaction. In this case, a non-transactional request with the SYNCONRETURN option can be used to make the transaction boundary start at the entry into CICS and terminate on return.

    • If all the requests within the global transaction are made through a single CICS system, then the one-phase commit local transaction support provided by the CICS ECI resource adapter may provide sufficient integrity, as a two-phase commit operation is not required. In addition, the performance of requests using local transactions is slightly optimal compared with XA transactions due to the reduced network flows involved when using the RMLTs in WebSphere Application Server. However, the XA protocol does provide some additional integrity to this one-phase commit scenario in its provision of resynchronization and recovery logic for failure during commit processing.

  7. What failure will occur if a local transaction capable resource adapter (such as the CICS ECI resource adapter) is enlisted in a global transaction?

    If a local transaction capable resource adapter is enlisted in a global transaction along with an XA capable resource manager, then at commit time an exception occurs within the EJB container, as the two-phase commit process will not be able to complete the prepare phase with the one-phase commit resource manager. The EJB container will report a message saying An illegal attempt to enlist a one-phase capable resource with existing two-phase capable resources has occurred.

  8. What support is provided if I use the ECIRequest class or the Common Connector Framework (CCF) classes within WebSphere Application Server?

    In WebSphere Application Server V5, the ECIRequest class and the CCF classes are supported only 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.

  9. What happens if the CICS region or transaction fails unexpectedly?

    The XA transaction protocol is a presumed abort protocol. Thus, if there is any failure while the transaction is in-flight (that is, before commit processing is initiated), then all updates will be rolled back. This includes failure such as failure of the CICS sub-system, or network outages. However, processing of CICS abends is treated slightly differently. In the JCA architecture, any failure (including an abend) is propagated back to the calling J2EE component as a ResourceException. If this exception is left uncaught, the default action will be to commit the transaction, including all work performed by CICS, up to the point of the abend. If you wish to ensure that a CICS transaction abend triggers an automatic rollback, there are two ways to achieve this:

    1. In CICS TS V2 and later, the EXCI options table DFHXCOPT has been amended to include the new option ABENDBKOUT={NO|YES}. This option specifies whether or not a CICS transaction abend should trigger an automatic rollback of the RRS Unit of Recovery and force a back-out of all updates made within the CICS unit of work. This option is introduced as APAR PK17426 in CICS TS V3.1 and APAR PK17427 in CICS TS V2.2 and V2.3. (This APAR only applies to the EXCI and so is only applicable to the CICS TG on z/OS.)

    2. If the J2EE application receives a ResourceException, it can detect if the exception represents a CICS transaction abend, and even what the particular CICS abend code was. Once this is detected, then the default action for the EJB can be marked as setRollbackOnly on the EJB session context to force the transaction manager to rollback the transaction automatically. This is illustrated in the following code sample:

      try {
      eciInt.execute(eSpec, jsr, jsr);
      } catch (ResourceException re) {
      
      if (re instanceof com.ibm.connector2.cics.CICSTxnAbendException )
      {
      System.err.println("CICS ABEND detected."+ " 
      	Connection Factory="+targetCF.toString());
      try {
      mySessionCtx.setRollbackOnly();
      } catch(IllegalStateException ise) {
      ise.printStackTrace();
      }

Conclusion

We have reviewed the transactional support provided by both WebSphere Application Server and CICS, and explained how the CICS ECI resource adapters 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 XA or RRS with WebSphere Application Server.

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, Java technology, Architecture
ArticleID=150127
ArticleTitle=IBM WebSphere Developer Technical Journal: Exploiting the J2EE Connector Architecture
publish-date=07262006