Using the DB XA Module with the Informix Access Module provides XA functionality through the ODBC API.
NOTE -- Only Informix SDK 2.70 and above provide XA functionality through the ODBC API.
This section describes how to use the Informix Access Module with XA functionality. This chapter assumes that you have followed the instructions for installing and building the DB XA Module with Informix. These instructions are located in Appendix A, "Installing and Building the DB XA Module," of the manual Installing and Building Your SourcePro C++ Products.
As explained in Chapter 4, XA connections to your database are established by using the database() function in RWDBManager, and providing its connectString parameter with key XA=xaParameter. This section explains how you obtain the Informix-specific value of the xaParameter argument.
When you run on Informix, the value of the xaParameter argument must be the same as that used for the Application Number parameter in the open string passed to the TPM to open the database. The open string for the Informix database takes the following form:
ApplicationNumber|(DSNName or Informix_connect_string)
NOTE -- Consult your Informix and TPM documentation for complete and up-to-date information.
The parameters for the Informix open string include:
ApplicationNumber: This parameter uniquely identifies each XA application.
Note that the value of this parameter is the same value that you provide in the argument XA=xaParameter when defining the connectString parameter in RWDBManager::database(). See Section 5.4.3.1.
DSNName or Informix_connect_string: You can either specify the ODBC DSN name here, if you have a ODBC DSN setup, or you can directly use the Informix connectString to connect to the database.
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 Informix ODBC-specific xa_switch_t table is accessible through the variable _Odbc_xa_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 "INFORMIX" to the xaSwitch() function.
(struct xa_switch_t*)RWDBManager::xaSwitch("INFORMIX"),
For shared libraries, you must supply the name of the access library, using the same name as the non-XA library. For example:
(struct xa_switch_t *)RWDBManager::xaSwitch("libinf424d.so");
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). Therefore, the DB XA Module does not make use of any Informix calls that explicitly establish connections to database servers.
The DB XA Module uses following API provided by Informix:
_fninfx_xa_switch()
struct xa_switch_t * _fninfx_xa_switch( void );
This function returns the XA switch table variable (_Odbc_xa_switch), which is used by the TPM.
IFMX_SQLGetXaHenv ()
RETCODE IFMX_SQLGetXaHenv(int applNo, HENV * henv);
This function returns the environment handle allocated by the TPM that corresponds to the application number.
IFMX_SQLGetXaHdbc()
RETCODE IFMX_SQLGetXaHdbc(int applNo, HDBC * hdbc);
This function returns the handle to the database connection that was established by the TPM corresponding to the application number.
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=applNo");
All arguments are of type RWCString. Note that establishing an XA connection to the Informix database requires only two of the six database() arguments, as described here:
accessLib
The argument for the first parameter is the same as that which you provide for the non-XA connection.
For static libraries, supply the string "INFORMIX".
For shared libraries, supply the name of your shared access library, for example "libinf424d.so".
connectString or "XA=applNo"
This last parameter provides the application number, passed as the value of the key XA. Informix identifies each XA application by its application number. This application number should be the same as that provided in open string while registering with the TPM. For more information, see Section 5.4.1.
The DB XA Module does not differ from the DB Interface Module in its approach to using RWDBSystemHandle and RWDBEnvironmentHandle with the Informix Access Module. See the Informix Access Module User's Guide for information about the Informix-specific implementations of these classes.
©2005 Copyright Quovadx, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Quovadx, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.