XA APIs

DB2^® for IBM^® i provides two sets of XA APIs:

Before you use the XA APIs, you should read the following publications, which describe the X/Open Distributed Transaction Processing model in detail.

X/Open Guide, February 1996, Distributed Transaction Processing: Reference Model, Version 3 (ISBN:1-85912-170-5, G504), The Open Group.
X/Open CAE Specification, December 1991, Distributed Transaction Processing: The XA Specification (ISBN:1-872630-24-3, C193 or XO/CAE/91/300), The Open Group.
X/Open CAE Specification, April 1995, Distributed Transaction Processing: The TX (Transaction Demarcation) Specification (ISBN:1-85912-094-6, C504), The Open Group.

The model consists of five basic components:

An application program, which defines transaction boundaries and specifies actions that constitute a transaction.
Resource managers, such as databases or file access systems, which provide access to resources.
A transaction manager, which assigns identifiers to transactions, monitors their progress, and takes responsibility for transaction completion and for coordinating failure recovery.
Communications resource managers, which control communications between distributed applications within or across transaction manager domains.
A communications protocol, which provides the underlying communications between distributed applications. The protocol is supported by protected resource managers.

This section explains the use of DB2 for i as an X/Open-compliant resource manager, and therefore is concerned only with the first three components of this model. More specifically, it documents the XA interface, which is the portion of the XA Distributed Transaction Processing model that transaction managers and resource managers use to communicate. The XA interface is a bidirectional interface, which consists of a set of UNIX^®-type APIs.

The XA specification requires the resource manager to provide a switch that gives the transaction manager access to these APIs. The switch allows an administrator to change the set of resource managers that are linked with a program without having to recompile the application. This switch is a data structure that contains the resource manager's name, non-null pointers to the resource manager's APIs, a flag, and a version word.

DB2 for i provides a switch for each set of XA APIs. Each switch is exported by the QTNXADTP service program. The switch for the XA APIs for Transaction Scoped Locks is called xa_switch. The switch for the XA APIs for Job Scoped Locks is called db2xa_switch. The flags in each switch provide information about the resource manager including the facts that migration of associations is not supported and asynchronous requests are not allowed. They also contain an array of procedure pointers that give addressability to the XA APIs. The XA APIs are typically called by a transaction manager using these pointers rather than by name. This precludes the transaction manager from having to know the actual function names and from having to link to the service program that actually contains the functions.

The XA specification requires each resource manager to provide a header file that defines data structures and constants common to the operation of transaction managers and resource managers. The DB2 for i XA resource manager ships two header files in file H, library QSYSINC. Member XA contains a header file that is compatible with the XA architecture. Member QTNXADTP contains a header file that is not compatible with the XA architecture. Some of the structure and variable names in header file QTNXADTP have the prefix "db2." Either file can be used, but it is recommended that the XA header file be used rather than the QTNXADTP header file. The examples at the end of the XA APIs assume you use the XA header file.

See the Commitment control topic collection for additional information about commitment control and XA transactions.

Restrictions

Supported Database Interfaces

X/Open applications must use SQL interfaces to access resources managed by DB2 for i. Both the embedded and call level interface (CLI) SQL interfaces are supported.

In particular, the following interfaces are not supported:

Traditional system interfaces for updating local database files or distributed data management (DDM) files, such as Control language (CL) or high-level languages (HLL), except that the following cases are allowed:
- Triggers, stored procedures and user defined functions may use these interfaces for updating local files.
- The application may use these interfaces directly for updating DDM files if all the following are true:
  - The XA APIs for Transaction Scoped Locks are used.
  - IBM i thread is specified as the XA thread of control via the xainfo string of the xa_open() API.
  - SQL server mode is not used.
The Process Extended Dynamic SQL (QSQPRCED) API.
The Query (QQQQRY) API.
The commitment control API interfaces documented in the Journal and Commit APIs category.

The DB2 for i XA transaction support may also be driven indirectly via these interfaces:

IBM DB2 for clients other than IBM i. See Chapter 7: Designing for XA-compliant transaction managers in IBM DB2 Universal Database™ Administration Guide: Planning.
The IBM i Access ODBC driver, which includes support of the Microsoft^® Transaction Server (MTS). See Distributed transaction support.
The IBM i Extended Dynamic Remote SQL (EDRS) APIs. See Extended Dyamic Remote SQL (EDRS) APIs.

If you are writing a new application, you should use the XA APIs for Transaction Scoped Locks. These APIs have fewer restrictions than the XA APIs for Job Scoped Locks, and provide better performance in the following situations:

If multiple SQL connections are ever used to work on a single XA transaction branch.
If a single SQL connection is used to work on multiple, concurrent XA transaction branches.

In these situations, a separate job must be started to run XA transaction branches when the XA APIs for Job Scoped Locks are used.

Considerations for Remote Databases

Local relational databases may be used for both the XA APIs for Transaction Scoped Locks or the XA APIs for Job Scoped Locks without regard to communications protocols. Local databases include those defined for an Indpendent ASP.

When using the XA APIs for Job Scoped Locks for a remote relational database, the RDB connection method must be Distributed Unit of Work (*DUW), and the remote location may be defined for either TCP/IP or SNA LU6.2 connections.

When using the XA APIs for Transaction Scoped Locks for a remote relational database, the RDB connection method must be Distributed Unit of Work (*DUW), the remote location must be defined for TCP/IP connections, and the remote system must support XAMGR Level 7 of the DRDA^® architecture. When using these APIs, it is also important to understand a difference in connection behavior between local and remote databases. See the description of the THDCTL keyword in the xa_open() xainfo string for details.

SQL Server Mode

Transactions that require the use of an XA resource manager must be performed in SQL server jobs if you are using the XA APIs for Job Scoped Locks, or if you are using the XA APIs for Transaction Scoped Locks against a local database. If you are using the XA APIs for Transaction Scoped Locks against a remote database, use of SQL server jobs is required when using the SQL connection as the XA thread of control, and optional when using the IBM i thread as the XA thread of control. An SQL server job is a job whose server mode for Structured Query Language attribute has been set to *YES. Use the Change Job (QWTCHGJOB) API to control the setting of this attribute. The xa_open() and db2xa_open() APIs will set the server mode attribute to *YES if the attribute has not already been set, except when the xa_open() API is used for a remote database and the IBM i thread is specified as the XA thread of control. See the description of the THDCTL keyword in the xa_open() xainfo string for more information regarding the XA thread of control. For additional information about SQL server jobs, see the SQL programming topic collection and the question on What is CLI Server Mode? in DB2 for i SQL CLI Frequently Asked Questions Link outside information center .

User Profiles

It is expected that most transaction managers will use the same user profile for all SQL connections. If the xa_open() or db2xa_open() APIs are used before the connections are started, this can be accomplished by specifying the same user profile for the *xainfo parameter of each xa_open() or db2xa_open() API call. XA applications generally do not use the resource manager's native security mechanisms to limit access to data. Rather, this is done at the application or transaction manager level.

Autocommit

Autocommit must not be in effect for any connection that is used to perform work during an XA transaction branch, regardless of whether the connection was established on the System i platform or some client that drives the IBM i XA transaction support. The default setting for the autocommit attribute is FALSE for connections established on the System i platform. Some clients may implicitly change the autocommit attribute for the connection to a System i platform when a XA transaction branch is started. See the documentation for each client for information about its autocommit behavior.

[ Back to top | UNIX-Type APIs | APIs by category ]