Release 8.1.5
A64684-01
 Library |
 Product |
 Contents |
 Index |
| Oracle8i SQLJ Developer's Guide and Reference Release 8.1.5 A64684-01 |
|
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".
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)
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 |
-J-Java_option
-J-Duser.language=ja
n/a
n/a
n/a
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:
-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)".)
-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)".)
-C-Java_compiler_option
-C-nowarn
compile.Java_compiler_option
compile.nowarn
n/a
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:
-P prefix by itself to pass generic options to the customizer harness that apply regardless of the customizer.
-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.
For information about available generic and Oracle-specific customizer options, see "Customization Options and Choosing a Customizer".
-P-<C>profile_customizer_option
-P-driver=oracle.jdbc.driver.OracleDriver -P-Csummary
profile.<C>profile_customizer_option
profile.driver=oracle.jdbc.driver.OracleDriver profile.Csummary
n/a
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:
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:
|
-compile=true/false
-compile=false
sqlj.compile=true/false
sqlj.compile=false
true (enabled)
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.
-profile=true/false
-profile=false
sqlj.profile=true/false
sqlj.profile=false
true (enabled)
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
-ser2class=true/false
-ser2class=true
sqlj.ser2class=true/false
sqlj.ser2class=false
false
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.
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.
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.
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.)
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
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.
-offline<@conn_context_class>=checker_class
-offline=oracle.sqlj.checker.Oracle80OfflineChecker -offline@Context=oracle.sqlj.checker.Oracle80OfflineChecker
sqlj.offline<@conn_context_class>=checker_class
sqlj.offline=oracle.sqlj.checker.Oracle80OfflineChecker sqlj.offline@Context=oracle.sqlj.checker.Oracle80OfflineChecker
oracle.sqlj.checker.OracleChecker
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.
-online<@conn_context_class>=checker_class(list)
-online=oracle.sqlj.checker.Oracle80JdbcChecker
-online=oracle.sqlj.checker.Oracle80JdbcChecker,sqlj.semantics.JdbcChecker
-online@Context=oracle.sqlj.checker.Oracle80JdbcChecker
sqlj.online<@conn_context_class>=checker_class(list)
sqlj.online=oracle.sqlj.checker.Oracle80JdbcChecker
sqlj.online=oracle.sqlj.checker.Oracle80JdbcChecker,sqlj.semantics.JdbcChecker
sqlj.online@Context=oracle.sqlj.checker.Oracle80JdbcChecker
oracle.sqlj.checker.OracleChecker
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.
-cache=true/false
-cache=true
sqlj.cache=true/false
sqlj.cache=false
false
