(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

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:

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:

• [$ORACLE_HOME/sqlj/lib/runtime11.zip] - runtime for JDK 1.1, Oracle 8.1.7 JDBC
• [$ORACLE_HOME/sqlj/lib/runtime12.zip] - runtime for JDK 1.2, Oracle 8.1.7 JDBC
• [$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].

• see [$ORACLE_HOME/sqlj/demo/README.txt] for more information,
• additional examples using object types [$ORACLE_HOME/sqlj/demo/Objects],
• examples showing JDBC 2.0-derived features from the SQLJ ISO standard [$ORACLE_HOME/sqlj/demo/jdbc20],
• examples using Java stored procedures [$ORACLE_HOME/sqlj/demo/server],
• examples showing SQLJ programs in applets [$ORACLE_HOME/sqlj/demo/applets],
• 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].

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:

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.

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

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)

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).
• 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.
• support for scrollable iterators (both, positional and named)
• association of connection contexts with DataSources
• control of batching and row prefetch through the ExecutionContext
• 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

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:

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

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.

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.

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.

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:

• your source files (often this is . - the current directory)
• the Oracle JDBC driver classes111.zip or classes12.zip
• the SQLJ translator translator.zip
• 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.

• 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

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

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.

• 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

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.

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

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

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.

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

• Remove $ORACLE_HOME/lib/lclasses11.zip and [JDK Home]/lib/classes.zip from your CLASSPATH.
• Do not use JDK 1.1.6. This problem has not been observed under other JDK versions.
• 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].

• When using JDK1.1.3, the following encodings work with javac but not sqlj:

Cp1125, GBK, ISO2022CN, ISO2022CN_CNS, ISO2022CN_GB, ISO2022KR, JIS0208
• When using JDK1.1.6, the following encodings work with javac but not sqlj:

Cp1125, ISO2022CN, ISO2022CN_CNS, ISO2022CN_GB, JIS0208.
• 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

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

• 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]

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.

• 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]