Easysoft ODBC-JDBC Gateway User's Guide - Technical Reference

Technical Reference for the Easysoft ODBC-JDBC Gateway

This section contains extra information relating to the deployment of the Easysoft ODBC-JDBC Gateway.

Appendix Guide

Threading

The Easysoft ODBC-JDBC Gateway as an ODBC driver is supposed to be thread safe, as it is a requirement of ODBC 3 drivers.

No threading issues were found using the Easysoft ODBC-JDBC Gateway in WinSQL or Microsoft Access, both of which are multithreaded applications.

However, when tested last there appeared to be some threading issues when the Easysoft ODBC-JDBC Gateway runs behind the Easysoft ODBC-ODBC Bridge server.

This requires investigation and eventual resolution.

Supported API Calls

All ODBC 3.5 calls are supported except for the following:

The parameter based calls are not supported because support for them is not provided in JDBC 2. When JDBC 3 drivers become more common targets for the Easysoft ODBC-JDBC Gateway, support for these functions will be added.

Unicode ODBC Calls

If available, the Easysoft ODBC-JDBC Gateway supports the Unicode version (with suffix "W") of the ODBC calls it implements. The Easysoft ODBC-JDBC Gateway supports:

XA Support

The Easysoft ODBC-JDBC Gateway can provide access to XA resources in the context of a distributed transaction.

To access an XA resource, add a data source that connects to the JDBC driver for the resource by using the XA interface.


NB

To be involved in a distributed transaction, the target JDBC driver must implement the XA features of the JDBC 2.0 Optional Package.


In the data source, set the XA_Enlist data source option to 1. Use XAClass to specify the JDBC driver's XADataSource class. The class that the JDBC driver implements XADataSource with is used to produce XA connections. Use XIDClass to specify the method the JDBC driver provides to create Xids. The Transaction Manager uses Xids to identify each transaction in a distributed transaction. The XA_Connection_String attribute is required if the DB field is present in the xa_open string. The XA_Connection_String attribute value must be the same as that of the DB field.

This example data source sets up an XA connection to the Oracle JDBC driver:

[XA-OJG]

Driver = Easysoft ODBC-JDBC Gateway

DriverClass = oracle.jdbc.OracleDriver

User = system

Password = manager

ClassPath = /usr/local/oracle/jdbc/lib/ojdbc14.jar

URL = jdbc:oracle:oci8:@//my_host:1521/my_servicename

XA_Enlist = 1

XA_Connection_String = my_database

XAClass = oracle.jdbc.xa.client.OracleXADataSource

XIDClass = oracle.jdbc.xa.OracleXid

Note that if the XA attributes are present, the data source can only be used to access the target database as an XA resource under the control of a Transaction Manager. If you need to access the same database with a non-XA connection, configure a separate data source that does not contain the XA attributes.

The xa_open String

The Transaction Manager uses the xa_open string to connect to the Resource Manager.

The format for the Easysoft ODBC-JDBC Gateway xa_open string is:

ODBCJDBC_XA+DSN=data_source+LogFile=log_file+DB=db_name

ODBCJDBC_XA is the Easysoft ODBC-JDBC Gateway Resource Manager name. Use the DSN field to specify the Easysoft ODBC-JDBC Gateway data source that you configured for the resource. To enable logging, include the optional LogFile field. You need to use this field rather than the standard tracing mechanisms (see Tracing) to enable logging for an XA connection. The DB field is used to allow the ODBC connection to find the matching XA connection.

This WebSphere MQ example shows the corresponding xa_open string to use for the XA-OJG data source:

XAOpenString=ODBCJDBC_XA+DSN=XA-OJG+LogFile=/tmp/sql.log+DB=my_database

The xa_switch_t Structure

The Easysoft ODBC-JDBC Gateway xa_switch_t structure name is ojg_xaosw. This structure contains the entry points for the Easysoft ODBC-JDBC Gateway Resource Manager. Applications requiring XA support should be built to use this structure. The Easysoft ODBC-JDBC Gateway will translate calls into the entry points into the corresponding Java javax.sql.XADataSource methods.

Tracing

The ODBC calls an application makes can be traced:

Within the driver manager by an application

An application can turn tracing on in the driver manager via the ODBC API SQLSetConnectAttr (...,SQL_ATTR_TRACE,...).

The trace filename may also be specified with the SQLSetConnectAttr attribute SQL_ATTR_TRACEFILE.

From within the driver manager

Tracing in the driver manager is platform-specific:

Start the ODBC driver manager administration interface via Start Menu > Control Panel > ODBC Data Sources.

Click on Tracing, ensure the specified filename is valid and click Start Tracing Now.

For the unixODBC driver manager, add two attributes to the [ODBC] section (create one if none exists) in odbcinst.ini.

Trace = Yes|No

TraceFile = /path/filename

e.g.

[ODBC]

Trace = Yes

TraceFile = /tmp/sql.log

Ensure that the user who is running the application to be traced has write permission to TraceFile (and to the directory containing it), or no tracing information will be produced.