DB2 CLI Access Module

This section describes how to use the DB2 CLI Access Module with XA functionality. This chapter assumes that you have followed the instructions for installing and building the DB XA Module with DB2 CLI. These instructions are located in Appendix A, “Installing and Building the DB XA Module,” of the manual Installing and Building Your SourcePro Products.

As explained in Chapter 4 , XA connections to your database are established by using the database() function in RWDBManager, and providing its propertyString parameter with key XA=xaParameter. This section explains how you obtain the DB2-specific value of the xaParameter argument.

When you run on DB2, the value of the xaParameter argument must be the same as that used for the database alias parameter in the open string passed to the TPM to open the database. The open string for the DB2 database takes the following form:

NOTE >> Consult your DB2 and TPM documentation for complete and up-to-date information.

The parameters for the DB2 open string include:

• Database Alias: This parameter is the DB2 database alias name which is used to open a connection to the database. This is a required parameter.

Note that the value of this parameter is the same value that you provide in the argument XA=xaParameter when defining the propertyString parameter in RWDBManager::database(). See “RWDBDatabase Objects” .

• userName: The user name or user ID used while opening a connection to the database.

In addition to the above parameters, other parameters like TPM, AXLIB, CHAIN_END, SUSPEND_CURSOR, and HOLD_CURSOR can also be provided in the open string. For the explanation of these parameters, please refer to section, “Setting Up a Database as a Resource Manager,” in the Administration Guide for DB2 UDB, provided by DB2.

The XA interface describes a structure called the switch table, which lists the names of the xa_ routines implemented in the resource manager. This structure is called xa_switch_t, and is defined in the xa.h header file. The switch table helps build servers that are truly independent of the database vendor being used.

In order to be integrated in the X/Open environment, each resource manager must define the name of its XA switch table. The DB2 UDB specific xa_switch_t table is accessible through the variable db2xa_switch. You can use the following DB XA method to access the switch table in a database-independent manner:

static void* RWDBManager::xaSwitch(const RWCString& accessLib)

• For static libraries, you must supply the string "DB2CLI" to the xaSwitch() function.

• For shared libraries, you must supply the name of the access library, using the same name as the non-XA library.

Note that the method RWDBManager::xaSwitch(const RWCString&) returns a void*. This return value must be cast to a struct xa_switch_t pointer.

The DB XA Module does not open connections to a database server. Instead, it makes use of connections previously opened by the transaction processing monitor (TPM).

In order for the DB XA Module to interact with a resource manager and establish connectivity, you must create an instance of RWDBDatabase by calling:

RWDBDatabase RWDBManager::database("accessLib", "", "", "", "", "XA=dbAlias");

All arguments are of type RWCString. Note that establishing an XA connection to the DB2 UDB requires only two of the six database() arguments, as described here:

The argument for the first parameter is the same as that which you provide for the non-XA connection.

For shared libraries, supply the name of your shared access library, for example "libdb2<ver>12d.so".

propertyString or "XA=dbAlias"

This last parameter provides the database alias name, passed as the value of the key XA. This database alias name should be the same as that provided in open string while registering with the TPM. For more information, see “Configuring the Resource Manager” .

The DB XA Module does not differ from the DB Interface Module in its approach to using RWDBSystemHandle. For information about the DB2 CLI-specific implementations of this class, see the DB2 CLI Access Module User’s Guide.

NOTE >> RWDBSystemHandle gives you access to vendor library-specific structures.There are complications associated with making direct DB2 CLI calls. We recommend that you always consult your DB2 CLI manual, since there are many calls that are restricted in an XA environment.

The DB XA Module returns an environment handle of type RWDBDB2CLILibXAEnvironmentHandle. This handle derives from RWDBDB2CLILibEnvironmentHandle and redefines the behavior of the following methods:

You should not set maximum number of connections in XA connectivity. This function produces a notSupported error.

You should not change the connection type in XA connectivity. The connection type should always be SQL_COORDINATED_TRANS. This function produces a notSupported error.

In XA connectivity, the value can be either SQL_ONEPHASE or SQL_TWOPHASE. The DB XA Module uses SQL_TWOPHASE as the default value. Trying to set a value other than these two values will result in a notSupported error.