.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.
The model consists of five basic components:
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.
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:
The DB2 for i XA transaction support may also be driven indirectly via these interfaces:
.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:
In these situations, a separate job must be started to run XA transaction branches when the XA APIs for Job Scoped Locks are used.
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.
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
.
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 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.