Oracle8i SQLJ Developer's Guide and Reference Release 3 (8.1.7) Part Number A83723-01 |
Library | Service | Contents | Index

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

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index