Home

	Expand Search

XA Interface Integration Guide for CICS, Encina, and TUXEDO Adaptive Server Version 12.5

Chapter 2 The Sybase XA Environment

Chapter 2

The Sybase XA Environment

This chapter describes the X/Open DTP model, and shows how the components of the Sybase XA environment--including the DTM XA Interface, your application program, and Adaptive Server, among others--fit into that model. It also discusses how connections are established and managed in the Sybase XA environment.

Definitions

The X/Open DTP model assumes an understanding of certain terms.

• transaction - a whole unit of work consisting of one or more computational tasks. Most often, a transaction's tasks manipulate shared resources.

• committed transaction - a completed transaction whose changes to any shared resources are permanent.

• rolled-back transaction - a complete transaction whose changes to any shared resources are nullified.

• ACID test - the test of a true transaction; to pass, the transaction must exhibit the following properties:

  • Atomicity - all or none of the results of the transaction take effect.

  • Consistency - if a transaction is rolled back, all resources that the transaction affected return to the state they were in prior to the transaction's execution.

  • Isolation - a transaction's results are visible only to that transaction until the transaction commits.

  • Durability - permanent resource changes resulting from commitment survive subsequent system failures.

• transaction processing - a system of coordinating the transactions that multiple users perform on shared, centralized resources.

• distributed transaction processing - a transaction processing model in which the shared resources are located at distinct physical sites on a computer network.

• local transaction - a transaction that affects data in a single database and whose tasks a single resource manager performs. See "Overview of the X/Open DTP model" for a definition of resource managers.

• global transaction - a transaction that spans more than one database and multiple resource managers.

• transaction branch - a portion of the work that makes up a global transaction.

• transaction identifier - an identifier that a TM assigns to a transaction. The transaction monitor uses the transaction identifier to coordinate all activity related to a global transaction. The resource manager uses the global identifier to match the recoverable tasks it performed for the transaction.

• recovery - the process of bringing a transaction processing system into a consistent state after a failure. Specifically, this means resolving transactions left in a noncommitted state.

Overview of the X/Open DTP model

The X/Open DTP model is a model for software architecture that allows multiple application programs to share resources provided by multiple resource managers, and allows their work to be coordinated into global transactions.

The X/Open DTP model identifies the key entities in a distributed transaction processing environment and standardizes their roles and interactions. The entities are:

• The transaction processing monitor (TM)

• The resource manager (RM)

• The application program (AP)

This section discusses the X/Open DTP functional model, including its major components and their interfaces. Figure 2-1 shows the X/Open DTP model.

These components communicate through the native, XA, and TX Interfaces as described in "How the components communicate".

Components of the model

The X/Open DTP functional model consists of the following components:

• The application program (AP)

• The resource manager (RM)

• The transaction processing monitor (TM)

The AP contains the code written to accomplish a particular transaction or portion thereof. As such, it designates the beginning and end of global transactions.

The RM provides access to shared resources. Database servers, file servers, and print servers are examples of RMs. In a typical X/Open DTP environment, a single AP communicates with more than one RM. In the Sybase XA environment, the RM is an Adaptive Server database.

The TM coordinates the communication between all parties participating in the transaction. The TM assures that the work done by the AP is contained in a global transaction, which commits or aborts atomically.

Specifically, the TM's tasks include:

• Assigning global identifiers to transactions.

• Monitoring the progress of global transactions.

• Coordinating the flow of transaction information between the APs and the RMs.

• Managing the transaction commitment protocol and failure recovery. For details, see "How the components interact".

How the components communicate

The AP, the RM, and the TM communicate via three distinct interfaces: native, TX, and XA.

The native interface is the medium by which the AP makes requests directly to the RM. This interface is RM specific. In the Sybase XA environment, the native interface is either Embedded SQL or Client-Library.

The TX Interface is the medium between the AP and the TM. The AP uses TX calls to delineate transaction boundaries. In other words, the AP requests that the TM start and commit or roll back global transactions, via the TX Interface. This interface is TM specific.

The XA Interface is the medium between the RM and the TM. The DTM XA Interface is Sybase's version of the interface for Adaptive Server. Using XA calls, the TM tells the RM when transactions start, commit, and roll back. The TM also handles recovery.

How the components interact

The components work together to process transactions from initiation through completion.

The AP delimits transaction boundaries. An AP informs the TM, via TX calls, that a global transaction is beginning. The TM then communicates with all available RMs, via XA calls, to associate a single transaction identifier with any work the RMs will do on behalf of the AP within the bounds of the global transaction.

When the AP requests that the TM commit the global transaction, the TM and the RMs use the two-phase commit protocol to guarantee transaction atomicity.

Transaction completion takes place in two phases--the prepare phase and the commit phase. For a detailed description of the two-phase commit protocol, see the Open Client DB-Library/C Reference Manual.

In the prepare phase, the TM requests each RM to prepare to commit its portion of the global transaction. This portion is known as a transaction branch.

In the commit phase, the TM instructs the RMs to commit or abort their branches of the transaction. If all RMs report back that they have prepared their respective transaction branches, the TM commits the entire transaction. If any RM reports that it was unprepared or fails to respond, the TM rolls back the entire transaction.

Figure 2-2 shows a typical transaction branch structure.

Recovery

The TM is responsible for managing global recovery. In certain situations, an administrator may decide to complete its transaction branch independently of the TM. When this occurs, the administrator's decision is called a heuristic decision.

The heuristic decision may be in conflict with the TM's decision. For example, the administrator may commit a transaction branch and the TM may request to abort it.

Such a conflict requires manual intervention from the System Administrator. For a discussion of heuristic decisions in the Sybase XA environment, see Using Adaptive Server Distributed Transaction Management Features.

The Sybase XA environment

The DTM XA Interface relies on Sybase's transaction processing model to implement X/Open's DTP model. Adaptive Server is used as an RM, as shown in Figure 2-3.

Components of the Sybase XA environment

The Sybase XA environment consists of:

• The Sybase DTM XA Interface. This is Sybase's implementation of the XA Interface for Adaptive Server, described in "How the components communicate".

• The Open Client libraries. Client-Library calls can be part of the native interface between your application and the resource manager.

• Embedded SQL/C and Embedded SQL/COBOL. Embedded SQL calls can be part of the native interface between your application and the resource manager.

• One or more Adaptive Servers. These play the role of RMs.

• The XA configuration file. This file contains entries that define client/server connections for use with XA.

• A set of XA-specific dbcc commands. System Administrators use these to manage heuristic transactions.

• TM-specific configuration files and commands.

Chapter 3, "Configuring the XA Environment" explains how to configure these components so that transactions can use the DTM XA Interface to access data stored on Adaptive Server.

Connections in the Sybase XA environment

The X/Open DTP model has no notion of connections, yet connections are central to the Sybase client/server architecture. The Sybase XA environment must resolve this discrepancy.

To this end, the Sybase XA environment introduces the notion of a logical resource manager (LRM).

Identifying connections via LRMs

Each instance of the Sybase RM appears to the TM as one or more LRMs.

An LRM associates a symbolic name with a client/server connection. An AP uses the names to identify the specific physical connection to one or more Adaptive Servers. The TM uses the names to open connections on behalf of the AP.

The following components of the Sybase XA environment contain information about LRMs. The System Administrator configures these files before starting up the TM. For information on the full configuration process, see Chapter 3, "Configuring the XA Environment."

The Sybase XA configuration file

The Sybase XA configuration file contains one entry per LRM. The entry associates the LRM with a physical Adaptive Server name, and assigns pre-connection Client-Library capabilities and properties to the LRM. For details on the XA configuration file, see "XA configuration file for DTM XA Interface".

The CICS XA product definition (XAD)

The CICS XAD contains one stanza per LRM. The stanza assigns each LRM a user name and password in the form of an open string. The user name and password enable the Sybase XA environment to control a particular connection's access to Adaptive Server resources. For details on the CICS XAD file, see "Adding a Sybase stanza to the CICS region XAD definition".

The Encina monadmin create rm command

The monadmin create rm command assigns each LRM a user name and password in the form of an open string. The user name and password allow the Sybase XA environment to control a particular connection's access to Adaptive Server resources. For details on the Encina monadmin command, see "Assigning an open string with monadmin create rm ". Your current version of Encina may have additional commands for specifying RMs.

You can use the Encina enconsole interactive command instead of the shell monadmin command.

For detailed information, see the Encina Monitor System Administrator's Guide and Reference.

TUXEDO's UBBCONFIG file

In addition to modifying the Sybase configuration files, integrating TUXEDO requires customizing the TUXEDO configuration file, UBBCONFIG. The open string is the only portion of the UBBCONFIG file that requires modification. It includes the user name and password, which allow XA-Server to control a connection's access to Adaptive Server resources. See "Setting up the UBBCONFIG file" for details.

Establishing connections

The TM, together with the XA Interface, establishes connections between applications and RMs in several steps.

1. When the CICS region starts up, it issues an XA open call to each LRM configured in an XAD, using the information contained in each open string.

2. The CICS region passes to the XA Interface library the open string associated with each stanza. The open string contains the LRM name, the user name, and the password.

3. The XA Interface looks up the LRM name in the Sybase XA configuration file and matches it to an actual RM name, that is, an actual physical Adaptive Server. The RM name matches an entry in the Adaptive Server interfaces file.

4. The XA Interface establishes one connection to an Adaptive Server for each LRM entry. The XA Interface confers on any connection the pre-connection properties and capabilities configured for the LRM.

1. An application issues a mon_RegisterRmi function, thereby requesting use of an LRM.

2. Using information contained in an open string, the TM issues an XA open call to the LRM (configured in the monadmin create rm command) whose name matches that issued in step 1, above.

3. The TM passes the open string associated with each monadmin create rm command to the XA Interface. The open string contains the LRM name.

4. The XA Interface looks up the LRM name in the Sybase XA configuration file and matches it to an actual RM name--that is, to an actual physical Adaptive Server. The RM name matches an entry in the Adaptive Server interfaces file.

5. The XA Interface establishes one logical connection to an Adaptive Server for each LRM entry. The XA Interface confers on any connection the pre-connection properties and capabilities configured for the LRM.

1. The application uses the LRM specified in the UBBCONFIG file to reference the logical connection for a branch of a global transaction. In using the LRM name, the application implicitly requests and establishes an LRM.

2. The transaction manager passes the appropriate open string to the XA Interface through the LRM whose name matches the one issued in step 1. The XA Interface uses the LRM name, the user name, and the password.

3. The XA Interface looks in the xa_config file to find an association between the LRM name and Adaptive Server. The Adaptive Server name matches an entry in the interfaces file where its network information is kept.

4. The XA Interface establishes one logical connection to an Adaptive Server for each LRM entry. The XA Interface confers on any connection the pre-connection properties and capabilities configured for the LRM.

Distributing work across LRMs

The System Administrator and the application programmer together must agree on the number and names of LRMs that their Sybase XA environment includes.

The System Administrator configures the TM and Sybase XA configuration files accordingly. The application programmer invokes a particular LRM name within the application code to send a portion of a global transaction across that connection. The TM coordinates this distribution.

You can configure the Sybase XA environment for more connections than are actually used. That is, the XA configuration file may contain inactive entries.

Figure 2-4 depicts the relationship between the Sybase XA configuration file, TM configuration file, application code, and Adaptive Server interfaces file for a CICS environment.