
Oracle JDBC Drivers release 8.1.7 README
========================================


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
    * New Scheme (FIXED_WAIT_SCHEME)
    * 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:

  CharacterConverter<OracleCharacterSetId>.class

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


-----------------------------------------------------------------------


Installation
------------

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.

On HP/UX:
  - 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.

On AIX:
  - 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:

      DriverManager.registerDriver(
        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(
                          "jdbc:oracle:oci8:@<database>",
                          "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(
                          "jdbc:oracle:thin:@<database>",
                          "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(
                          "jdbc:oracle:kprb:");

      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:

  [ORACLE_HOME]/javavm/demo/demo.zip

Once unzipped, the directory containing the examples is:

  [ORACLE_HOME]/javavm/demo/examples/jsp


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
      data.
    - 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
    defineColumnType.

    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
    deprecated.

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
      oracle.sql.CustomDatum

12. The scrollable result set implementation has the following
    limitation:

    - 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
        -------------------------------------------------------
        no          TYPE_FORWARD_ONLY          CONCUR_READ_ONLY
        no          TYPE_FORWARD_ONLY          CONCUR_UPDATABLE
        no          TYPE_SCROLL_INSENSITIVE    CONCUR_READ_ONLY
        yes         TYPE_SCROLL_INSENSITIVE    CONCUR_UPDATABLE
        yes         TYPE_SCROLL_SENSITIVE      CONCUR_READ_ONLY
        yes         TYPE_SCROLL_SENSITIVE      CONCUR_UPDATABLE

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.
