What Is New In This Release?

These are the major new features/enhancements in this release:

- Statement Caching
* Implicit Statement Caching
* Explicit Statement Caching

- Full XA Support
* Including XA Recover and Forget
* OracleXid independent implementation for 8.1.7 servers and above

- Connection Caching
* Statement Caching coupling

- PLSQL Tables Support for Scalar types (for OCI driver only)

- User-Defined Datatypes Performance Enhancement

- Object Types Extensions
* Serializable Type Descriptors
* Accessing collection elements in Java primitive types
* Buffering and indexing collection elements
* Creating empty Lobs

- Support for 56-bit encryption algorithms for connection using
the Thin JDBC driver.

These are the major bug fixes:

- BUG-903011
The JDBC Thin driver could not be used with usernames that
contained Latin-1 characters when the server used UTF8 character
set. This problem has been fixed in release 8.1.7.

- BUG-1052489
There was a problem with PreparedStatements being executed
multiple times and the length of one of the bind variables (bound
with setBinaryStream or setCharacterStream) increased. This
problem has been fixed in release 8.1.7.

- BUG-1069768
There was a problem with insertion of ADTs with an image bigger
than 4K with the JDBC Thin driver. This problem has been fixed
in release 8.1.7.

- BUG-1247015
When using ResultSet::getObject() to access CHAR or VARCHAR columns
in scrollable result sets, ResultSet::getObject() returned null.

- BUG-1349713
getString() of scrollable result sets returns incorrect values if
the column data contains multibyte characters.

Driver Versions

These are the driver versions in the 8.1.7 release:

- JDBC OCI Driver 8.1.7
Client-side JDBC for use on a machine where OCI 8.1.7 is installed.

- JDBC Thin Driver 8.1.7
100% Java client-side JDBC for use in applets and applications.

- JDBC Thin Server-side Driver 8.1.7
JDBC for use by Java Stored Procedures or by Java CORBA objects
running in Oracle 8.1.7. This driver is typically used in a middle
tier server.

- JDBC Server-side Internal Driver 8.1.7
Server-side JDBC for use by Java Stored procedures or by Java CORBA
objects running in Oracle 8.1.7. This driver used to be called the
"JDBC Kprb Driver".

For complete documentation, please refer to "JDBC Developer's Guide
and Reference".

Contents Of This Release

The [ORACLE_HOME]/jdbc/lib directory contains:

- classes111.zip
Classes for use with JDK 1.1.x. It contains the JDBC driver
classes except classes necessary for NLS support in Object and
Collection types.

- nls_charset11.zip
NLS classes for use with JDK 1.1.x. It contains classes necessary
for NLS support in Object and Collection types.

- classes111_g.zip
Same as classes111.zip, except that classes were compiled with
"javac -g".

- classes12.zip
Classes for use with JDK 1.2.x. It contains the JDBC driver
classes except classes necessary for NLS support in Object and
Collection types.

- nls_charset12.zip
NLS classes for use with JDK 1.2.x. It contains classes necessary
for NLS support in Object and Collection types.

- classes12_g.zip
Same as classes12.zip, except that classes were compiled with
"javac -g".

Note that the packaging of the JDBC classes to support NLS was
changed in 8i. The classes pertaining to specific character sets
support in Object and Collection types have been separated from the
basic zip files. These NLS classes are now packaged into the
extension zip files. This allows the user to include the NLS
classes only if necessary. Please refer to the "NLS Extension Zip
Files (for client-side only)" for further details.

[ORACLE_HOME]/lib directory contains libocijdbc8.so and
libocijdbc8_g.so (on Solaris), which are the shared libraries used by
the JDBC OCI driver.

[ORACLE_HOME]/jdbc/doc/javadoc.tar contains the JDBC Javadoc. This
release contains a beta release of the Javadoc files for the public
API of the public classes of Oracle JDBC.

[ORACLE_HOME]/jdbc/demo/demo.tar contains sample JDBC programs.
Demo programs written for JDK 1.1 must be modified to run in JDK 1.2.
Please refer to the "Support For JDK 1.2" for porting details.

NLS Extension Zip Files (for client-side only)

The JDBC Server-side Internal Driver provides complete NLS support.
It does not require any NLS extension zip files, nls_charset*.zip.
Discussions in this section do not apply to the JDBC Server-side
Internal Driver. You can skip this section if you only use the
Server-side Internal Driver.

The basic zip files, classes111.zip and classes12.zip, contain all the
necessary classes to provide complete NLS support for:

- Oracle Character sets for CHAR/VARCHAR/LONGVARCHAR/CLOB type data
that is not retrieved or inserted as a data member of an Oracle 8
Object or Collection type.

- NLS support for CHAR/VARCHAR data members of Objects and
Collections for a few commonly used character sets. These
character sets are: US7ASCII, WE8DEC, WE8ISO8859P1 and UTF8.

Users must include the appropriate extension zip in their CLASSPATH
if utilization of other character sets in CHAR/VARCHAR data members
of Objects/Collections is desired. It is important to note that
extension zip files are large in size due to the requirement of
supporting a large number of character sets. Users may choose to
include only the necessary classes from the extension zip file.
To do so, users can first unzip the extension zip file, and then put
only the necessary classes in the CLASSPATH. The character set
extension class files are named in the following format:


where <OracleCharacterSetId> is the hexidecimal representation of the
Oracle character set id of the corresponding character set.



Please do not try to put multiple versions of the Oracle JDBC drivers
in your CLASSPATH. The Oracle installer installs the JDBC Drivers in
the [ORACLE_HOME]/jdbc directory.

Setting Up Your Environment

On Win95/Win98/NT:
- Add [ORACLE_HOME]\jdbc\lib\classes111.zip and
[ORACLE_HOME]\jdbc\lib\nls_charset11.zip to your CLASSPATH.
(Add classes12.zip and nls_charset12.zip if JDK 1.2.x is used.)
- Add [ORACLE_HOME]\jdbc\lib to your PATH.

On Solaris/Digital Unix:
- Add [ORACLE_HOME]/jdbc/lib/classes111.zip and
[ORACLE_HOME]/jdbc/lib/nls_charset11.zip to your CLASSPATH.
(Add classes12.zip and nls_charset12.zip if JDK 1.2.x is used.)
- Add [ORACLE_HOME]/jdbc/lib to your LD_LIBRARY_PATH.

- Add [ORACLE_HOME]/jdbc/lib/classes111.zip and
[ORACLE_HOME]/jdbc/lib/nls_charset11.zip to your CLASSPATH.
(Add classes12.zip and nls_charset12.zip if JDK 1.2.x is used.)
- Add [ORACLE_HOME]/jdbc/lib to your SHLIB_PATH and LD_LIBRARY_PATH.

- Add [ORACLE_HOME]/jdbc/lib/classes111.zip and
[ORACLE_HOME]/jdbc/lib/nls_charset11.zip to your CLASSPATH.
(Add classes12.zip and nls_charset12.zip if JDK 1.2.x is used.)
- Add [ORACLE_HOME]/jdbc/lib to your LIBPATH and LD_LIBRARY_PATH.

Some Useful Hints In Using the JDBC Drivers

Please refer to "JDBC Developer's Guide and Reference" for details
regarding usage of Oracle's JDBC Drivers. This section only offers
useful hints. These hints are not meant to be exhaustive.

These are a few simple things that you should do in your JDBC program:

1. Import the necessary JDBC classes in your programs that use JDBC.
For example:

import java.sql.*;
import java.math.*;

2. Register the Oracle driver before before calling other JDBC APIs.
(This is not needed if you are using the JDBC Server-side Internal
Driver because registration is done automatically in the server.)
To register the Oracle driver, make sure the following statement
is executed at least once in your Java session:

new oracle.jdbc.driver.OracleDriver());

3. Open a connection to the database with the getConnection call.
Different connection URLs should be used for different JDBC
drivers. The following examples demonstrate the different URLs.

For the JDBC OCI8 Driver:

Connection conn = DriverManager.getConnection(
"scott", "tiger");

where <database> is either an entry in tnsnames.ora or a SQL*net
name-value pair.

For the JDBC Thin Driver, or Server-side Thin Driver:

Connection conn = DriverManager.getConnection(
"scott", "tiger");

where <database> is either a string of the form
<host>:<port>:<sid> or a SQL*net name-value pair.

For the JDBC Server-side Internal Driver:

Connection conn = DriverManager.getConnection(

Note that the trailing ':' character is necessary. When you use
the Server-side Internal Driver, you always connect to the
database you are executing in. You can also do this:

Connection conn
= new oracle.jdbc.driver.OracleDriver().defaultConnection();

Java Stored Procedures

Please note that examples for callins and instance methods using Oracle
8 Object Types are provided in:


Once unzipped, the directory containing the examples is:


Known Problems/Limitations In This Release

The following is a list of known problems/limitations:

1. There is a limitation regarding the use of stream input for LOB
types. Stream input for LOB types can only be used for 8.1.7
JDBC OCI driver connecting to an 8.1.7 Oracle server. The use of
stream input for LOB types in all other configurations may result
in data corruption. PreparedStatement stream input APIs include:
setBinaryStream(), setAsciiStream(), setUnicodeStream(),
setCharacterStream() and setObject().

2. BUG-1018797
Extra characters may be appended to the end of a CLOB value
mistakenly under the following conditions:
- setCharacterStream() is used to insert a CLOB value, and
- The Oracle server uses multi-byte character set.

(See 1 for limitation of stream input for LOB type.)

3. Programs can fail to open 16 or more connections using our
client-side drivers at any one time. This is not a limitation
caused by the JDBC drivers. It is most likely that the limit of
per-process file descriptors is exceeded. The solution is to
increase the limit.

4. The Server-side Internal Driver has the following limitation:
- Data access for LONG and LONG RAW types is limited to 32K of
- Inserts of Object Types (Oracle 8 Objects, Collections and
References) will not work when the database compatibility mode
is set to 8.0. This limitation does not apply when the
compatibility mode is set to 8.1.
- Statement.cancel() is not implemented.
- In a chain of SQLExceptions, only the first one in the chain
will have a getSQLState value.

5. The JDBC OCI driver on an SSL connection hangs when the Java
Virtual Machine is running in green threads mode. A work-around
is to run the Java Virtual Machine in native threads mode.

6. Date-time format, currency symbol and decimal symbols are always
presented in American convention.

7. When using OracleStatement.defineColumnType(), it is not necessary
to define the column type to be the same as the column type
declared in the database. If the types are different, the
retrieved values are converted to the type specified in

Note: Most reasonable conversions work, but not all. If you find
a conversion that you think is reasonable, but that does not work,
please submit a TAR to Oracle Support.

8. The utility dbms_java.set_output or dbms_java.set_stream that is
used for redirecting the System.out.println() in JSPs to stdout
SHOULD NOT be used when JDBC tracing is turned on. This is
because the current implementation of dbms_java.set_output and
set_stream uses JDBC to write the output to stdout. The result
would be an infinite loop.

9. The JDBC OCI and Thin drivers do not read CHAR data via binary
streams correctly. In other word, using getBinaryStream() to
retrieve CHAR data may yield incorrect results. A work-around is
to use either getCHAR() or getAsciiStream() instead. The other
alternative is to use getUnicodeStream() although the method is

10. BUG-899078 (since 8.1.6 SDK):
The JDBC Server-side Internal driver has extra space padding with
PL/SQL CHAR OUT (2 to 3 space depending on character set).
Problem occurs in most of the multibyte database character set
except UTF8.

11. There is a limitation for Triggers implemented in Java and Object
Types. It only affects the IN argument types of triggers
implemented using Java on the client-side. The restriction does
not apply to JDBC programs running inside the server. Triggers
implemented as Java methods cannot have IN arguments of Oracle 8
Object or Collection type. This means the Java methods used to
implement triggers cannot have arguments of the following types:

- java.sql.Struct
- java.sql.Array
- oracle.sql.STRUCT
- oracle.sql.ARRAY
- oracle.jdbc2.Struct
- oracle.jdbc2.Array
- any class implementing oracle.jdbc2.SQLData or

12. The scrollable result set implementation has the following

- setFetchDirection() on ScrollableResultSet is not supported.
- refreshRow() on ScrollableResultSet does not support all
combinations of sensitivity and concurrency. The following
table depicts the supported combinations.

Support Type Concurrency

13. BUG-1324918
Repeatedly updating a clob with jdbc-oci, prepared statement,
and setCharacterStream consumes the temporary tablespace. If
you repeatedly update the clob, either the temp tablespace will
continue to grow, or you may get a Exception in thread "main"
java.sql.SQLException: ORA-01652: unable to extend segment if
you have a limit on the tablespace size. The work-around is to
use oracle.sql.CLOB::setCharacterOutputStream() instead.