XA APIs for Transaction Scoped Locks

The following XA APIs for Transaction Scoped Locks are provided by the DB2^(R) UDB for iSeries^(TM) XA resource manager for use by a transaction manager:

• xa_close() (Close an XA Resource Manager (Transaction Scoped Locks)) closes a currently open resource manager in the thread of control.
• xa_commit() (Commit an XA Transaction Branch (Transaction Scoped Locks)) commits the work associated with*xid.
• xa_complete() (Test Completion of Asynchronous XA Request) waits for the completion of an asynchronous operation.
• xa_end() (End Work on an XA Transaction Branch (Transaction Scoped Locks)) is called when when an application thread of control finishes or needs to suspend work on a transaction branch.
• xa_forget() (Forget an XA Transaction Branch (Transaction Scoped Locks)) is called to forget about a heuristically completed transaction branch.
• xa_open() (Open an XA Resource Manager (Transaction Scoped Locks)) is called to open the XA resource manager and to prepare it for use in the XA distributed transaction environment.
• xa_prepare() (Prepare to Commit an XA Transaction Branch (Transaction Scoped Locks)) is called to request that a resource manager prepare for commitment any work performed on behalf of*xid.
• xa_recover() (Recover XA Transaction Branches (Transaction Scoped Locks)) is called during recovery to obtain a list of transaction branches that are currently in a prepared or heuristically completed state.
• xa_rollback() (Roll Back an XA Transaction Branch (Transaction Scoped Locks)) is called to roll back work performed on behalf of the transaction branch.
• xa_start() (Start an XA Transaction Branch (Transaction Scoped Locks)) informs a resource manager that an application may do work on behalf of a transaction branch.
• xa_start_2() (Start an XA Transaction Branch, Extended Version (Transaction Scoped Locks)) informs a resource manager that an application may do work on behalf of a transaction branch.

When using the XA APIs for Transaction Scoped Locks, the XA thread of control is normally considered to be the i5/OS^(TM) thread from which transactional work is requested, regardless of what SQL connection is used to perform that work. However, in some cases, it is useful to use the SQL connection, rather than the i5/OS thread, as the XA thread of control. This can be accomplished by using extensions provided with the DB2 UDB for iSeries implementation of the SQLSetConnectAttr API to start and end work on an XA transaction, rather than the xa_start() and xa_end() APIs. In this environment:

• use SQLSetConnectAttr to set attribute SQL_ATTR_TXN_EXTERNAL to SQL_TRUE to indicate that the CLI connection is to be used as the XA thread of control.
• use SQLSetConnectAttr to set attribute SQL_ATTR_TXN_INFO to SQL_TXN_CREATE to start a transaction branch (similar to xa_start() with no flags).
• use SQLSetConnectAttr to set attribute SQL_ATTR_TXN_INFO to SQL_TXN_FIND to join a transaction branch (similar to xa_start() with the TMJOIN flag).
• use SQLSetConnectAttr to set attribute SQL_ATTR_TXN_INFO to SQL_TXN_RESUME to resume a suspended transaction branch (similar to xa_start() with the TMRESUME flag).
• use SQLSetConnectAttr to set attribute SQL_ATTR_TXN_INFO to SQL_TXN_END to end work for a transaction branch and close SQL and legacy cursors (similar to xa_end() with the TMSUCCESS flag).
• use SQLSetConnectAttr to set attribute SQL_ATTR_TXN_INFO to SQL_TXN_END_FAIL to end work for a transaction branch, close SQL and legacy cursors and mark the transaction rollback only (similar to xa_end() with the TMFAIL flag).
• use SQLSetConnectAttr to set attribute SQL_ATTR_TXN_INFO to SQL_TXN_HOLD to end work on a transaction branch and close SQL cursors except those that were defined WITH HOLD and close legacy cursors (no XA API equivalent). When using this option, each transaction branch must be committed or rolled back before using the connection to perform work on another transaction branch. Also, use SQL_TXN_END rather than SQL_TXN_HOLD for the last transaction branch prior to a disconnect. Unpredictable results may occur if these rules are not followed.
• use SQLSetConnectAttr to set attribute SQL_ATTR_TXN_INFO to SQL_TXN_CLEAR to suspend work on a transaction branch and close legacy cursors (similar to xa_end() with the TMSUSPEND flag).

The following example shows the interactions between the application program, transaction manager, and the XA resource manager during a typical transaction branch when the XA APIs for Transaction Scoped Locks are used. 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.

Example Using XA APIs for Transaction Scoped Locks, Thread of Control is i5/OS Thread

    HLL                 XA                     XA 
    Application         Transaction            Resource
    Program             Manager                Manager 
                                                       

1.  tx_open ----------> xa_open ------------->   
            <----------           <-----------   

                                    XID xxx            
2.  tx_begin ---------> xa_start ------------>   
            <----------           <-----------   

3.  <SQL work> ------------------------------>
            <---------------------------------      

4.      .                                              
        .                                              
        .                                              

5.  tx_commit --------> xa_end -------------->   
                                  <-----------      

6.                      xa_prepare ---------->      
                                  <-----------      

7.                      xa_commit ----------->      
            <----------           <-----------   

Notes

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 xa_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.
   
   
2. The application uses the TX tx_begin() interface to begin a transaction. For each resource manager that will participate in XA transactions, the transaction manager generates a transaction branch identifier (XID) and uses the XA xa_start() interface to start a transaction branch.
   
   
3. The application uses SQL interfaces to access resources managed by DB2 UDB for iSeries.
   
   
4. The application continues its transaction. It may access other resource managers as appropriate.
   
   
5. When the transaction has been completed, the application uses the TX tx_commit() interface to commit the work. The transaction manager uses the XA xa_end() interface to end the transaction branch.
   
   
6. The transaction manager uses the XA xa_prepare() interface to prepare the resources for commitment.
   
   
7. The transaction manager uses the XA xa_commit() interface to commit the resources after all the resource managers involved in the transaction 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.

Example Using XA APIs for Transaction Scoped Locks, Thread of Control is SQL Connection

1. xa_open (specify THDCTL=C on xainfo string parameter). SQLAllocHandle CLI API to allocate SQL environment handle
   
   
2. SQLAllocHandle CLI API to allocate SQL connection handle
   
   
3. SQLConnect CLI API to establish connection
   
   
4. SQLSetConnectAttr to set attribute SQL_ATTR_TXN_EXTERNAL to SQL_TRUE
   
   
5. SQLSetConnectAttr to set attribute SQL_ATTR_TXN_INFO to SQL_TXN_CREATE (this starts a XA transaction branch, similar to start)
   
   
6. Perform SQL work over the CLI connection
   
   
7. SQLSetConnectAttr to set attribute SQL_ATTR_TXN_INFO to SQL_TXN_END (this ends the XA transaction branch, similar to start)
   
   
8. xa_prepare
   
   
9. xa_commit
   
   

Notes

1. As with the XA protocol, once the association with a transaction branch has been ended by setting connection attribute SQL_ATTR_TXN_INFO to SQL_TX_END, SQL_TX_CLEAR or SQL_TX_HOLD, the connection may be used to start, join or resume other transaction branches before committing or rolling back the transaction branch whose association was just ended. Also, the XA commit or rollback requests may be issued from any thread in any job. They are not required to be issued from the same thread that issued the SQLSetConnectAttr to start the transaction branch.
   
   
2. See SQL call level interface for detailed information on the CLI APIs.