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 JVM, 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:

• -J (mark options for Java interpreter)

• -C (mark options for Java compiler)

• -P (mark options for profile customizer)

Options to Pass to the Java Virtual Machine (-J)

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

For example:

-J-Duser.language=ja

After stripping the -J prefix, the sqlj script passes the -Duser.language argument as is to the JVM. In the Sun Microsystems 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 JVM from a properties file, because properties files are read after the JVM is invoked.

Notes: It is not possible to use a properties file to pass options directly to the JVM 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 JVM in which the Java compiler runs. See "Options to Pass to the Java Compiler (-C)" for information. The JVM file.encoding setting does not apply to Java properties files--sqlj.properties and connect.properties, for example. Properties files always use the encoding 8859_1. This is a feature of Java in general, not SQLJ in particular. You can, however, use Unicode escape sequences in a properties file. (You can use the native2ascii utility to determine escape sequences--see "Using native2ascii for Source File Encoding".)

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 the Java Compiler (-C)

The -C prefix marks options to pass to the Java compiler 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 JVM 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 JVM, then you can pass options to that JVM through the compiler. Accomplish this by prefixing the JVM option with -C-J with no spaces between this prefix combination and the option.

For example:

-C-J-Duser.language=de

Observe the following restrictions in using the -C prefix:

• Do not use -C-encoding to specify encoding of .java files processed by the Java compiler. Instead, use the SQLJ -encoding option, which specifies encoding of .sqlj files processed by SQLJ and .java files generated by SQLJ, and is also passed to the compiler. This ensures that .sqlj files and .java files receive the same encoding. (For information about the -encoding option, see "Encoding for Input and Output Source Files (-encoding)".)

• Do not use -C-d to specify an output directory for .class files. Instead, use the SQLJ -d option, which specifies the output directory for generated profile (.ser) files and is also passed to the Java compiler. This will ensure that .class files and .ser files are in the same directory. (For information about the -d option, see "Output Directory for Generated .ser and .class Files (-d)".)

  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 JVM. 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 -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 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 the 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:

• Use the -P prefix by itself to pass generic options to the customizer harness that apply regardless of the customizer.

• Use the -P-C prefix to pass vendor-specific options to the particular customizer you are using.

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

• -compile

• -profile

The following flag instructs SQLJ to convert profiles from serialized resource (.ser) files to class files after customization:

• -ser2class

The following flag instructs SQLJ type resolution, in certain circumstances, to examine source files as well as class files or files specified on the SQLJ command line:

• -checksource

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 must be accessed for type resolution. You might do this, for example, if you are translating a .sqlj file, the translator will need one or more .java files for type resolution during translation, but you want to compile all your .java files later using a particular compiler. (An example of a situation where .java files must be accessed for type resolution is if you are using 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 available 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 (compile)

Profile Customization Flag (-profile)

The -profile flag enables or disables processing of generated profile (.ser) files by the SQLJ profile customizer. However, this applies only 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 from 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 you might want other operations, such as line mapping, to be performed 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.

Notes: Set this option to false if you do not want your application to require the Oracle SQLJ runtime and an Oracle JDBC driver when it runs. (Or specify a non-default customizer, using the -default-customizer option.) If no customization is performed, then the generic SQLJ runtime will be used when your application runs. 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 (customize)

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. Loaded class schema objects have a simpler naming convention than loaded resource schema objects. (This is discussed in "Loaded 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 identical to those of 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 delete the .class file and rerun SQLJ to 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

Source Check for Type Resolution (-checksource)

Normally the SQLJ type resolution process examines only class files in the CLASSPATH, and class or source files specified on the SQLJ command line. The -checksource flag instructs SQLJ to also examine source files in the CLASSPATH under the following circumstances:

• if a class file cannot be found for a required class, but a source file can be found

• if a source file has a more recent modification date than its corresponding class file

  Note: This applies only to Java types that appear in #sql statements, not elsewhere in your Java code. Therefore, you should always explicitly provide the names of any required .sqlj files on the SQLJ command line.

Command-line syntax

-checksource=true/false

Command-line example

-checksource=true

Properties file syntax

sqlj.checksource=true/false

Properties file example

sqlj.checksource=false

Default value

true

Semantics-Checking Options

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

• -offline

• -online

• -cache

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 is oracle.sqlj.checker.OracleChecker (for both online and offline checking). 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):

• Oracle8 checkers for Oracle8i types (as used in Oracle8i JDBC)

• Oracle80 checkers for Oracle 8.0.x types (as used in Oracle 8.0.x JDBC)

• Oracle7 checkers for Oracle 7.3.x types (as used in Oracle 7.3.x or 8.0.x JDBC)

• Oracle8To7 checkers for using an Oracle8i JDBC driver, but only with the subset of types that are compatible with an Oracle 7.3.x database.

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.x and Oracle 7.3.x 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.x 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	Chosen Online Checker	Other Legal Online Checkers
Oracle8i or 8.0.x	Oracle8i	Oracle8JdbcChecker	Oracle8To7JdbcChecker
Oracle8i or 8.0.x	Oracle 8.0.x	Oracle80JdbcChecker	Oracle7JdbcChecker
Oracle8i or 8.0.x	Oracle 7.3.x	Oracle7JdbcChecker	none
Oracle 7.3.x	Oracle8i	Oracle8To7JdbcChecker	none
Oracle 7.3.x	Oracle 8.0.x	Oracle7JdbcChecker	none
Oracle 7.3.x	Oracle 7.3.x	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 be used only by selecting it manually.)

Table 8-4 Oracle Offline Semantics-Checkers Chosen by OracleChecker

JDBC Version	Chosen Offline Checker	Other Legal Offline Checkers
Oracle8i	Oracle8OfflineChecker	Oracle8To7OfflineChecker
Oracle 8.0.x	Oracle80OfflineChecker	Oracle7OfflineChecker
Oracle 7.3.x	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:

• sqlj.semantics.OfflineChecker if online checking is not enabled

• sqlj.semantics.JdbcChecker if online checking is enabled

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 that would not be chosen by OracleChecker. For example, you might 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 a CtxClass instance.

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 established for online checking. (At analysis time, a connection is passed to each online checker, and the checker reports whether 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 might 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 the oracle.sqlj.checker.Oracle7JdbcChecker semantics-checker. If connection is made to any other kind of database, then SQLJ uses the generic sqlj.semantics.JdbcChecker semantics-checker. 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. Delete 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

---