Oracle8i SQLJ Developer's Guide and Reference
Release 8.1.5

A64684-01

Library

Product

Contents

Index

Prev  Chap Top Next

Advanced Translator Options

This section documents the syntax and functionality of the advanced flags and options you can specify in running SQLJ, as well as prefixes employed to pass options to the Java VM, Java compiler, or SQLJ profile customizer. These options allow you to exercise any of the specialized features of Oracle SQLJ. For options that can also be specified in a properties file (such as sqlj.properties), that syntax is noted as well (see "Properties Files for Option Settings" for more information).

Additional advanced options, intended specifically for situations where you are using alternative Java environments, are discussed in "Translator Support and Options for Alternative Environments". More basic command line flags and options are discussed in "Basic Translator Options".

Prefixes that Pass Option Settings to Other Executables

The following flags mark options to be passed to the Java interpreter, Java compiler, and SQLJ profile customizer:

Options to Pass to Java VM (-J)

The -J prefix, specified on the command line, marks options to be passed to the Java VM from which SQLJ was invoked. This prefix immediately precedes a Java VM option, with no spaces in between. After stripping off the -J prefix, the sqlj script passes the Java option to the VM.

For example:

-J-Duser.language=ja

After stripping the -J prefix, the sqlj script passes the -Duser.language argument as is to the VM. In the JDK, the flag -Duser.language=ja sets the system property user.language to the value ja (Japanese), but specific flags are dependent on the actual Java executable you are using and are not interpreted or acted upon by the sqlj script in any way.

You cannot pass options to the Java VM from a properties file because properties files are read after the VM is invoked.


Note:

It is not possible to use a properties file to pass options directly to the Java VM in which the SQLJ translator runs. It is possible, however, to use the SQLJ_OPTIONS environment variable for this purpose. See "SQLJ_OPTIONS Environment Variable for Option Settings". It is also possible (if applicable) to use a properties file to pass options to the VM in which the Java compiler runs. See "Options to Pass to Java Compiler (-C)" for information.  


Command-line syntax
-J-Java_option
Command-line example
-J-Duser.language=ja
Properties file syntax

n/a

Properties file example

n/a

Default value

n/a

Options to Pass to Java Compiler (-C)

The -C prefix marks options to pass to the Java compiler that is invoked from the sqlj script. This prefix immediately precedes a Java compiler option, with no spaces in between. After stripping off the -C prefix, the sqlj script passes the compiler option to the Java compiler (typically, but not necessarily, javac).

For example:

-C-nowarn

After stripping the -C prefix, the sqlj script passes the -nowarn argument as is to the compiler. The -nowarn flag is a javac option to suppress warning messages during compilation.

One Java compiler option, -classpath, is slightly modified when it is passed to the compiler. All other compiler options are passed without change. (Note that if you want the same CLASSPATH setting for the VM and compiler, then you can use the SQLJ -classpath option instead of -J-classpath and -C-classpath.)

Specify the CLASSPATH setting to the Java compiler using the following syntax:

-C-classpath=path

For example:

-C-classpath=/user/jdk/bin

The equals sign is necessary for SQLJ parsing but is automatically replaced with a space when the option is passed to the Java compiler. After the -C is stripped off and the equals sign is replaced, the option is passed to the compiler as follows:

-classpath /user/jdk/bin

If the Java compiler runs in its own Java VM, then you can pass options to that VM through the compiler. This is accomplished by prefixing the VM option with -C-J with no spaces between this prefix combination and the VM option.

For example:

-C-J-Duser.language=de

Observe the following in using the -C prefix:


Notes:

  • In the above -classpath discussion, the forward-slash (/) was used as the file separator. Be aware, however, that in specifying this or similar options you must use the file separator of your operating system, as specified in the file.separator system property of your Java VM.

  • If you specify compiler options but disable compilation (-compile=false), then the compiler options are silently ignored.

  • The compiler help option (-C-help, presuming your compiler supports a help option) can be specified only on the command line or in the SQLJ_OPTIONS variable, not in a properties file. As with the SQLJ -help option, no translation will be done. This is true even if you also specify files to process. (SQLJ generally assumes that you want help or you want translation, but not both.)

 

Command-line syntax
-C-Java_compiler_option
Command-line example
-C-nowarn
Properties file syntax
compile.Java_compiler_option
Properties file example
compile.nowarn
Default value

n/a

Options to Pass to Profile Customizer (-P)

During the customization phase, the sqlj script invokes a front-end customizer harness, which coordinates the customization and runs your particular customizer. The -P prefix marks options for customization, as follows:

The -P and -P-C prefixes immediately precede a customizer option, with no spaces in between. After stripping off the prefix, the sqlj script passes the customizer option as is to the profile customizer.

One use of the -P prefix is to override the default customizer determined by the SQLJ -default-customizer option, as follows:

-P-customizer=your_customizer_class

Example of generic option:

-P-backup

The -backup flag is a generic customizer option to backup the previous customization before generating a new one.

Here is an example of a vendor-specific customizer option (in this case, Oracle-specific):

-P-Csummary

The -summary flag is an Oracle customizer option that prints a summary of the customizations performed.


Notes:

  • Note that there is no hyphen between "-P-C" and a vendor-specific customizer option. With other prefixes and prefix combinations, there is a hyphen between the prefix and the option.

  • The customizer help option (-P-help) can be specified only on the command line or in the SQLJ_OPTIONS variable, not in a properties file. As with the SQLJ -help option, no translation will be done. This is true even if you also specify files to process. (SQLJ generally assumes that you want help or you want translation, but not both.)

  • If you specify customization options but turn off customization for .sqlj files (and have no .ser files on the command line), then the customization options are silently ignored.

 

For information about available generic and Oracle-specific customizer options, see "Customization Options and Choosing a Customizer".

Command-line syntax
-P-<C>profile_customizer_option
Command-line examples

     
-P-driver=oracle.jdbc.driver.OracleDriver
-P-Csummary
Properties file syntax
profile.<C>profile_customizer_option
Properties file example

     
profile.driver=oracle.jdbc.driver.OracleDriver
profile.Csummary
Default value

n/a

Flags for Special Processing

As mentioned above, .sqlj files are typically processed by the SQLJ translator, Java compiler, and SQLJ profile customizer. The following flags limit this processing, directing the SQLJ startup script to skip the indicated process:

In addition, the following flag directs special processing of the SQLJ profile after customization:

Compilation Flag (-compile)

The -compile flag enables or disables processing of .java files by the compiler. This applies both to generated .java files and to .java files specified on the command line. This flag is useful, for example, if you want to compile .java files later using a compiler other than javac. The flag is true by default; setting it to false disables compilation.

When you process a .sqlj file with -compile=false, you are responsible for compiling and customizing it later as necessary.


Notes:

  • Setting -compile=false also implicitly sets -profile=false. In other words, whenever -compile is false, both compilation and customization are skipped. If you set -compile=false and -profile=true, then your -profile setting is ignored.

  • There are situations where it is sensible for -compile to be set to false even when .java files are specified on the command line. You might do this, for example, if you are translating a .sqlj file and need to specify one or more .java files for type resolution during translation but want to compile all of your .java files later using a particular compiler. (An example of a situation where you must supply .java files for type resolution is if you are accessing Oracle8i objects in your SQLJ application and using the Oracle JPublisher utility to map these objects to custom Java types. The .java files produced by JPublisher must be supplied to the SQLJ translator for type resolution during translation. See "Compiling Custom Java Classes" for more information.)

 

Command-line syntax
-compile=true/false
Command-line example
-compile=false
Properties file syntax
sqlj.compile=true/false
Properties file example
sqlj.compile=false
Default value

true (enabled)

Profile Customization Flag (-profile)

The -profile flag enables or disables processing of generated profile (.ser) files by the SQLJ profile customizer. However, this only applies to .ser files generated by the SQLJ translator from .sqlj files that you specify on the current command line; it does not apply to previously generated .ser files (or to .jar files) that you specify on the command line. The flag is true by default; setting it to false disables customization.

This option behaves differently than the -compile option for files specified on the command line. Any .ser and .jar files specified on the command line are still customized if -profile=false; however, .java files specified on the command line are not compiled if -compile=false. The reason for this is that there are other operations, such as line mapping, that you might want to perform on a .java file. There are, however, no other operations that can be performed on a .ser or .jar file specified on the command line.

When you process a .sqlj file with -profile=false, you are responsible for customizing it later, as necessary.


Note:

Setting -compile=false also implicitly sets -profile=false. In other words, whenever -compile is false, both compilation and customization are skipped. If you set -compile=false and -profile=true, then your -profile setting is ignored.  


Command-line syntax
-profile=true/false
Command-line example
-profile=false
Properties file syntax
sqlj.profile=true/false
Properties file example
sqlj.profile=false
Default value

true (enabled)

Conversion of .ser File to .class File (-ser2class)

The -ser2class flag instructs SQLJ to convert generated .ser files to .class files. This is necessary if you are using SQLJ to create an applet that will be run from a browser that does not support resource file names with the .ser suffix. (This is true of Netscape Navigator 4.x, for example.)

This also simplifies the naming of schema objects for your profiles in situations where you are translating a SQLJ program on a client and then loading classes and resource files into the server. (This is discussed in "Naming of Class and Resource Schema Objects".)

The conversion is performed after profile customization so that it includes your customizations.

The base names of converted files are the same as for the original files; the only difference in the file name is .ser being replaced by .class. For example:

Foo_SJProfile0.ser

is converted to:

Foo_SJProfile0.class


Notes:

  • The original .ser file is not saved.

  • Once a profile has been converted to a .class file, it cannot be further customized. You would have to rerun SQLJ and recreate the profile.

  • Where encoding is necessary, the -ser2class option always uses 8859_1 encoding, ignoring the SQLJ -encoding setting.

 

Command-line syntax
-ser2class=true/false
Command-line example
-ser2class=true
Properties file syntax
sqlj.ser2class=true/false
Properties file example
sqlj.ser2class=false
Default value
false

Semantics-Checking Options

The following options specify characteristics of online and offline semantics-checking:

Discussion of these options is preceded by a discussion of OracleChecker--the default front-end class for semantics-checking--and an introduction to the Oracle semantics-checkers.

Semantics-Checkers and the OracleChecker Front End (default checker)

The default checker (for both online and offline checking) is oracle.sqlj.checker.OracleChecker. This class acts as a front end and runs the appropriate semantics-checker, depending on your environment and whether you choose offline or online checking.

For Oracle databases and JDBC drivers, there are the following categories of checkers (for both online and offline checking):

The Oracle80 and Oracle7 checkers are incompatible with the Oracle8i JDBC drivers, and the Oracle8 and Oracle8To7 checkers are incompatible with the Oracle 8.0.5 and Oracle 7.3.4 JDBC drivers. The Oracle8To7 checkers were created so that there is a way to use an Oracle8i JDBC driver and check against an Oracle 7.3.4 subset of types.

Online Checking with Oracle Database and JDBC Driver

If you are using an Oracle database and Oracle JDBC driver with online checking, then OracleChecker will choose a checker based on the lower of your database version and JDBC driver version. Table 8-3 summarizes the choices for the possible combinations of database version and driver version, and also notes any other Oracle checkers that would be legal.

Table 8-3 Oracle Online Semantics-Checkers Chosen by OracleChecker
Database Version  JDBC Version  Online Checker  Other Legal Checkers 

Oracle8i or 8.0.5  

Oracle8i  

Oracle8JdbcChecker  

Oracle8To7JdbcChecker  

Oracle8i or 8.0.5  

Oracle 8.0.5  

Oracle80JdbcChecker  

Oracle7JdbcChecker  

Oracle8i or 8.0.5  

Oracle 7.3.4  

Oracle7JdbcChecker  

none  

Oracle 7.3.4  

Oracle8i  

Oracle8To7JdbcChecker  

none  

Oracle 7.3.4  

Oracle 8.0.5  

Oracle7JdbcChecker  

none  

Oracle 7.3.4  

Oracle 7.3.4  

Oracle7JdbcChecker  

none  

Offline Checking with Oracle JDBC Driver

If you are using an Oracle JDBC driver with offline checking, then OracleChecker will choose a checker based on your JDBC driver version. Table 8-4 summarizes the possible choices. (Note that there is an Oracle8To7OfflineChecker but it can only be used by selecting it manually.)

Table 8-4 Oracle Offline Semantics-Checkers Chosen by OracleChecker
JDBC Version  Offline Checker  Other Legal Checkers 

Oracle8i  

Oracle8OfflineChecker  

Oracle8To7OfflineChecker  

Oracle 8.0.5  

Oracle80OfflineChecker  

Oracle7OfflineChecker  

Oracle 7.3.4  

Oracle7OfflineChecker  

none  

Not Using Oracle Database and JDBC Driver

If OracleChecker detects that you do not use an Oracle JDBC driver, then it runs one of the following checkers:

Offline Semantics-Checker (-offline)

The -offline option specifies a Java class that implements the semantics-checking component of SQLJ for offline checking. With offline checking, there is no connection to the database--only SQL syntax and usage of Java types is checked. (For information about what offline and online semantics-checkers accomplish and how they function, see "Semantics-Checking".)

Note that offline checking is neither enabled nor disabled by the -offline option. Offline checking runs only when online checking does not (either because online checking is not enabled or because the database connection cannot be established).

You can specify different offline checkers for different connection contexts, with a limit of one checker per context (do not list multiple offline checkers for one connection context).

The default OracleChecker, a front-end class discussed in "Semantics-Checkers and the OracleChecker Front End (default checker)", will serve your needs unless you want to specify a particular checker which would not be chosen by OracleChecker. For example, you may run offline checking on a machine with an Oracle 8.0 JDBC driver but your application (or at least statements using a particular connection context class) will run against an Oracle 7.3 database. In this case you will want to check these statements using the Oracle7 checker.

The following example shows how to select the Oracle7 offline checker for a particular connection context (CtxClass):

-offline@CtxClass=oracle.sqlj.checker.Oracle7OfflineChecker

This results in SQLJ using oracle.sqlj.checker.Oracle7OfflineChecker for offline checking of any of your SQLJ executable statements that specify a connection object that is an instance of CtxClass.

The CtxClass connection context class must be declared in your source code or previously compiled into a .class file. (See "Connection Contexts" for more information.)

Use the -offline option separately for each connection context offline checker you want to specify; these settings have no influence on each other. For example:

-offline@CtxClass2=oracle.sqlj.checker.Oracle7OfflineChecker
-offline@CtxClass3=sqlj.semantics.OfflineChecker

To specify the offline checker for the default connection context and any other connection contexts for which you do not specify an offline checker:

-offline=oracle.sqlj.checker.Oracle7OfflineChecker

Any connection context without an offline checker setting uses the offline checker setting of the default connection context, presuming an offline checker has been set for the default context.

Command-line syntax
-offline<@conn_context_class>=checker_class
Command-line examples

     
-offline=oracle.sqlj.checker.Oracle80OfflineChecker
-offline@Context=oracle.sqlj.checker.Oracle80OfflineChecker
Properties file syntax
sqlj.offline<@conn_context_class>=checker_class
Properties file examples

     
sqlj.offline=oracle.sqlj.checker.Oracle80OfflineChecker
sqlj.offline@Context=oracle.sqlj.checker.Oracle80OfflineChecker
Default value
oracle.sqlj.checker.OracleChecker

Online Semantics-Checker (-online)

The -online option specifies a Java class or list of classes that implement the online semantics-checking component of SQLJ. This involves connecting to a database.

Remember that online checking is not enabled by the -online option--you must enable it through the -user option. The -password, -url, and -driver options must be set appropriately as well. (For information about what offline and online semantics-checkers accomplish and how they function, see "Semantics-Checking".)

You can specify different online checkers for different connection contexts and you can list multiple checkers (separated by commas) for any given context. In cases where multiple checkers are listed for a single context, SQLJ uses the first checker (reading from left to right in the list) that accepts the database connection that was established for online checking. (At analysis time, a connection is passed to each online checker, and the checker reports whether or not the database is recognized.)

The default OracleChecker, a front-end class discussed in "Semantics-Checkers and the OracleChecker Front End (default checker)", will serve your needs unless you want to specify a particular checker that would not be chosen by OracleChecker. For example, you may run online checking on a machine with an Oracle 8.0 database and JDBC driver, but your application (or at least statements using a particular connection context class) will eventually run against an Oracle 7.3 database. In this case you will want to check these statements using the Oracle7 checker.

The following example shows how to select the Oracle7 online checker for the DefaultContext class (and any other connection context classes without a specified setting):

-online=oracle.sqlj.checker.Oracle7JdbcChecker

To specify a list of drivers and allow the proper class to be selected depending on what kind of database is being accessed:

-online=oracle.sqlj.checker.Oracle7JdbcChecker,sqlj.semantics.JdbcChecker

With this specification, if connection is made to an Oracle database, then SQLJ uses oracle.sqlj.checker.Oracle7JdbcChecker. If connection is made to any other kind of database, then SQLJ uses the generic JdbcChecker. This is similar functionally to what the default OracleChecker does but ensures that you use an Oracle7 checker instead of an Oracle8 checker if you connect to an Oracle database.

To specify the online checker for a particular connection context (CtxClass):

-online@CtxClass=oracle.sqlj.checker.Oracle7JdbcChecker

This results in the use of oracle.sqlj.checker.Oracle7JdbcChecker for online checking of any of your SQLJ executable statements that specify a connection object that is an instance of CtxClass, presuming you enable online checking for CtxClass.

The CtxClass connection context class must be declared in your source code or previously compiled into a .class file. (See "Connection Contexts" for more information.)

Use the -online option separately for each connection context online checker you want to specify; these settings have no influence on each other:

-online@CtxClass2=oracle.sqlj.checker.Oracle80JdbcChecker
-online@CtxClass3=sqlj.semantics.JdbcChecker

Any connection context without an online checker setting uses the online checker setting of the default connection context, presuming you set an online checker for the default context.

Command-line syntax
-online<@conn_context_class>=checker_class(list)
Command-line examples

-online=oracle.sqlj.checker.Oracle80JdbcChecker
-online=oracle.sqlj.checker.Oracle80JdbcChecker,sqlj.semantics.JdbcChecker
-online@Context=oracle.sqlj.checker.Oracle80JdbcChecker
Properties file syntax
sqlj.online<@conn_context_class>=checker_class(list)
Properties file examples

sqlj.online=oracle.sqlj.checker.Oracle80JdbcChecker
sqlj.online=oracle.sqlj.checker.Oracle80JdbcChecker,sqlj.semantics.JdbcChecker
sqlj.online@Context=oracle.sqlj.checker.Oracle80JdbcChecker
Default value
oracle.sqlj.checker.OracleChecker

Caching of Online Semantics-Checker Results (-cache)

Use the -cache option to enable caching of the results generated by the online checker. This avoids additional database connections during subsequent SQLJ translation runs. The analysis results are cached in a file SQLChecker.cache that is placed in your current directory.

The cache contains serialized representations of all SQL statements successfully translated (translated without error or warning messages), including all statement parameters, return types, translator settings, and modes.

The cache is cumulative and continues to grow through successive invocations of the SQLJ translator. Remove the SQLChecker.cache file to empty the cache.

Command-line syntax
-cache=true/false
Command-line example
-cache=true
Properties file syntax
sqlj.cache=true/false
Properties file example
sqlj.cache=false
Default value
false



Prev

Top

Next
Oracle
Copyright © 1999 Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index