Release Notes for Oracle SQLJ Release 8.1.7.0.0 Production
(build version 2.0.0.0) June 30 2000


CONTENTS OF THIS README
=======================

  1. WHAT IS SQLJ?
  2. WHAT IS IN THIS DISTRIBUTION?
  3. INSTALLATION
  4. WHAT’S NEW?
  5. PLATFORM-SPECIFIC INFORMATION
  6. BUGS FIXED
  7. KNOWN RESTRICTIONS AND PROBLEMS
  8. USING SQLJ IN Server-Side JavaVM: KNOWN RESTRICTIONS AND PROBLEMS


1. WHAT IS SQLJ?
================

Oracle, IBM, Compaq, Sybase, Informix, Sun Microsystems, and others have
contributed to the SQLJ Standard for embedding static SQL statements and
constructs in Java programs (ANSI X3.135.10-1998). An updated version of
this standard is currently being finalized by ISO.

SQLJ is a way to reduce the development and maintenance costs of Java
programs that require Database connectivity. SQLJ provides a simpler model
for Java code containing static SQL Statements (SQL that does not change
each time you run your application or applet. Applications typically
contain more static SQL than dynamic SQL). The reduction in the cost of
development and maintenance occurs because SQLJ uses an easier methodology
of embedding SQL directly into Java programs, resulting in more concise and
more legible code. SQLJ can further make coding easier by providing
compile-time checks on the SQL statements your application uses. In using
dynamic SQL APIs such as JDBC, you won't find out if your SQL is
syntactically or semantically wrong until you test the line in your code
that runs it.

This implementation, the 8.1.7.0.0 Production release of Oracle's SQLJ
Implementation, is in the form of a translator that takes SQLJ programs and
turns them into Java programs that call -via the SQLJ runtime- JDBC. The
translator itself is written purely in Java.

This release supports the ANSI standard for embedding SQL in Java.
Furthermore, the JDK 1.2 runtime of this release supports the forthcoming
ISO standard for embedding SQL in Java.

This release supports the features of the Oracle 8.1.7.0.0 JDBC drivers.
Additionally, you can use this release with any Oracle JDBC driver running
against an Oracle database, as well as any standard JDBC Driver running
against any database system.

For more information, visit the Oracle Technology network site at:

     http://technet.oracle.com/tech/java/sqlj_jdbc/

You can also find information on SQLJ at:

     http://www.oracle.com/java/sqlj/

Oracle Support services this product. For more information see:

     http://www.oracle.com/support/

Note on Version Numbers: version 8.1.7 is synonymous with Oracle8i Release
3, version 8.1.6 is synonymous with Oracle8i Release 2, and version 8.1.5
corresponds to Oracle8i.


2. WHAT IS IN THIS DISTRIBUTION?
================================

We assume that you have installed the SQLJ distribution files through the
Oracle 8.1.7 Installer into the directory $ORACLE_HOME/sqlj. $ORACLE_HOME
is the root installation directory for Oracle products.

This distribution contains:

   * This file [$ORACLE_HOME/sqlj/README.txt].
   * An HTML file detailing the SQLJ installation. This file also contains
     references to the other documentation [$ORACLE_HOME/sqlj/index.html].
   * White Paper "SQLJ: Embedded SQL in Java" in PDF format
     [$ORACLE_HOME/sqlj/doc/whitepaper.pdf].
   * Technical White Paper "Overview of SQLJ - Embedded SQL in Java" in PDF
     format [$ORACLE_HOME/sqlj/doc/sqlj-overview.pdf].
   * Technical White Paper "Using Oracle Objects in SQLJ programs" in PDF
     format [$ORACLE_HOME/sqlj/doc/sqlj-objects.pdf].
   * The SQLJ Primer "SQLJ: Tricks, Traps, and Gems" in PDF format
     [$ORACLE_HOME/sqlj/doc/sqlj-primer.pdf].
   * SQLJ Runtime API: runtime packages documented in the javadoc format
     [$ORACLE_HOME/sqlj/doc/runtime].
   * Different SQLJ runtime versions:

        o [$ORACLE_HOME/sqlj/lib/runtime11.zip] - runtime for JDK 1.1,
          Oracle 8.1.7 JDBC
        o [$ORACLE_HOME/sqlj/lib/runtime12.zip] - runtime for JDK 1.2,
          Oracle 8.1.7 JDBC
        o [$ORACLE_HOME/sqlj/lib/runtime.zip] - runtime for all JDK, all
          JDBC drivers

   * The zip file containing the *.class files for the SQLJ translator. In
     order to use the translator you also need one of the runtime zips
     above. [$ORACLE_HOME/sqlj/lib/translator.zip]
   * Files for testing your installation
     [$ORACLE_HOME/sqlj/demo/TestInstall*]
   * Sample files [$ORACLE_HOME/sqlj/demo].

        o see [$ORACLE_HOME/sqlj/demo/README.txt] for more information,
        o additional examples using object types
          [$ORACLE_HOME/sqlj/demo/Objects],
        o examples showing JDBC 2.0-derived features from the SQLJ ISO
          standard [$ORACLE_HOME/sqlj/demo/jdbc20],
        o examples using Java stored procedures
          [$ORACLE_HOME/sqlj/demo/server],
        o examples showing SQLJ programs in applets
          [$ORACLE_HOME/sqlj/demo/applets],
        o and examples of SQLJ customization and SQL checking components
          [$ORACLE_HOME/sqlj/demo/components].

   * Wrapper scripts and/or wrapper executables to simplify the invocation
     of SQLJ and related tools [$ORACLE_HOME/bin].

Direct your Web browser to $ORACLE_HOME/sqlj/index.html for an index of the
SQLJ documentation provided with this SQLJ installation.

The book "SQLJ Developer's Guide and Reference" is distributed
independently as part of the Oracle 8.1.7 documentation. It documents the
details of this version of SQLJ - how to test the installation and use the
product. The books in the Oracle 8.1.7 documentation are also available
online at:

     http://technet.oracle.com/docs/products/oracle8i/doc_index.htm

For information about the JPublisher tool for generating Java classes for
SQL object and collection types, please refer to the book "JPublisher
Developer's Guide and Reference". Please refer to the book "JDBC
Developer's Guide and Reference" for information about Oracle's JDBC
drivers.


3. INSTALLATION
===============

You must have a JDK 1.1.* or JDK 1.2 compatible Java environment.
Furthermore, you should have installed the Oracle 8.1.7 JDBC driver.

Ensure that the directory $ORACLE_HOME/bin with the sqlj shell script or
executable is in your PATH.

   * Add the file $ORACLE_HOME/sqlj/lib/translator.zip to the environment
     variable CLASSPATH.
   * If you are using JDK 1.1.x and Oracle JDBC 8.1.7 then add the file
     $ORACLE_HOME/sqlj/lib/runtime11.zip to your CLASSPATH.
   * If you are using JDK 1.2 or later and Oracle JDBC 8.1.7 then add the
     file $ORACLE_HOME/sqlj/lib/runtime12.zip to your CLASSPATH.
   * Otherwise (that is, if you are not using Oracle JDBC 8.1.7) add the
     file $ORACLE_HOME/sqlj/lib/runtime.zip to your CLASSPATH.

--- ATTENTION --- ATTENTION --- ATTENTION --- ATTENTION --- ATTENTION ---

   * Previous SQLJ releases only required that you place translator.zip in
     the CLASSPATH in order to translate and/or run SQLJ programs.
   * SQLJ 8.1.7 and later requires that you place translator.zip and one of
     the runtime zip files (runtime.zip, runtime11.zip, or runtime12.zip)
     in your CLASSPATH in order to translate SQLJ programs.

--- ATTENTION --- ATTENTION --- ATTENTION --- ATTENTION --- ATTENTION ---

The "Getting Started" section of the "SQLJ Developer's Guide and Reference"
discusses required settings for PATH and CLASSPATH in more detail.

You should first verify your JDBC installation before using SQLJ. Refer to
the section "Getting Started" in the book "SQLJ Developer's Guide and
Reference" for information on testing your SQLJ and JDBC installations.

This distribution of SQLJ has been run under the following configurations:

   * for Applications: Solaris 2.6 with Oracle's 8.1.7 JDBC-OCI8, and 8.1.7
     JDBC-Thin drivers, Windows NT 4.0 with Oracle's 8.1.7 JDBC-OCI8, and
     8.1.7 JDBC-Thin drivers, Oracle 8.1.7 server-side JavaVM with
     server-side (kprb) JDBC drivers
   * for Applets: Netscape 4.7 (Windows NT, Solaris), MS Internet Explorer
     5.0 (Windows NT, Windows 95), AppletViewer (Solaris), Java plug-in
     1.1.2 (NT Explorer, Solaris Netscape, and NT Netscape)


4. WHAT’S NEW?
==============

CHANGES SINCE VERSION 8.1.6.0.0 OF SEP 15 1999
----------------------------------------------

LANGUAGE

   * support for JDBC 2.0 features as defined in the SQLJ ISO specification
     (see $ORACLE_HOME/sqlj/demo/jdbc20 for sample programs).
        o connection context type maps for reading and writing user defined
          types, such as instances of java.sql.SQLData. This feature
          requires JDK 1.2 and the SQLJ runtime runtime12.zip.
        o support for scrollable iterators (both, positional and named)
        o association of connection contexts with DataSources
        o control of batching and row prefetch through the ExecutionContext
        o support for JDBC 2.0 connection pooling

   * support for Java object serialization in RAW and BLOB columns, using
     connection context type maps
   * new "FETCH CURRENT FROM ..." syntax for positional iterators permits
     preserving program logic when migrating result sets to SQLJ iterators

TRANSLATOR

The translator's statusMain method can be called multiple times. This
permits the embedding of SQLJ in Oracle's JSP translator [Bug 1321820]

RUNTIME

   * availability of different SQLJ runtime libraries:

        o runtime11.zip, runtime12.zip: applet-enabled and optimized for
          use with the Oracle JDBC 8.1.7 drivers
        o runtime.zip: provides compatibility with all Oracle JDBC drivers

SEE ALSO: Bug fixes - section 6. below.


CHANGES SINCE VERSION 8.1.5.0.0 (AND SOME SINCE 8.1.4)
------------------------------------------------------

LANGUAGE

   * SQLJ support for the Java language has been improved (see [Bug
     808400], [Bug 808729], [Bug 808856], and [Bug 845528] below).
   * Public static final field values (such as attributes in WITH clauses)
     are now properly and fully evaluated at translate time by SQLJ [Bug
     808856].
   * SQLJ now permits subclassing of iterators. SQLJ now permits you to use
     subclasses of oracle.sql.CustomDatum classes as host expressions [Bug
     879170]
   * SQLJ now supports the JDBC 2.0 types
     java.sql.Struct/Ref/Array/Blob/Clob.
   * SQLJ now supports JPublisher-generated JDBC 2.0 Java wrapper classes
     that implement the java.sql.SQLData interface.

This version supports the ANSI standard ANSI X3.135.10-1998.

TRANSLATOR

   * SQLJ now has a limited form of make functionality, similar to javac
     [Bug 801780].
     Note: you must always specify all relevant .sqlj source files on the
     SQLJ command line. The translator can automatically check for
     additional .java sources, but not for possibly required .sqlj sources.
     Use the following command line option to turn this functionality off.
     checksource=false
   * Use the new -jdblinemap option instead of -linemap if you expect to
     debug the instrumented class files under the jdb debugger [Bug
     868524].
   * The -help option now prints a usage synopsis. Full help on all option
     settings has been moved to the -help-long option. Command line
     shorthand notation is explained with the option -help-alias.
   * A -version-long option prints out additional version information,
     including the Oracle JDBC driver version (if any) accessible in the
     CLASSPATH and the version of Java that you are using.
   * An -explain flag was added. This flag displays cause/action
     information on error and warning messages issued by the SQLJ
     translator.

CHECKING

The default offline and online checker class is now
oracle.sqlj.checker.OracleChecker. Depending on the JDBC driver detected in
your configuration, an appropriate checker will be selected. You need only
explicitly specify a particular checker when you are using an 8.0.x or
8.1.x JDBC driver and want to"downgrade" the types supported by your
program to Oracle7 functionality.

PERFORMANCE

SQLJ now supports all the performance enhancements previously available
through Oracle's JDBC drivers. See "SQLJ User's Guide and Reference -
Appendix A." for a complete description.

   * Statement caching. By default, the SQLJ runtime caches the last five
     SQL statements that it executed on a given JDBC connection. You can
     use the -P-Cstmtcache=NN flag to set the statement cache size to NN.
     Setting the size to 0 disables statement caching.
   * Batching. SQLJ now supports batching of INSERT, DELETE, and UPDATE
     statements. The batching function is controlled through the
     ExecutionContext. Note: The batching API provided complies with the
     SQLJ batching support in the forthcoming ISO standard for SQLJ.
   * Parameter size registration. Optimizations for variable-size
     parameters and result set columns can be enabled through new flags
     -P-Coptcols and -P-Coptparams.

RUNTIME

Changes in runtime support:
[$ORACLE_HOME/sqlj/doc/runtime/RELEASENOTES.txt]


5. PLATFORM-SPECIFIC INFORMATION
================================

We offer several general troubleshooting tips that should help in working
around platform specific problems that might occur.

GENERAL TROUBLESHOOTING

   * Turn off the JIT (Just In Time compilation). In many cases, this
     eliminates the problem. Either set the environment variable:
     JAVA_COMPILER=NONE
     or specify the following additional flag to the SQLJ command line:
     J-Djava.compiler=none
     Note: You can set the SQLJ_OPTIONS environment variable to any
     additional flags that you always want to send to the SQLJ command
     line.
   * Reduce your PATH to contain a single, known JDK version.
   * Reduce your CLASSPATH to only contain:

        o your source files (often this is . - the current directory)
        o the Oracle JDBC driver classes111.zip or classes12.zip
        o the SQLJ translator translator.zip
        o one of the SQLJ runtimes (runtime.zip, runtime11.zip, or
          runtime12.zip)

   * If you experience a hang during Java compilation (use the -status flag
     on the SQLJ command line to see how far the SQLJ translator got), then
     add the following flag to the SQLJ command line.
     -passes
   * Use a different JDK version.

UNIX PLATFORMS

   * If you need to customize the way in which SQLJ invokes the JavaVM and
     the Java compiler on your platform, you can edit the shell script:
     $ORACLE_HOME/bin/sqlj

WINDOWS PLATFORMS

Note that the wrapper executable $ORACLE_HOME/bin/sqlj.exe has only been
tested on Windows NT.

   * Some version of Windows place rather severe restrictions on the number
     of characters in the environment and on the command line.
   * On Windows 95 you cannot use the ‘=’ character in the string that is
     assigned to environment variables. In SQLJ_OPTIONS you can use ‘#’
     instead. Thus, on Windows 95, instead of specifying, for example, the
     following to turn the JIT off:
     set SQLJ_OPTIONS=-J-Djava.compiler=none
     you would say:
     set SQLJ_OPTIONS=-J-Djava.compiler#none

   * You must not have space characters in your CLASSPATH


6. BUGS FIXED
=============

IN SQLJ VERSION 8.1.7
---------------------

TRANSLATOR

   * SQL source text in SQLJ statements of arbitrary size is now supported
     [Bug 1018117]. Earlier versions were limited to 65k.
   * The -ser2class conversion now supports .ser files of arbitrary size
     [Bug 1061663]. Earlier versions were limited to 32k.

RUNTIME

   * The new Oracle SQLJ library runtime11.zip now permits Oracle SQLJ
     programs to properly work in applet environments [Bug 814704].
     Note: Depending on the browser used, certain features (CAST statement,
     CustomDatum and SQLData support) may not be available, since these do
     require the use of reflection. Another workaround is to use the Java
     plug-in provided by Sun Microsystems. It will permit all SQLJ
     statements to run - even in pre-4.X browsers.
     See also the applet demos in [$ORACLE_HOME/sqlj/demo/applets].

   * The following error does not occur any longer in SQLJ applets.[Bug
     850197]:
     java.lang.IllegalAccessError:
     sqlj.runtime.ExecutionContext.DEBUG
     at sqlj.runtime.ExecutionContext$StatementStack.setStatement


IN SQLJ VERSION 8.1.6
---------------------

LANGUAGE

   * SQLJ now permits "mixed" Array declarations [Bug 808400], such as
     int[] a,b[];
   * SQLJ host expressions now permit calls to functions that return an
     array [Bug 845528]
   * SQLJ iterator and context declarations inside of method blocks are now
     permitted [Bug 808729].
     Note: In JDK 1.1.X you cannot reference classes declared at the block
     level. You will see a subsequent error by the Java compiler when you
     try to use such a class. However, JDK 1.2 fully supports lock-level
     declarations.
   * Japanese halfwidth sound characters such as \uff70 and \uff65 are now
     accepted in SQL identifiers. In general, SQL identifiers can be
     composed of characters from the superset of the definitions of letters
     and digits in Unicode 2.0, Java, and all Oracle SQL character sets.

TRANSLATOR

   * The SQLJ translator now works with JDK 1.2 [Bug 814692]. Ensure that
     you are using the proper Oracle JDBC driver file (classes12.zip).
   * The current release of the SQLJ translator runs under Microsoft's J++
     Java VM (jview), and the generated *.java files compile under
     Microsoft's J++ Java compiler (jvc).
   * The -linemap option now instruments all the Java classes declared in a
     .sqlj source file, including inner classes. The only exception is
     anonymous classes, which are currently not being instrumented.
     Problems that occurred during instrumentation are fixed [Bugs 814687,
     814680].
   * SQL source text in SQLJ statements may now have arbitrary size. [Bug
     1018117].
   * SQLJ -ser2class conversion now works for any number of files [Bug
     859265].
   * Additionally, -ser2class can now convert .ser files of abitrary size
     to .class representation [Bug 1061663].
   * Certain warnings are no longer reported on the wrong source file [Bug
     859307].
   * SQLJ now detects the invalid use of "/" instead of "\" as directory
     separator on the Windows NT platforms and will issue an error [Bug
     550152].
   * SQLJ should no longer experience hangs on NT [Bug 749636]. The use of
     the -passes option is no longer required on the NT platform.

ONLINE CHECKING

   * Multiple database errors are now correctly reported [Bug 460846].
   * Stored procedure overloading now matches the PL/SQL rules [Bug
     808874].

RUNTIME

A SQLException will now be issued when a SQLJ connection context is
initialized with a null JDBC connection.


7. KNOWN RESTRICTIONS AND PROBLEMS
==================================

A list of know issues and bugs in SQLJ version 8.1.7.0.0

LANGUAGE

   * Classes containing executable SQLJ statements should not be named
     "java", "sqlj", or "oracle" [Bug 808835]. Additionally, if your SQLJ
     statements use host variables whose type is a user-defined type
     "x.y.MyClass", then the class using this host variable should not be
     named "x".
     To avoid this problem, we recommend you follow the Java naming
     convention of package names starting with lower case and class names
     starting with upper case.
   * SQLJ cannot import classes of the form a$b [Bug 1083057]. Instead of
     referencing a$b.c, it will incorrectly use a$b$c. Try to avoid
     referencing classes that have the character "$" in their name.
   * SQLJ translation does not support remote procedure calls [Bug
     1275178], such as
     #sql { call remote_procedure@db_link(...) };
     As workaround, in SQLJ 8.1.7 remote procedure calls are supported
     during offline translation, but result in errors during online
     translation.

TRANSLATOR

   * Only French, German, and Japanese message translations are available.
     Moreover, these translations are only partial, and do not include the
     help messages. [Bugs 803875, 803869].
   * The SQLJ translator does not support file or directory names
     containing spaces [Bug 864304]. This affects in particular the -d,
     -dir, and -classpath options.
     Note that on the Windows NT platform, Sun's JDK does support file and
     directory names with embedded spaces. As a workaround you could use
     the DOS-style equivalent "short" file or directory name in the -d,
     -dir, or -classpath options.
   * The SQLJ translator might experience hangs on Solaris [Bug N/A]. We
     have experienced occasional hangs when running the SQLJ translator on
     Solaris 2.6. This happened when using the JavaVM in /usr/bin/java
     (java version "1.1.3") distributed with the Solaris Operating System.
     You can work around this problem by using the JavaVM from one of the
     JDK's instead of the VM that came with your operating system.
   * SQLJ translation might occassionally experience a JavaVM core dump
     [Bug 1102856]. The following is the top of the Java stack dump issued:

     java.util.zip.ZipFile.findEND(ZipFile.java)
     java.util.zip.ZipFile.readCEN(ZipFile.java)
     java.util.zip.ZipFile.<init>(ZipFile.java)
     java.util.zip.ZipFile.<init>(ZipFile.java)
     sun.tools.java.ClassPath.<init>(ClassPath.java)
     If you see this problem, you can use one of the following workarounds.

        o Remove $ORACLE_HOME/lib/lclasses11.zip and [JDK
          Home]/lib/classes.zip from your CLASSPATH.
        o Do not use JDK 1.1.6. This problem has not been observed under
          other JDK versions.
        o Call sqlj from the command line. This problems not been observed
          when the SQLJ wrapper script was directly invoked from the
          command line.

   * Some encodings supported by Java are invalid in SQLJ [Bug 1051122].

        o When using JDK1.1.3, the following encodings work with javac but
          not sqlj:
          Cp1125, GBK, ISO2022CN, ISO2022CN_CNS, ISO2022CN_GB, ISO2022KR,
          JIS0208
        o When using JDK1.1.6, the following encodings work with javac but
          not sqlj:
          Cp1125, ISO2022CN, ISO2022CN_CNS, ISO2022CN_GB, JIS0208.
        o When using JDK1.2 the following encodings work with javac but not
          sqlj:
          ISO2022CN, ISO2022CN_CNS, ISO2022CN_GB.
   * When using JDK 1.1.8 on NT, it has been reported that the SQLJ
     translator generates truncated .java files [Bug 1080299]. In this case
     you will have to use a different JDK version.

   * "Unable to convert XXXX.ser to a class file." [Bug 1070362] When you
     use the -ser2class option and have packages, you must either

        o mirror the package hierarchy with your source hierarchy and
          always translate from the root (in this case . must be on the
          CLASSPATH), or
        o translate into a class repository directory (which must be on the
          CLASSPATH) using the -d option.

RUNTIME

   * Under JDK 1.2.1 a NullPointerException may be experienced when
     close()ing an iterator instance. This might occur in code of the
     following form:
     NamedOrPositionalIterator iter;
     #sql iter = { SELECT .. };
     ... while loop to process iter ..
     iter.close(); // <== NullPointerException on iter!
     This problem is due to faulty garbage collection under JDK 1.2.1. You
     will have to run your SQLJ program under a different JDK version [Bug
     1130431].
   * Locale dependent literals cannot be used when using the JDBC thin
     driver [Bug 810245]


8. USING SQLJ IN Server-side JavaVM: KNOWN RESTRICTIONS AND PROBLEMS
====================================================================

For your convenience we list some additional limitations and differences of
the SQLJ translator that is part of the Oracle 8.1.7 server-side JavaVM.

You may find this useful when you want to compile the same code on both,
client and server. You can also circumvent the limitations below (with the
exception of [Bug 1094935]) by compiling your sources outside of JServer
and then uploading the compiled files with loadjava.

IMPORTANT: Since the server-side JavaVM implements JDK 1.2, it is
recommended that you use JDK 1.2, the Oracle 8.1.7 JDBC driver library
classes12.zip, and the SQLJ runtime library runtime12.zip to compile and
test your programs on the client. This ensures the highest degree of
correspondence between your client and server-side environments.

LANGUAGE

   * Nested interface declarations are not supported [Bug 1049817]. For
     example, the following declaration is not supported:
     interface Nested { #sql static iterator NestedCur(int); }
   * WITH-clause declarations are not supported [Bug 1049818].
   * Class declarations at the block level are not permitted [Bug 1034704].
     Such declarations are permissible in JDK 1.2.

TRANSLATOR

   * When a duplicate class declaration occurs, SQLJ may throw a stack
     trace instead of issuing a Class Circularity Error [Bug 1018565].
   * In error messages, the server side SQLJ translator shows the name of
     the first public class, or -if there is no public class- the nameof
     the first class in the source as the actual name of the source file
     [Bug 1018533].
   * JServer verifier errors have occasionally been observed when uploading
     classes with arrays such as char[][] via loadjava. [Bug 1094935]
