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.

See the Backup and Recovery book for additional information on commitment control and XA transactions.

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 AS/400 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 following functions are provided by the DB2 for AS/400 XA resource manager, hereafter referred to as XA resource manager, for use by a transaction manager:

Figure 1-1. XA Functions

Function	Description
db2xa_close()	Close an XA resource manager
db2xa_commit()	Commit an XA transaction branch
db2xa_complete()	Test completion of asynchronous XA request
db2xa_end()	End work on an XA transaction branch
db2xa_forget()	Forget an XA transaction branch
db2xa_open()	Open an XA resource manager
db2xa_prepare()	Prepare to commit an XA transaction branch
db2xa_recover()	Recover XA transactions
db2xa_rollback()	Roll back an XA transaction
db2xa_start()	Start an XA transaction

The following exit functions must be provided by a transaction manager for use by the XA resource manager:

Figure 1-2. XA Exit Functions

Function	Description
ax_reg()	Exit program to dynamically register an XA resource manager
ax_unreg()	Exit program to dynamically unregister an XA resource manager

The XA resource manager also provides 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. The XA resource manager's switch is exported by the QTNXADTP service program and is called db2xa_switch. The flags in the switch provide information about the resource manager including the facts that migration of associations is not supported and asynchronous requests are not allowed. It also contains 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 AS/400 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.

Figure 1-3 shows the interactions between the application program, transaction manager, and the XA resource manager during a typical transaction. The actual interactions that occur during a transaction will vary depending on factors such as the following:

• Whether the transaction is committed or rolled back

• Whether the one- or two-phase commit protocol is used with the XA resource manager

• Whether multiple threads are used to perform the work of a transaction branch

Refer to the X/Open XA Specification for details.

Figure 1-3. Example Using XA APIs

1. The application uses the X/Open Transaction Demarcation (TX) tx_open() interface to open all the resource managers that are linked with the transaction manager. The transaction manager uses the db2xa_open() interface to open an instance of the XA resource manager. The transaction manager may open multiple XA resource managers that will participate in XA transactions. The transaction manager assigns a resource manager identifier (ID) to each resource manager instance. The resource manager ID uniquely identifies the instance within the thread of control in which the application is running. An instance of the XA resource manager can be thought of as an SQL connection to the relational database specified on the *xainfo parameter of the db2xa_open() API.

2. The application uses the TX tx_begin() interface to begin a transaction.

3. The application uses SQL interfaces to access resources managed by DB2 for AS/400.

4. The XA resource manager uses the XA ax_reg() interface to dynamically register itself with the transaction manager. The transaction manager returns a transaction branch identifier (XID) that uniquely identifies the transaction.

5. The application continues its transaction. It may access other resource managers as appropriate.

6. When the transaction has been completed, the application uses the TX tx_commit() interface to commit the work. The transaction manager uses the XA db2xa_end() interface to end the transaction branch.

7. The transaction manager uses the XA db2xa_prepare() interface to prepare the resources for commitment.

8. The transaction manager uses the XA db2xa_commit() interface to commit the resource after all the resource managers involved in the transaction branch have successfully prepared their resources for commitment. When the commit operation is complete, the application can begin another transaction using the TX tx_begin() interface.

Restrictions

Transactions that require the use of an XA resource manager must be performed in SQL server jobs. 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 db2xa_open() API will set the server mode attribute to *YES if the attribute has not already been set. See the DB2 UDB for AS/400 SQL Programming book for additional information about SQL server jobs.

X/Open applications are only allowed to use SQL interfaces to access resources managed by DB2 for AS/400. Both the embedded and call level interface (CLI) SQL interfaces are supported. The relational databases that are accessed by the application may be local or remote. If remote, the remote location must support the SNA LU6.2 two-phase commit protocol. The following interfaces are not supported for use by an X/Open application:

• Control language (CL) or high-level language (HLL) interfaces for local files or distributed data management (DDM) files.

• The Process Extended Dynamic SQL (QSQPRCED) API.

• The Query (QQQQRY) API.

• The commitment control API interfaces documented in the Journal and Commit APIs part.

An application that uses the CLI SQL interfaces must use a single connection to perform all work for a transaction branch. This means that if the XA join function is used so that multiple threads work on a single transaction branch, all the joining threads must use the same CLI connection for that work. A connection must be dedicated to a transaction branch until the transaction branch has been committed or rolled back; that is, a connection must not be used to start a new transaction branch or join a different transaction branch before its current transaction branch has been committed or rolled back. Since CLI connection handles cannot be shared across jobs, this means that the XA join function can be used only by threads within a single job when using the CLI. This restriction does not apply when the application uses embedded SQL.

It is expected that most transaction managers will use the same user profile for all SQL connections. Normally, this is accomplished by specifying the same user profile for the *xainfo parameter of each 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. If, however, embedded SQL is used and the native DB2 for AS/400 security mechanisms are used, the transaction manager must ensure that all work on a transaction branch is performed by jobs or threads using the same user profile. In other words, if the XA join function is used, every joining thread or job must use the same user profile as the thread or job that started the transaction branch; otherwise, a security exposure will exist.