This section describes how to use the Oracle OCI Access Module with XA functionality. This chapter assumes that you have followed the instructions for installing and building the DB XA Module with Oracle OCI (9i and 10g). 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 propertyString parameter with key XA=xaParameter. This section explains how you obtain the value of the xaParameter argument that is specific to Oracle OCI.
The value of the xaParameter argument must be the same as that used for the DB parameter in the open string passed to the TPM to open the database. For example, the open string for the Oracle databases takes the following form:
Oracle_XA(+required_fields) [+optional_fields] |
For complete and accurate connection information, consult the documentation for your database and TPM.
As of this printing, required_fields are:
User and password: Acc=P/user/password
Session time limit: SesTm=session_time_limit
The optional_fields includes:
Database name: DB=db_name
Note that the value of this DB parameter is the same value that you provide in the argument XA=xaParameter when defining the propertyString parameter in RWDBManager::database(). See Section 5.2.3.1.
The XA interface describes a structure called a 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. For Oracle 9i, and Oracle 10g, the database-specific xa_switch_t table for static registration is xaosw. The DB XA Module does not support dynamic registration, as provided by the Oracle switch structure xaoswd. You can use the following method to access the xaosw switch table in a database-independent manner:
static void* RWDBManager::xaSwitch(const RWCString& accessLib) |
For static libraries, you must supply the database-specific string to the xaSwitch() method. Note that the value of the accessLib parameter is the same here as it is in the RWDBManager::database() method. For example:
(struct xa_switch_t *)RWDBManager::xaSwitch("ORACLE_OCI");
|
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("liboci4315d.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 TPM. Therefore, the DB XA Module does not make use of Oracle OCI calls such as OCIServerAttach(), OCISessionBegin() and OCISessionEnd(), since those calls explicitly establish connections to database servers.
To obtain a valid environment handle and service context handle, the DB XA Module uses function calls xaoEnv() and xaoSvcCtx(), respectively, for a connection previously opened by the TPM. The signatures for these routines are:
OCIEnv *xaoEnv(text *dbname) OCISvcCtx *xaoSvcCtx(text *dbname) |
The dbname parameter has the same value as the xaParameter argument that you pass in as the propertyString parameter for RWDBManager::database(). That is, function xaoEnv returns the environment handle, already allocated by the TPM, that corresponds to the dbName parameter. Likewise, function xaoSvcCtx returns the service context handle, already allocated by the TPM, that corresponds to the dbName parameter. If dbname is a null pointer, these functions respectively return environment and service context handles for the default connection.
In order for the DB XA Module to interact with a resource manager and establish connectivity to a database, you must create an instance of RWDBDatabase by calling:
RWDBManager::database("accessLib", "", "", "", "",
"XA=xaParameter");
|
All arguments are of type RWCString. Note that establishing an XA connection to the Oracle OCI 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 "ORACLE_OCI".
For shared libraries: supply the name of your shared access library, for example, "liboci4215d.so".
propertyString or "XA=xaParameter"
The argument for the sixth and last parameter, propertyString, provides the database name, passed as XA=xaParameter. Oracle OCI identifies each XA application by its database name. This database name should be the same as the value of the DB parameter, which you provided in the open string while registering with the TPM (see Section 5.2.1).
The DB XA Module does not differ from the DB Interface Module in its approach to using RWDBSystemHandle and RWDBEnvironmentHandle with Oracle OCI Access Module. For information about the database-specific implementations of these classes, see the Oracle OCI Access Module User's Guide.
There are complications associated with making direct OCI calls. We recommend that you always consult your OCI manual, since there are many calls that are restricted in an XA environment.
Copyright © Rogue Wave Software, Inc. All Rights Reserved.
The Rogue Wave name and logo, and SourcePro, are registered trademarks of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.