WebSphere Application Server
ORACLE JDBC Drivers
Cathy Nordstrom
cjn@us.ibm.com
June 14, 2002
Oracle JDBC Drivers
Oracle comes with two types of JDBC drivers, a type 4 driver (the thin driver) and a type 2
driver (thoci driver).
Using either of these drivers, applications running in a WebSphere
Application Server can connect to Oracle databases and perform operations on the database.
Both types of drivers can be used from the same application server. The type of driver to use is
specified in the URL that is passed on the connect request.
The Oracle JDBC drivers can be used to connect with the same version of database as the driver
or earlier versions of databases, within the limits of the version of the database. For example,
Oracle JDBC Driver 9.0.1 can be used to connect to Oracle Server 9.0.1, Oracle Server 8.1.7, etc.
This document provides the basic information needed to configure Oracle so that a WAS
application can access Oracle. Currently WAS 4.0/5.0 only supports Oracle 8.1.7 and Oracle
9.0.1. Oracle 9.2 should be similar to 9.0.1 and this information should apply to the 9.2
release.
Oracle Thin JDBC Driver
The Oracle Thin JDBC Driver is a type 4 driver. It is a thin driver because all that is needed to
connect to an Oracle database is the jar or zip file with the java classes implemented by Oracle
for the JDBC driver.
For Oracle 8i, the thin driver consists of the classes12.zip and nls_charset12.zip files. If the
Oracle Server or Oracle Client is installed, then these are usually located in
$ORACLE_HOME/jdbc/lib. Otherwise, these can be obtained from any machine that has them
installed or from the Oracle Tech Net site and put in a convenient place on the machine.
For Oracle 9i, the thin driver consists of either the classes12.zip or classes12.jar file and either
the nls_charset12.zip or the nls_charset12.jar file. Either the .zip set of files or the .jar set of
files can be used. Oracle has provided a .jar set of files for use by some products that cant
use .zip files, but either can be used with WAS
To use the thin driver with WAS, the server configuration needs to have a JDBC driver
configured as a resource and then datasources need to be configured to use the JDBC driver.
To make a connection using the thin driver, a URL, a user id and a password need to be passed to
Oracle on the connect request.
The URL looks like this:
jdbc:oracle:thin:@dbmachine:1521:dbname
Where dbmachine is the name of the machine that has the Oracle database that the application
wants to connect to. 1521 is the port that the Oracle listener typically is configured to listen
at.dbname is the name of the database on the machine.
For example, if the machine is wastest1.rchland.ibm.com and the name of the database is orcl,
then the URL would be:
jdbc:oracle:thin:@wastest1.rchland.ibm.com:1521:orcl
Each release of WAS has a different way to configure the URL on the DataSource resource, see
the documentation for the specific release for how to set it up.
Oracle OCI JDBC Driver
The Oracle OCI JDBC Driver is a type 2 or thick driver. It is a thick driver because both the
class files for the OraclJDBC Driver and the Oracle Client must be installed on the machine for
programs to access the database via the OCI JDBC driver. The OCI JDBC Driver takes
advantage of the Oracle Client Interface provided by the Oracle Client. The Oracle Client
includes binaries for either native code or Java code to use. Both of these are considered to
bOCI clients.
Only the OCI JDBC client is discussed here.
In order to use the OCI JDBC Driver, first install the Oracle Client on same machine that WAS
application servers will run on. If the Oracle Server has been installed on the machine, then the
Oracle Client was probably installed as part of the Oracle Server installation. While the
following information should work, it is best to do the install following the instructions in the
Oracle Windows or Oracle UNIX installation manual. The 9.2.0.1 Oracle UNIX install
manual has a very good explanation UNIX environment variables settings and should be
consulted if there is any question about the following information.
If 8.1.7 is used, then a connection can be made using a URL similar to this:
jdbc:oracle:oci8:@netservicename
If 9.0.1 is used, then the URL should look similar to one of these:
jdbc:oracle:oci8:@netservicename
jdbc:oracle:oci:@netservicename
The netservicename is the name defined for the database connection information that is located
in the $ORACLE_HOME/network/admin/tnsnames.ora file.
For example, if the net service
name is orcl then the URL would look like:
jdbc:oracle:oci8:@orcl
Each release of WAS has a different way to configure the URL on the DataSource resource, see
the documentation for the specific release for how to set it up.
Oracle Client Installation, 64 bit versus 32 bit
Starting with Oracle 9i:
 Oracle 9i Server or Oracle 9i Client for Solaris can be installed on either 32 bit or 64
bit machines.
 Oracle 9i Server for AIX or HP can only be installed on 64 bit machines.
 Oracle 9i Client for AIX or HP can be installed on either 32 bit or 64 bit machines.
The following statements are based on testing on AIX with WAS 4.0/5.0. Oracle claims
that this should also be true for HP-UX.
 AIX Oracle 9i Server can only be installed on AIX 64 bit machine. An attempt to
install on a 32 bit AIX machine will fail.
 There is currently only a 32 bit version of the OCI driver client,
$ORACLE_HOME/lib32/libocijdbc.so
shipped with the AIX Oracle 9i Client, so only 32 bit processes can use the OCI
JDBC driver even when the AIX Oracle 9i client is installed on a 64 bit machine.
This is because there are currently only 32 bit versions of Java available.
According to Oracle, Java 1.4 will be the first version of Java that can run in a 64 bit
process and Oracle will make 64 bit versions of the OCI client available sometime
after Java 1.4 becomes available.
 The AIX Oracle 9i Client can be installed on either AIX 64 bit machines or AIX 32 bit
machines. However, when installed on an AIX 32 bit machine, some utilities
shipped with the client, such as "sqlplus" will not work because they have been
converted to 64 bit. "netmgr" does work on both 64 bit and 32 bit machines.
 While it is possible to install both 9i and 8i Oracle Clients on the same machine, it is
not possible to use both clients in the same application server because of the way
the classpath is formed. If both are installed, then the 9i Client should be used.
 The Oracle JDBC Thin Client is a pure java JDBC Driver that can be used with Java
2.0/3.0 in any 32 bit process including WAS.
 There are actually two clients available after the Oracle Client is installed, one for
use with native code and one for use with JDBC via the "Oracle OCI JDBC driver".
There is only a 32 bit version of the OCI client. There are both 32 and 64 bit
versions of the native client. The two clients are separate and should not be
confused with one another.


Configuration
1. Set up the environment variables as specified in the next section for each platform
2. Make sure the database and listener are running on the database server machine.
3. Configure tnsnames.ora file with net service name by eithe
a. Editing the file. Some editors will change this file in such a way as to make it unusable
by Oracle. Windows Notepad and UNIX vi are safe editors to use. Oracle will return
errors that may not indicate that the problem is a bad tnsnames.ora file, so care should be
taken when editing this file.
b. Copying an existing tnsnames.ora file from another machine that already has the service
names defined.
c. Use network configuration tool provided by Oracle to edit the tnsnames.ora file. This
tool allows the service name to be tested to make sure the connection will work. This
will also set up the sqlnet.ora file. If the sqlnet.ora file is missing, copy it from another
machine that has it.
i. Oracle 9.0.1 on Windows - Net Manager
ii. Oracle 8.1.7 on Windows - Net8 Assistant
iii. Oracle 9.0.1 on Unix - $ORACLE_HOME/bin/netmgr
iv. Oracle 8.1.7 on Unix - $ORACLE_HOME/bin/netasst
WINDOWS configuration
Oracle install takes care of what is needed to run the Oracle Client except for setting the
CLASSPATH. The CLASSPATH is set from the WAS configuration for the JDBC driver.
UNIX configuration
There should be a shared library called libocijdbc8.so for Oracle 8i or libocijdbc9.so for Oracle
9i. For 32 bit versions of Oracle, these should be in the $ORACLE_HOME/lib directory. For 64
bit versions of Oracle, these should be in the $ORACLE_HOME/lib32 directory.
For each platform, operating system environment variables need to be set. This is best done by
defining the variables in the profile of the user that the application server will start under.
For all UNIX platforms, the following environment variables need to be set:
 ORACLE_HOME - there is no explanation why this needs to be set, but strange
errors occur it is not set when using the OCI JDBC driver.For example, if you
installed Oracle 9i in /home/oracle/product/9.0.1 then set
ORACLE_HOME=/home/oracle/product/9.0.1

CLASSPATH - it isnt necessary to set this in the user profile because it will be set by
what is defined for theJDBC driver in the WAS server. The location of the JDBC
driver should be set to one of the following:
$ORACLE_HOME/jdbc/lib/classes12.zip:$ORACLE_HOME/jdbc/lib/nls_charset1
2.zip
$ORACLE_HOME/jdbc/lib/classes12.jar:$ORACLE_HOME/jdbc/lib/nls_charset1
2.zip
Starting with Oracle 9i, Oracle provides both a .jar and a .zip version of the

classes12 file. Oracle has reported that some vendors have problems using a .zip
version, so they provided the same implementation in .jar file. Either the .zip or .jar
files can be used with WAS.
DO NOT include in the location of the JDBC driver any other Oracle files such as the
Oracle jta.jar file. The implementations provided by WAS should not be overridden
with Oracle implementations.
Environment variables specific to the platform.
AIX
 8.1.7 Oracle Client (32 bit machine only)
LIBPATH=$ORACLE_HOME/lib
 9.0.1 Oracle Client (64 bit or 32 bit machine)
LIBPATH=$ORACLE_HOME/lib32
HP
 8.1.7 Oracle Client (32 bit machine only)
LD_LIBRARY_PATH=$ORACLE_HOME/lib
SHLIB_PATH=$ORACLE_HOME/lib
 9.0.1 Oracle Client (64 bit or 32 bit machine)
LD_LIBRARY_PATH=$ORACLE_HOME/lib32
SHLIB_PATH=$ORACLE_HOME/lib32
Solaris
 8.1.7 Oracle Client (32 bit machine only)
LD_LIBRARY_PATH= $ORACLE_HOME/lib
 9.0.1 Oracle Client (64 bit machine)
LD_LIBRARY_PATH_64=$ORACLE_HOME/lib
 9.0.1 OracleClient (64bit or 32 bit machine)
LD_LIBRARY_PATH=$ORACLE_HOME/lib32
Linux
 8.1.7 or 9.0.1 Oracle Client (Intel machine)
LD_LIBRARY_PATH=$ORACLE_HOME/lib


Oracle errors and causes
These errors where seen on AIX machines. Similar errors with similar causes should occur on
other UNIX platforms.
-----------------------------------------------------------------------------------------------------------------Error:
Exception in thread "main" java.sql.SQLException: Error while trying to retrieve text for error
ORA-12154
at oracle.jdbc.dbaccess.DBError.throwSqlException(DBError.java:169)
at oracle.jdbc.oci8.OCIDBAccess.check_error(OCIDBAccess.java:1614)
at oracle.jdbc.oci8.OCIDBAccess.logon(OCIDBAccess.java:360)
at oracle.jdbc.driver.OracleConnection.<init>(OracleConnection.java:265)
at oracle.jdbc.driver.OracleDriver.getConnectionInstance(OracleDriver.java:365)
at oracle.jdbc.driver.OracleDriver.connect(OracleDriver.java:260)
at java.sql.DriverManager.getConnection(DriverManager.java:543)
at java.sql.DriverManager.getConnection(DriverManager.java:194)
at oracle.jdbc.pool.OracleDataSource.getConnection(OracleDataSource.java:111)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPhysicalConnection
(OracleConnectionPoolDataSource.java:98)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPooledConnection
(OracleConnectionPoolDataSource.java:77)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPooledConnection
(OracleConnectionPoolDataSource.java:61)
Cause:
8i OCI driver is being used. LIBPATH is correctly set, but ORACLE_HOME is either not set
or set incorrectly.
-----------------------------------------------------------------------------------------------------------------Error:
Exception in thread "main" java.lang.UnsatisfiedLinkError: /usr/WebSphere/AppSer
ver/java/jre/bin/libocijdbc8.so: load ENOENT on shared library(s) /usr/WebSpher
e/AppServer/java/jre/bin/libocijdbc8.so libclntsh.a
at java.lang.ClassLoader$NativeLibrary.load(Native Method)
at java.lang.ClassLoader.loadLibrary0(ClassLoader.java(Compiled Code))
at java.lang.ClassLoader.loadLibrary(ClassLoader.java(Compiled Code))
at java.lang.Runtime.loadLibrary0(Runtime.java:780)
at java.lang.System.loadLibrary(System.java:865)
at oracle.jdbc.oci8.OCIDBAccess.logon(OCIDBAccess.java:233)
at oracle.jdbc.driver.OracleConnection.<init>(OracleConnection.java:265)
at oracle.jdbc.driver.OracleDriver.getConnectionInstance(OracleDriver.java:365)
at oracle.jdbc.driver.OracleDriver.connect(OracleDriver.java:260)
at java.sql.DriverManager.getConnection(DriverManager.java:543)
at java.sql.DriverManager.getConnection(DriverManager.java:194)
at oracle.jdbc.pool.OracleDataSource.getConnection(OracleDataSource.java:111)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPhysicalConnection
(OracleConnectionPoolDataSource.java:98)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPooledConnection
(OracleConnectionPoolDataSource.java:77)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPooledConnection
(OracleConnectionPoolDataSource.java:61)
Cause:
8i OCI driver is being used. LIBPATH is not set or LIBPATH is incorrectly set.
-----------------------------------------------------------------------------------------------------------------Error:
Exception in thread "main" java.lang.NullPointerException
at oracle.jdbc.oci8.OCIDBAccess.check_error(OCIDBAccess.java:1743)
at oracle.jdbc.oci8.OCIEnv.getEnvHandle(OCIEnv.java:69)
at oracle.jdbc.oci8.OCIDBAccess.logon(OCIDBAccess.java:452)
at oracle.jdbc.driver.OracleConnection.<init>(OracleConnection.java:287)
at oracle.jdbc.driver.OracleDriver.getConnectionInstance(OracleDriver.java:442)
at oracle.jdbc.driver.OracleDriver.connect(OracleDriver.java:321)
at java.sql.DriverManager.getConnection(DriverManager.java:543)
at java.sql.DriverManager.getConnection(DriverManager.java:194)
at oracle.jdbc.pool.OracleDataSource.getConnection(OracleDataSource.java:116)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPhysicalConnection
(OracleConnectionPoolDataSource.java:98)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPooledConnection
(OracleConnectionPoolDataSource.java:77)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPooledConnection
(OracleConnectionPoolDataSource.java:61)
Cause:
9i OCI driver is being used on AIX 32 bit machine. LIBPATH is set correctly, but
ORACLE_HOME is not set or is set incorrectly.
-----------------------------------------------------------------------------------------------------------------Error:
Exception in thread "main" java.lang.UnsatisfiedLinkError: no ocijdbc9 (libocij
dbc9.a or .so) in java.library.path
at java.lang.ClassLoader.loadLibrary(ClassLoader.java(Compiled Code))
at java.lang.Runtime.loadLibrary0(Runtime.java:780)
at java.lang.System.loadLibrary(System.java:865)
at oracle.jdbc.oci8.OCIDBAccess.logon(OCIDBAccess.java:294)
at oracle.jdbc.driver.OracleConnection.<init>(OracleConnection.java:287)
at oracle.jdbc.driver.OracleDriver.getConnectionInstance(OracleDriver.java:442)
at oracle.jdbc.driver.OracleDriver.connect(OracleDriver.java:321)
at java.sql.DriverManager.getConnection(DriverManager.java:543)
at java.sql.DriverManager.getConnection(DriverManager.java:194)
at oracle.jdbc.pool.OracleDataSource.getConnection(OracleDataSource.java:116)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPhysicalConnection
(OracleConnectionPoolDataSource.java:98)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPooledConnection
(OracleConnectionPoolDataSource.java:77)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPooledConnection
(OracleConnectionPoolDataSource.java:61)
Cause:
9i OCI driver is being used on AIX 32 bit or 64 bit machine. LIBPATH is not set or is set
incorrectly.
-----------------------------------------------------------------------------------------------------------------Error:
Exception in thread "main" java.sql.SQLException: internal error: oracle.jdbc.oci8.
OCIEnv@568b1d21
at oracle.jdbc.dbaccess.DBError.throwSqlException(DBError.java:184)
at oracle.jdbc.dbaccess.DBError.throwSqlException(DBError.java:226)
at oracle.jdbc.oci8.OCIEnv.getEnvHandle(OCIEnv.java:79)
at oracle.jdbc.oci8.OCIDBAccess.logon(OCIDBAccess.java:390)
at oracle.jdbc.driver.OracleConnection.<init>(OracleConnection.java:353)
at oracle.jdbc.driver.OracleDriver.getConnectionInstance(OracleDriver.java:457)
at oracle.jdbc.driver.OracleDriver.connect(OracleDriver.java:332)
at java.sql.DriverManager.getConnection(DriverManager.java:543)
at java.sql.DriverManager.getConnection(DriverManager.java:163)
at oracle.jdbc.pool.OracleDataSource.getConnection(OracleDataSource.java:149)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPhysicalConnection
(OracleConnectionPoolDataSource.java:98)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPooledConnection
(OracleConnectionPoolDataSource.java:77)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPooledConnection
(OracleConnectionPoolDataSource.java:61)
at JDBCTestOraclePooledConnection.main(JDBCTestOraclePooledConnection.java:80)
Cause:
9i OCI driver is being used on AIX 64 bit machine. LIBPATH is correctly set, but
ORACLE_HOME is not set or is set incorrectly.
-----------------------------------------------------------------------------------------------------------------Error:
Exception in thread "main" java.sql.SQLException: Invalid Oracle URL specified
at oracle.jdbc.dbaccess.DBError.throwSqlException(DBError.java:169)
at oracle.jdbc.dbaccess.DBError.throwSqlException(DBError.java:211)
at oracle.jdbc.dbaccess.DBError.throwSqlException(DBError.java:274)
at oracle.jdbc.driver.OracleDriver.connect(OracleDriver.java:182)
at java.sql.DriverManager.getConnection(DriverManager.java:543)
at java.sql.DriverManager.getConnection(DriverManager.java:194)
at oracle.jdbc.pool.OracleDataSource.getConnection(OracleDataSource.java:111)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPhysicalConnection
(OracleConnectionPoolDataSource.java:98)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPooledConnection
(OracleConnectionPoolDataSource.java:77)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPooledConnection
(OracleConnectionPoolDataSource.java:61)
at JDBCTestOraclePooledConnection.main(JDBCTestOraclePooledConnection.java:80)
Cause:
Incorrectly specified URL. For 8i OCI driver, make sure oci8 is used in URL. For 9i OCI driver,
either oci8 or oci can be used.
-----------------------------------------------------------------------------------------------------------------Error:
Exception in thread "main" java.sql.SQLException: ORA-12154: TNS:could not resolve service
name
at oracle.jdbc.dbaccess.DBError.throwSqlException(DBError.java:169)
at oracle.jdbc.oci8.OCIDBAccess.check_error(OCIDBAccess.java:1614)
at oracle.jdbc.oci8.OCIDBAccess.logon(OCIDBAccess.java:360)
at oracle.jdbc.driver.OracleConnection.<init>(OracleConnection.java:265)
at oracle.jdbc.driver.OracleDriver.getConnectionInstance(OracleDriver.java:365)
at oracle.jdbc.driver.OracleDriver.connect(OracleDriver.java:260)
at java.sql.DriverManager.getConnection(DriverManager.java:543)
at java.sql.DriverManager.getConnection(DriverManager.java:194)
at oracle.jdbc.pool.OracleDataSource.getConnection(OracleDataSource.java:111)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPhysicalConnection
(OracleConnectionPoolDataSource.java:98)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPooledConnection
(OracleConnectionPoolDataSource.java:77)
at oracle.jdbc.pool.OracleConnectionPoolDataSource.getPooledConnection
(OracleConnectionPoolDataSource.java:61)
at JDBCTestOraclePooledConnection.main(JDBCTestOraclePooledConnection.java:80)
Cause:
Incorrect or missing $ORACLE_HOME/network/admin/TNSNAMES.ORA entry.