This section describes how to use the Sybase Access Module with XA functionality. This chapter assumes that you have followed the instructions for installing and building the DB XA Module with Sybase. 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 Sybase-specific value of the xaParameter argument.

When you run on Sybase, the value of the xaParameter argument must be the same as that used for the lrm_name parameter, which indicates the logical resource manager (LRM) name that the TPM uses to open the database. The open string for the Sybase database takes the following form:

The required parameters include:

For more information on the open string parameters, both required and optional, please refer to the XA Interface Integration Guide for CICS, Encina and Tuxedo.

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. Sybase provides two XA switches:

In spite of the nominal implication that the TUX and TXS switch structures are TPM-specific, the use of these switches is not dependent on the use of Tuxedo or TXS TPMs. Rather, as described above, their use is dependent on whether the application is single-threaded or multithreaded.

You can use the following DB XA method to access the switch table in a database-independent manner:

If you have built the DB XA Module using a single-threaded build type, xaSwitch() returns sybase_TUX_xa_switch. If you are using a multithreaded build, this method returns sybase_TXS_xa_switch.

For static libraries, you must supply "SYBASE_CT" to the xaSwitch() method.

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

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. When the TPM opens a connection to the Sybase SQL Server database, a CS_CONNECTION structure gets allocated. Therefore, the DB XA Module does not use Sybase Open Client Client-Library calls like the following, because these calls explicitly establish connections to database servers:

The connection handle is obtained using the logical resource manager (LRM) name provided during the configuration of the resource manager. The DB XA Module uses a global CS_CONTEXT for all database calls. It fetches the CS_CONNECTION object that was allocated by the TPM using the lrm_name and the thread information, in case the build is multithreaded. For more information about the LRM, see the XA Interface Integration Guide for CICS, Encina and Tuxedo.

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

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

When using the DB XA Module, RWDBConnection objects are created in the same manner as those in the non-XA environment. Given an RWDBDatabase object:

The same rules that apply to default connections in a non-XA environment apply in the XA environment. (See the “Databases and Connections” section of the DB Interface Module User’s Guide.)

The DB XA Module does not pose any restrictions on the number of connections opened on a single lrm_name. The restriction is placed by the CS_MAX_CONNECT property in the [all] section of the XA configuration file.

Because the retrieval of CS_CONNECTION objects is dependent on the current thread information, connection pooling is turned off when using the DB XA Module with the Sybase Access Module.

Using method RWDBDatabase:: defaultConnections(size_t size) to set default connections in a connection pool will result in a notSupported error.

The DB XA Module is similar to the DB Interface Module in its approach to the Sybase XA implementation of RWDBSystemHandle. RWDBSystemHandle, however, gives you access to vendor library-specific structures. Therefore, when you’re working in the XA environment, you must consult the Sybase XA documentation, available from Sybase, for restrictions applying to certain calls.

The XA-component of the Sybase Access Module returns an environment handle of type RWDBSybCTXAEnvironmentHandle. This handle derives from RWDBSybCTLibEnvironmnentHandle and redefines the behavior of the following methods: