Chapter 4 Database Access

Configuring XA resources

You must configure XA resources to access a specific database. XA resources differ from connection caches in that XA resources are XA-Library interfaces that maintain their own connection pool separate from the connection cache connection pool. You can use XA resources only when EAServer is running in either OTS/XA or JTS/JTA transaction mode.

If a get connection call (such as the Java getConnection or the C JagCmGetConnection method call) is in a transaction, the XA resource is automatically used to return a connection. If a get connection call is not in a transaction, the connection cache is automatically used. If the transactional behavior for a component uses the Supported option, then EAServer determines at runtime whether the component executes its get connection calls in a transaction; if it does, you must configure both a connection cache and a corresponding XA resource for a database.

By default, EAServer uses the XA libraries listed in Table 4-4 to obtain an XA resource that is exported from the database connection libraries.

Table 4-4: XA resource libraries and property files
Connection library	XA library for Solaris	XA library for Windows	Connection library for Solaris	Connection library for Windows	Database property file
Sybase Client Library 11.0	libjxa.so	libjxa.dll	libjct_r.so	libjct.dll	CTLIB_110.props
Oracle OCI 7.x	libclntsh.so	xa73.dll	libclntsh.so	ociw32.dll	OCI_7.props
Oracle OCI 8.x	libclntsh.so	oraclient8.dll	libclntsh.so	oci.dll	OCI_8.props
Oracle OCI 9.x	libclntsh.so	oraclient9.dll	libclntsh.so	oci.dll	OCI_9.props

In most cases, you should not need to modify the resource manager properties. However, to use a shared library or DLL other than the default, you do need to edit the database property file. For example, for XA resource connections using Oracle OCI 8.x, where 8.x is 8.1.5 or lower, set this property value in the Repository/ResourceManager/OCI_8.props file:

com.sybase.jaguar.resourcemanager.xalib = xa80.dll

To use a shared library or DLL other than the default for a single connection cache, edit the connection cache properties file, <cache_name>.props, located in EAServer's Repository/ConnCache directory, and specify the shared library or DLL name:

com.sybase.jaguar.conncache.xadllname = library_name

If you are running EAServer 3.6.1 To run EAServer 3.6.1, use the All Properties tab to add the com.sybase.jaguar.conncache.xadllname property. For UNIX, set it to "libjxa.so"; for Windows, set it to "libjxa.dll".

If you execute a transaction without an XA resource configured for a database, the EAServer connection manager returns CS_FAIL.

If a configured XA resource is not running or cannot be connected to, EAServer cannot initialize. To solve this problem, perform one of these tasks:

Start the XA resource.
Make the XA resource available to EAServer.
Start the JagRepair server and delete the XA resource. See "Using the JagRepair server" for information about JagRepair.

Creating new XA resources

Right-click the Connection Caches folder.
Select New XA Resource.
Enter the XA Resource name.

In the XA resource properties dialog, configure the properties described in Table 4-5.

Table 4-5: XA resource properties
Tab	Property	Description
General	Description	A brief phrase describing the purpose of the XA resource.
	Database Type	Select the database type from the list.
	Server Name	Name of the XA resource server. For JDBC, enter: `NetworkProtocol=Tds:Server=yourServer:Port=TdsPort#` where: yourServer is the server that the driver is installed on. TdsPort# is the port number where TDS calls are received.
	User Name	A name you can use to access the server. To use XA transactions, set to something other than "sa".
	Password	The password for the user.
Driver (Connection Library)	DLL or Class Name	The file name of the XA resource library. For JDBC, enter `com.sybase.jdbc2.jdbc.SybXADataSource` For Client Library 11.0, enter: On UNIX - `libjct_r.so` On Windows - `libjct.dll` For OCI 7.x, enter `ociw32.dll` For OCI 8.x, enter `oci.dll` For OCI 9.x, enter `oci.dll`
	JDBC	A Java Database Connectivity driver such as Sybase jConnect.
	Client Library 11.0	Connections made via Sybase Open Client Client-Library version 11.1 (included with EAServer). Client-Library is the proprietary, native C/C++ interface to Sybase databases and database gateways.
	OCI 7.x	Oracle Call Interface (OCI) version 7.x. OCI is the proprietary, native driver for C/C++ access to Oracle databases.
	OCI 8.x	OCI version 8.x or later.
	OCI 9.x	OCI version 9.x or later.
XA (Properties)	Database Name	If you selected OCI 7.x, 8.x, or 9.x, specify the database name.
	Default Open String	The string used to connect to the XA resource. You cannot modify this string, which is automatically built from the information that you entered in the previous tabs.
	Open String Suffix	In this optional field, you can specify any valid open string options. For example, for a Sybase Client-Library 11.0 XA resource, you can enter: -L logfile where logfile is where you want to store log information. If the Open String Suffix is set incorrectly, EAServer does not initialize.
	Close String	In this optional field, you can specify a value used by the resource to close a connection.

See your XA resource documentation for more information about the Open String Suffix and Close String syntax.

Click Refresh.

Viewing or modifying an XA resource

Expand the Connection Caches folder.
Highlight the XA resource you want to modify.
From the File menu, select one of:
- XA Resource Properties - view or modify this XA resource's properties. See Table 4-5.
- Delete XA Resource - delete the XA resource from the system.

You must refresh XA resources before any changes to XA resource properties take effect.

Using XA resources with Adaptive Server Enterprise

To use XA resources with an Adaptive Server Enterprise 12.0 or later database running on UNIX or Windows, perform these tasks:

(Windows only.) Verify that you have the correct license file, which is located in %SYBASE%\SYSAM-1_0\licenses\license.dat. To run XA transactions, you must have the ASE_DTM license.
Configure the database to use XA transactions. For more information, see Using the Adaptive Server Distributed Transaction Management Features, available on the Sybase Product Manuals Web page .
Create a database to use for XA transactions.
Configure the database tables and stored procedures required for JDBC connection caches, which are available in $JAGUAR/html/classes/sp/sql_server12.sql.
Configure the database tables required for C/C++ connection caches. You can install these tables by running xa_load.sh (UNIX) or xa_load.bat (Windows), which is located in EAServer's html/classes/sp directory.
Create a login, other than sa, for connecting to the database. You cannot use the sa login to connect to Adaptive Server Enterprise databases for XA transactions.

Modifying the Adaptive Server configuration files

When you configure an XA resource for C/C++ connection caches, you need to modify two configuration files.

On UNIX:

$JAGUAR/interfaces
$JAGUAR/xa_config

On Windows:

%JAGUAR%\ini\sql.ini
%JAGUAR%\ini\xa_config

interfaces and sql.ini

On UNIX, add these lines to the interfaces file:

DbServer
   master tcp ether host 5300
   query tcp ether host 5300

On Windows, add these lines to the sql.ini file:

[DbServer]
master=NLWNSCK,host,5200
query=NLWNSCK,host,5200

Where DbServer is the name of the database server and host is the name of the machine on which the database server runs. DbServer should have the same value that you entered in the Server Name field when you configured the XA resource.

xa_config

For both operating systems, add these lines to the xa_config file:

[xa]
   lrm=serverName
   server=DbServer

Where:

serverName is the name you entered in the Server Name field when you configured the XA resource.
DbServer is the name of the server you entered in either the interfaces file or the sql.ini file.

serverName and DbServer represent the same server and should have the same value.