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

Technical Reference for the Easysoft JDBC-ODBC Bridge

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

Appendix Guide

ODBC Conformance

The Easysoft JDBC-ODBC Bridge is an ODBC 3.5 driver and uses the driver manager to provide the deprecated and old ODBC 2 functions:

SQLDescribeParam (not supported by default but see Describe Parameters)

Cursor support in the Easysoft JDBC-ODBC Bridge is restricted to FORWARD_ONLY and STATIC.

Scalar Functions

The Easysoft JDBC-ODBC Bridge supports the following scalar functions:

Functions need to be called by using the ODBC escape sequence {fn scalar-function}. For example:

SELECT {fn UCASE(Name)} FROM Customers


The Easysoft JDBC-ODBC Bridge will allow access to Oracle databases on version 8.1.7 and upwards.

Supported Data Types

The following Oracle data types are supported by the Easysoft JDBC-ODBC Bridge:

Advanced Security

The Oracle Advanced Security option is an Oracle client or server add-on that combines network encryption, database encryption and strong authentication to protect sensitive data stored in Oracle databases. The Advanced Security option:

Oracle Advanced Security requires Net8 or Oracle Net to transmit data securely. The Easysoft JDBC-ODBC Bridge uses the Oracle client, which uses these protocols to communicate with the Oracle database server over the network. Applications that access Oracle by using the Easysoft JDBC-ODBC Bridge can therefore take advantage of the Oracle Advanced Security option.

For information about configuring the Oracle client and server for use with the Oracle Advanced Security option, see the Oracle Advanced Security Administrator's Guide. No additional Easysoft JDBC-ODBC Bridge configuration is necessary.

Oracle Real Application Clusters (RAC)

Real Application Clusters (RAC) is an Oracle High Availability feature that enables an Oracle Database Server Grid by providing a single database that spans multiple low-cost servers yet appears to the application as a single, unified database system. RAC combines the processing power of these multiple interconnected computers to provide system redundancy, scalability, and high availability. Application scale in a RAC environment to meet increasing data processing demands without changing the application code.

To increase the performance of a RAC database, you can add cluster nodes. Each additional node can help speed up application processing.

If a clustered server fails, the Oracle database will continue running on the surviving servers. If more processing power is needed, another server can be added without interrupting user's access to data.

The Easysoft JDBC-ODBC Bridge will allow access to Oracle RAC environments. The Oracle client must be configured correctly to take full advantage of the RAC features. Please consult you Oracle documentation for more details.

Transparent Application Failover (TAF)

Transparent Application Failover (TAF) is a mechanism that automatically reconnects client applications to a node of a RAC database cluster following a connection failure. If a failure occurs, the Oracle client intercepts the resultant error message and starts the transparent failover process. The Oracle client requests another connection from the Oracle listener, which then connects the client to a surviving node of the RAC database cluster.

There may be a delay associated with failing over to another node. To keep users informed, it is possible for an OCI application to register a callback function that is invoked in the event of a connection loss and during the course of the failover. The callback function enables the OCI application to advise users that a failover is in progress and to wait while the failover completes. This ensures users do not attempt to restart their applications, because they perceive this delay as a application failure.

The Easysoft JDBC-ODBC Bridge enables ODBC applications to register a failover callback function. To do this, the ODBC application must:

1.  Define a callback function that takes the form:

 int TAF_callback_fn( SQLHANDLE connection,

  int type,

  int event );


 The function can trigger a new failover attempt by returning OCI_FO_RETRY.

 All the OCI_* constants listed here are defined in the OCI header file oci.h. Consult the Oracle Call Interface Programmer's Guide for the meanings of these constants.

2.  Register and establish a context for the callback function by calling SQLSetConnectAttr with the attributes SQL_ATTR_REGISTER_TAF_HANDLE and SQL_ATTR_REGISTER_TAF_CALLBACK.

 The definitions for these attributes are:



The value SQL_ATTR_REGISTER_TAF_CALLBACK is a pointer to the callback function. The value for SQL_ATTR_REGISTER_TAF_HANDLE is a pointer to the connection handle used to establish a context for the callback function. For example:









Version 1.39 of the Perl DBD::ODBC module (which in conjunction with Perl DBI provides an interface to ODBC databases for Perl) has been used to test the Easysoft JDBC-ODBC Bridge's TAF support. An example Perl script is provided that shows how to use the failover types and events to:

The example Perl script is available at:


Database Resident Connection Pooling (DRCP)

Database Resident Connection Pooling (DRCP) is a scalability feature introduced in Oracle 11g Release 1, which uses a combination of dedicated server and connection broker to handle short, transient sessions coming from Web applications.

DRCP is especially relevant for architectures with multi-process, single-threaded application servers, such as PHP and Apache, that cannot do middle tier connection pooling.

The OCI client libraries enable applications to configure the behaviour of DRCP. Applications can:

For example, applications in an HR suite may be willing to share pooled servers among themselves but not among other applications.

Because the Easysoft JDBC-ODBC Bridge uses Oracle client software, it makes it possible for ODBC applications and interfaces to configure behaviour normally controlled from within the OCI layer. For example, the Easysoft JDBC-ODBC Bridge enables PHP applications using the Unified ODBC interface to configure the DRCP pool purity or specify a connection class.

To configure the DRCP pool purity or specify a connection class from an ODBC application, set the Pool_Purity or Pool_Connection_Class attributes. For more information on these attributes see Attribute Fields. (Note that to set these attributes, you need to be using version 11.1+ of the Oracle client software.)


A connection pool is a cache of database connection objects. The objects represent physical database connections that can be used by an application to connect to a database.

Connection pools promote the reuse of connection objects and reduce the number of times that connection objects are created. Connection pools significantly improve performance for database intensive applications because creating connection objects is costly both in terms of time and resources.

The connection pool is normally configured with a shared pool of physical connections, translating to a back-end server pool containing an identical number of dedicated server processes.

Applications that can use connection pooling include middle tier applications for Web application servers and e-mail servers. (Web applications introduced the three-tier model in which the browser is the client tier, the database is the backend tier, and the web server and its extensions are the middle tier.)

Connection pooling is beneficial only if the middle tier itself is multithreaded, because it takes advantage of the ability of multiple threads in one application process to share resources. (Threads are lightweight processes that exist within a larger process.)

DRCP is an alternative connection pooling mechanism that enables multi-process applications to share connections to the database. (In multi-process applications, unlike in multi-threaded applications, processes are insulated from each other.)

Network Protocols

The Easysoft JDBC-ODBC Bridge supports both IPC and TCP/IP network protocols.

Materialized Views

The Easysoft JDBC-ODBC Bridge supports materialized views. A materialized view is a database object that contains the results of a query. Materialized views stored in the same database as their base tables can improve query performance through query rewrites.

The query rewrite mechanism reduces response time for returning results from the query. It does this by automatically rewriting the SQL query to use the materialized view instead of accessing the original tables. Query rewrites are particularly useful in a data warehouse environment.

For more information about materialized views, see your Oracle documentation.

XA Support

The Easysoft JDBC-ODBC Bridge can be configured to take part in a distributed XA transaction. To do this, add a data source that contains entries that correspond with the xa_open string used by the XA Transaction Manager to connect to the Oracle database server.

For example, the following sample xa_open string opens an XA connection to an Oracle database named "payroll." It also specifies the Net8 link and the username and password used to log onto the Oracle server.


To make this XA connection available for use by the Easysoft JDBC-ODBC Bridge, the data source used to access Oracle needs to contain the following corresponding entries.


Driver = ORACLE

Database = ninetwo.oracle

User = system

Password = manager

XA_Enlist = 1

XA_Connection_String = payroll

In addition, the XA_Enlist attribute must be set to 1. When this setting is present, the Easysoft JDBC-ODBC Bridge accesses Oracle by using the Oracle XA library. Note that the data source can then only be used to access an Oracle 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 without the XA_Enlist attribute.

The XA_Connection_String attribute is only 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.

A tutorial that provides more information about using the Easysoft JDBC-ODBC Bridge in the context of an XA transaction is available from the Easysoft JDBC-ODBC Bridge section of the Easysoft web site. The tutorial includes a code sample that shows the point at which an ODBC connection needs to be created and closed to participate in a distributed transaction.

Application Specific Issues

StarOffice 5.2

If problems occur with metadata, the METADATA_ID parameter needs to be set to 1 in the odbc.ini file.

OpenOffice.org 1.0

For OpenOffice.org 1.0, you need to check the No Metadata Schema check box in the dialogue or set METADATA_DONT_DO_SCHEMA to 1 in your odbc.ini file. This is not necessary for OpenOffice.org 2.0.


PHP4 calls the SQLDescribeParams ODBC function when processing SQL statements that have parameters.

The Easysoft JDBC-ODBC Bridge correctly reports that it does not support the SQLDescribeParams function, but PHP4 ignores this and continues with undefined results. See Describe Parameters.

Perl DBI

If attempting to fetch LONG data, set the DBI_LONG_SIZE to an appropriate value. See DBI Long Size.


The Easysoft JDBC-ODBC Bridge is thread safe in accordance with the ODBC 3.5 specification and can be used behind threaded applications with confidence. Usually applications use one connection handle and multiple threads executing SQL statements on that connection.


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



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.

From within the Easysoft JDBC-ODBC Bridge

Tracing in the Easysoft JDBC-ODBC Bridge is platform-specific:

Update the Registry by running regedit and edit the key:


where DSN-NAME is the name of the Easysoft JDBC-ODBC Bridge data source.

Add a LOG string value and set it to the path and file name of the log file (e.g. \temp\oracle.log).

Add a LOG attribute to the DSN section of the odbc.ini file.






LOG = /tmp/oracle.log

The LOG value is the path and file name of the log file (e.g. /tmp/oracle.log).