Transactions

This chapter outlines the concept and process of a transaction and describes some transaction errors.

1. Overview

A transaction is a unit of work that changes a resource from a valid state to another.

Tmax supports local and global transactions.

  • Local Transaction

    A local transaction is a transaction that involves one resource manager (database).

  • Global Transaction

    A global transaction involves a logical unit consisting of more than one resource manager (database) and more than one physical site. All transactions in the Tmax system are handled as global transactions.

Transaction processing in the Tmax system preserves ACID (Atomicity, Consistency, Isolation, and Durability) properties and implements the TX standard of the X/Open DTP model.

The following are the ACID properties.

  • Atomicity

    A transaction is either completed or not (all or nothing).

  • Consistency

    A completed transaction changes a shared resource from one valid state to another.

  • Isolation

    The execution result of a transaction that involves a shared resource is visible only after it is committed.

  • Durability

    The results of committed transactions are permanent even if a system or a media failure occurs.

2. Distributed Transaction

Global transactions that involve two or more databases use the two-phase commit (2PC) protocol to guarantee ACID properties of the transaction. The following describes the two phases of 2PC.

  • Prepare Phase

    The commit manager checks whether the databases participating in the transaction are ready to commit. When all databases are ready, a ready signal is sent.

  • Commit Phase

    When all databases send a ready signal, the transaction is committed. If a database fails to send a ready signal, the transaction is rolled back.

figure2 7
Two-phase Commit (2PC) Protocol

During a distributed transaction processing, the 2PC protocol ensures data integrity. Also, a number of functions such as tx_begin, tx_commit, and tx_rollback enable global transaction processing. In addition, a multi-thread transaction manager ensures improved resource efficiency and dynamic error logging. Dynamic error logging enables a quick response to errors and supports reliability through recovery and rollback. All transactions are monitored through a single interface to facilitate easy scheduling and management of transactions.

Processing Mechanism

The Tmax system uses a set of standard functions, the Application-to-Transaction Monitor Interface (ATMI), which implements the X/Open distributed transaction model of transaction processing.

The following is the of X/Open DTP structure.

figure transaction
X/Open DTP Structure

The following describes X/Open DTP components.

Classification Description

AP

The application program (AP) defines the boundary of a distributed transaction.

RM

The resource manager (RM) provides access to resources, such as databases.

TM

The transaction manager (TM) assigns identifiers to transactions by each database, manages execution of transactions, and recovers a transaction in case it completes or fails.

CRM

The communication resource manager (CRM) controls communication between between applications that have operations distributed among different computers or databases from different vendors.

OSI-TP

The open system interconnection transaction processing (OSI-TP) manages communication between TMs.

X/OPEN ATMI processes transactions that occur between heterogeneous DBMSs that comply with X/OPEN DTP by grouping them.

The following is how distributed transactions are processed.

figure transaction phase
The Process of Distributed Transactions

A transaction starts when tx_begin() is called and ends when tx_commit() or tx_rollback() is called.

tx_begin() begins a transaction. The calling process becomes transaction publisher that is responsible for closing the transaction by using tx_commit() or tx_rollback(). Processes that are part of a transaction demarcated by tx_begin() and tx_commit() or tx_rollback() are called transaction participants, which can affect the results of the transaction when they return values with tpreturn(). You cannot call tx_begin() to start a transaction if another transaction is being processed, which causes failure and sets tperrno to TPEPROTO. Before calling another transaction, the transaction must be completed first.

A client participating in a transaction can exclude a server from the transaction by setting flags to TPNOTRAN when calling tpcall() or tpacall(). An excluded server cannot affect the result of the transaction being processed.

You can start an explicit transaction by issuing transaction functions such as tx_begin and tx_commit or an implicit transaction by configuring a database in SVRGROUP of the Tmax configuration file.

Checklist for DBMS Integration

The following is a DBMS integration checklist.

  • Check that the DBMS vendor’s client module is installed.

  • Check restrictions on DBMS settings such as maximum session count for database and client.

  • Get ready development tools module needed to create a Tmax server application

  • Check the XA and non-XA settings.

    The use of XA mode must be determined in the application design phase. XA and non-XA modes differ in terms of database access and distributed transaction processing methods as follows:

    Mode Description

    XA

    Settings of the Tmax configuration file is used to access a DBMS. X/OPEN ATMI functions are used to commit or roll back XA transactions, and the commit or rollback is completed through the transaction management server (TMS).

    Non-XA

    DBMS connections, transaction commits, and rollbacks are processed via the developer’s ESQL statement.

2.1. XA Mode

In XA mode, the transaction management server (TMS) provided by Tmax manages transactions.

All transactions are handled as global transactions and are processed with the 2PC protocol to ensure data integrity. To connect and disconnect an RM, you must configure some settings in the Tmax configuration file. Transactions are managed using the Tmax API, which is necessary when processing databases in a distributed environment. The following are steps for executing an XA transaction.

figure transaction xa
XA Mode

To connect to and disconnt a database, tpsvrinit() and tpsvrdone() are not required. As in non-XA mode, connection to the database is made with tmboot, and TMS, which manages commits and rollbacks of global transactions, also connects to the database. Any start, commit, rollback, or rollback cancellation calls of a global transaction must be made via the TX API of the Tmax system or by configuring the Tmax configuration file settings. To use the XA option, go to the SVRGROUP section in the configuration file. Then, check the name of a server group that contains the server application to connect to DBMS and specify the XA option for the server group.

The following is an example of specifying XA mode in the SVRGROUP section.

*SVRGROUP
svg1        NODENAME = tmax,
            DBNAME = ORACLE,
            OPENINFO = "ORACLE_XA+Acc=P/scott/tiger+SesTm=600",
            TMSNAME = svg1_tms
*SERVER
svr1        SVGNAME  = svg1

For more information about server group configuration environment, refer to Tmax Administration Guide.

2.2. Non-XA Mode

In non-XA mode, explicit transaction functions are enabled and global transactions are disabled in a distributed environment. The Tmax system issues explicit transaction functions, and global transactions are disabled in a distributed environment. To enable non-XA mode, you must connect an application to an RM and declare a transaction for the application.

In non-XA mode, a server program uses native SQL and has control over transaction involving the RDBMS, which cannot participate in global transactions supported by the Tmax system. Server programs running in non-XA mode are suitable for executing simple select queries or time-consuming batch server programs. In non-XA mode, you can define transaction boundary and control but only for direction connection between a client application and RDBMS, which does not involve the Tmax system.

The following describes how non-XA mode differs from XA mode.

  • An RDBMS is accessed through the client application’s SQL.

  • The server can request a transaction but the client cannot. It is recommended to issue tpsvrinit() and tpsvrdone() to connect the server to the database or disconnect it.

The following are steps for executing a non-XA transaction.

figure transaction nonxa
Non-XA Mode

  1. Write logic in tpsvrinit() to access the DBMS.

  2. Write explicit logic to roll back and release the DBMS in tpsvrdone().

  3. When a Tmax server application is booted through tmboot or tmboot -S svrname, a connection is established between the DBMS and the Tmax server application process.

  4. After a connection is established, the service logic can send a transaction request, commit, or roll back the transaction via ESQL.

The following is an example of specifying non-XA mode in the SVRGROUP section.

*SVRGROUP
svg1 NODENAME = tmax

*SERVER
svr1 SVGNAME = svg1

For more information about transaction-related functions, refer to Transaction Management or Tmax Reference Guide.

3. Transaction Errors

Transactions errors involve TX and XA.

TX errors are defined in <usrinc/tx.h>, and XA errors are listed by database vendor. For Oracle’s XA errors, refer to <$ORACLE_HOME/rdbms/demo/xa.h>.

3.1. TX Error

The following describes transaction errors.

Error Code Description

TX_NOT_SUPPORTED(1)

Transactions are not supported in this mode.

TX_OK(0)

This transaction has been completed successfully.

TX_OUTSIDE(-1)

A local transaction is being processed.

TX_ROLLBACK(-2)

commit cannot be executed. The transaction is rolled back.

TX_MIXED(-3)

This transaction is partly committed and partly rolled back.

TX_HAZARD(-4)

This transaction has not been completed successfully.

TX_PROTOCOL_ERROR(-5)

This transaction has been abnormally called.

TX_ERROR(-6)

An error has occurred in the database.

TX_FAIL(-7)

The database has failed.

TX_EINVAL(-8)

Invalid parameters have been received.

TX_COMMITTED(-9)

This transaction has been committed independently to the database.

TX_NO_BEGIN(-10)

This transaction has been committed, but a new transaction cannot begin.

3.2. XA Error

The following describes XA errors.

Error Code Description

XA_OK(0)

This transaction has been successfully completed.

XAER_RMERR(-3)

An error has occurred with the resource manager specified in the OPENINFO section.

XAER_NOTA(-4)

The given XID is invalid.

XAER_INVAL(-5)

Invalid parameters have been received.

XAER_PROTO(-6)

The routine has been invoked in an improper context.

XAER_RMFAIL(-7)

Failed to connect to database.

XAER_DUPID(-8)

A duplicate XID exists.

XAER_OUTSIDE(-9)

The database is working outside a local transaction.