XA APIs
DB2(R) UDB for iSeries(TM) 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 UDB for iSeries 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(R)-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 UDB for iSeries 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 UDB for iSeries 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 Commitment Control for
additional information on commitment control and XA transactions.
Restrictions
Supported Database Interfaces
X/Open applications must use SQL interfaces to
access resources managed by DB2 UDB for iSeries. 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 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 UDB for iSeries 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:
- 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 i5/OS 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 i5/OS 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
DB2 UDB for iSeries SQL Programming Concepts in
the Information Center and the question on What is CLI Server Mode? in the DB2
Universal Database for iSeries SQL CLI
Frequently Asked Questions.
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 a XA transaction
branch, regardless of whether the connection was established on the iSeries or some client that drives
the iSeries XA transaction support. The default setting for the autocommit attribute is FALSE for
connections established on the iSeries. Some clients may implicitly change the autocommit attribute
for the connection to an iSeries server when a XA transaction branch is started. Refer to the
documentation for each client for information about its autocommit behavior.