The DB XA Module implementation of RWDBDatabase manages connections with database servers, just like its counterpart in the DB Interface Module. In the XA environment it is not necessary to login, so the database class represents only accessLib and xaParameter to fetch the respective database connection. It does not represent any user information. The database class still provides the interface for tables, queries, and direct SQL transactions. You simply obtain XA-specific instances of RWDBDatabase from the database() function in RWDBManager, by passing an XA key (xaParameter) through the propertyString parameter.
Class RWDBConnection encapsulates a database connection. In a non-XA SourcePro DB application, connections to a database are opened as needed. In an XA environment, connections are opened and managed by the transaction processing monitor, based on criteria defined during the set up phase of the resource manager. An RWDBConnection does not open and close connections with the database. Instead, it attempts to get a valid handle to a database connection previously opened by the TPM, using the xaParameter supplied. Once acquired, it holds this handle, and uses it whenever it is needed.
Obtaining an instance of a connection in the DB XA Module is identical to obtaining a connection in the non-XA version of the DB Interface Module. For example, the following call to RWDBManager returns an RWDBDatabase object, which, in turn, creates an instance of RWDBConnection:
RWDBDatabase dbase=RWDBManager::database("accessLib", "", "", "",
"", "XA=xaParameter");
RWDBConnection conn=dbase.connection();
|
The same rules that apply to default connections in a non-XA environment apply in the XA environment. (See "Databases and Connections" in the DB Interface Module DB User's Guide.)
In an XA environment it is very important to be careful with connections. SourcePro DB provides a mechanism to implicitly create connections whenever a specific operation must access the server without using an explicit connection. This mechanism can lead to a proliferation of connections to the database server. If the client and server do not care about the number of open connections, then proliferation of connections is not a problem.
The DB XA Module, however, does not create its own connections to the database server, but rather obtains them through a third-party TPM. This means that the number of connection objects is limited by the number of connections that the TPM will make available. For example:
Oracle provides only one connection handle per db_name provided in the openString sent to the resource manager. For XA-specific information about the Oracle OCI Access Module, see Section 5.2.
For Sybase, the maximum number of connections open per LRM name depends on the setting for the CS_MAX_CONNECT property. This property is set in the [all] section of the XA configuration file. For XA-specific information about the Sybase Access Module, see Section 5.3.
DB2 CLI provides one connection per database alias name, which is provided in the openString sent to the resource manager. For XA-specific information about the DB2 CLI Access Module, see Section 5.4.
The DB XA Module limits the number of valid connections available per RWDBDatabase object to one, except with Sybase. Any attempt to use more than one connection will result in a notSupported error. It is possible to use implicit connections, but the number of connections available at the same time through a particular RWDBDatabase is limited to one.
We recommend that you always use explicit connections.
Because the TPM actually opens and closes connections, the following RWDBConnection member functions should not be called when using the DB XA Module:
RWDBConnection::open()
RWDBConnection::close()
Using open() and close() functions in the XA environment will produce a notSupported error.
In an XA environment, transactions are controlled by the TPM. This means that the DB XA Module must omit calls that affect the state of global transactions. Therefore, the following methods should not be called:
beginTransaction()
commitTransaction()
rollbackTransaction()
autocommit()
Using these functions produces a notSupported error.
We highly discourage the use of any SourcePro DB API that results in the generation of DDL statements (for example, using methods that create, drop, or alter a table, view, procedure, index, et cetera; or granting and revoking privileges). Since DDL statements commit implicitly, they change the transaction state of the database. The database may produce a server error upon the execution of such code. Refer to the DB XA Module Reference Guide for descriptions of which methods should not be used.
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.