Release 1 (9.0.1)
Part Number A90212-01
 Home |
 Solution Area |
 Contents |
 Index |
| Oracle9i SQLJ Developer's Guide and Reference Release 1 (9.0.1) Part Number A90212-01 |
|
Once you have written your source code, you must translate it using the SQLJ translator. This chapter discusses the SQLJ translator command line, options, and properties files.
The following topics are discussed:
This section discusses general command-line syntax for the script sqlj that you use to run the SQLJ translator, and lists all the options available. It then discusses SQLJ properties files, which you can use instead of the command line to set most options, and the SQLJ_OPTIONS environment variable, which you can use in addition to or instead of the command line for setting options.
For detailed information about settings for basic options, see "Basic Translator Options".
For information about more advanced options, see "Advanced Translator Options" and "Translator Support and Options for Alternative Environments".
The sqlj script invokes a Java virtual machine (JVM) and passes the class name of the SQLJ translator (sqlj.tools.Sqlj) to the JVM. The JVM invokes the translator and performs operations such as parsing the command line and properties files. For simplicity, running the script is referred to as "running SQLJ", and its command line is referred to as the "SQLJ command line".
This is the typical general syntax for the command line:
sqlj <optionlist> filelist
The option list is a list of SQLJ option settings, separated by spaces. There are also prefixes to mark options to pass to other executable programs.
The file list is the list of files, separated by spaces, to be processed by the SQLJ translator (they can be .sqlj, .java, .ser, or .jar files, as explained in "Command-Line Syntax and Operations"). The * wildcard entry can be used in file names. For example, Foo*.sqlj would find Foo1.sqlj, Foo2.sqlj, and Foobar.sqlj.
Do not include .class files in the file list, but do be sure that your classpath is set so that the SQLJ translator can find any classes it must have for type resolution of variables in your SQLJ source files.
If the -checksource flag is enabled (its default setting), the SQLJ translator can also find classes it needs in uncompiled .java files in the classpath. See "Source Check for Type Resolution (-checksource)".
|
Notes:
|
This section discusses options supported by the SQLJ translator. Boolean options are referred to as flags. Also listed are prefixes, used to pass options to the JVM, which the SQLJ script invokes, and to the Java compiler and SQLJ profile customizer, which the JVM invokes.
Use an equals sign (=) to specify option and flag settings, although for simplicity you do not have to specify =true to turn on a flag--typing the flag name alone will suffice. You must, however, specify =false to turn a flag off--a flag will not toggle from its previous value. For example:
-linemap=true or just -linemap to enable line-mapping
-linemap=false to disable line-mapping
loadjava utility.
javac options are recognized directly by SQLJ if specified on the command line, as indicated in Table 8-1. All these are passed to your Java compiler (presumably javac), and some also affect SQLJ operation.
SQLJ_OPTIONS environment variable can be used in addition to, or instead of, the command line for setting options. See "SQLJ_OPTIONS Environment Variable for Option Settings".
true or false, but they can also be enabled/disabled by setting them to yes/no, on/off, or 1/0.
For an example and discussion of command-line syntax and operations, see "Command-Line Syntax and Operations".
Table 8-1 below lists options supported by the SQLJ translator, categorized as follows:
javac options that SQLJ supports and that are also passed directly to the Java compiler (presumably javac). These options are discussed in "Options for javac Compatibility".
For compatibility with the loadjava utility used to load Java and SQLJ applications into Oracle9i, the following alternative syntax is recognized for some options when specified on the command line (this is also noted in Table 8-1 above):
-e (equivalent to -encoding)
-h (equivalent to -help)
-p (equivalent to -password)
-u (equivalent to -user)
-v (for verbose message output; equivalent to -status)
To maintain full consistency with loadjava syntax, you can use a space instead of "=" in setting these options, as in the following example:
-u scott/tiger -v -e SJIS
For general information about the loadjava utility, see the Oracle9i Java Tools Reference.
For compatibility with javac, the Java compiler supplied with the Sun Microsystems JDK, the following javac options are accepted directly by SQLJ without the -C prefix if specified on the command line. Some also serve as SQLJ options; some are not SQLJ options per se, but also set SQLJ options; some affect javac only. This is also indicated in Table 8-1 above. Refer to your javac documentation for information about javac option settings and functionality.
-classpath (also a SQLJ option; sets the classpath for both javac and the JVM)
See "Classpath for Java Virtual Machine and Compiler (-classpath)".
-d (also a SQLJ option; sets the output directory for .class files and SQLJ profile files)
See "Output Directory for Generated .ser and .class Files (-d)".
-depend (javac option only; compiles out-of-date files recursively; also enables the -checksource option)
-encoding (also a SQLJ option; sets encoding for both SQLJ and javac)
See "Encoding for Input and Output Source Files (-encoding)".
-g (generates javac debugging information; also sets SQLJ -linemap=true)
-nowarn (instructs javac to generate no warnings; also sets SQLJ -warn=none)
-O (instructs javac to optimize; also sets SQLJ -linemap=false)
-verbose (instructs javac to output real-time status messages; also sets SQLJ -status=true)
Profile customizer options--options for the customizer harness front end, the default Oracle customizer, and special customizers for debugging and deployment-time semantics-checking--are documented in "Customization Options and Choosing a Customizer".
The general sequence of events triggered by running the script sqlj was discussed in "Translation Steps". This section will add some operational details to that discussion, as part of this overview of the command line.
Recall the typical general syntax for the command line:
sqlj <optionlist> filelist
When the sqlj script invokes a JVM, it passes all of its command-line arguments to the JVM, which later passes them elsewhere (such as to the Java compiler or profile customizer) as appropriate.
Option list arguments are used in the following ways:
-J, -C, or -P prefixes are SQLJ options and are passed to the SQLJ translator as the JVM invokes it.
-J prefix are JVM options and are used by the JVM directly. Such options must be specified on the command line or in the SQLJ_OPTIONS environment variable.
-C prefix are Java compiler options and are passed to the compiler as the JVM invokes it.
Note that three SQLJ options have the same name as Java compiler options and, if specified, are automatically passed to the Java compiler, as well as being used by SQLJ:
-d setting is used by SQLJ to specify the output directory for its generated profile files and is also passed to the compiler, which uses it to specify the output directory for its generated .class files.
-encoding setting is used by SQLJ in reading .sqlj files and generating .java files and is also passed to the Java compiler (unless the -compiler-encoding-flag is off), which uses it in reading .java files.
-classpath setting is passed by SQLJ to both the Java compiler and the JVM to set the classpath for both. It must be specified on the command line or in the SQLJ_OPTIONS environment variable.
Do not use the -C prefix to specify the -d or -encoding compiler options. Note that this also means that SQLJ and the compiler use the same settings for -d and -encoding.
You must use the -C prefix (and the -J prefix) for -classpath if you want to set different classpath values for the Java compiler and for the JVM that runs SQLJ.
-P prefix are SQLJ profile customizer options and are passed to the customizer as the JVM invokes it.
Any profile customization other than what SQLJ performs automatically is considered an advanced feature and is covered in Chapter 10, "Profiles and Customization".
The SQLJ front end parses the file list, processes wildcard characters, and expands file names. By default, files are processed as follows:
.sqlj files are processed by the SQLJ translator, Java compiler, and SQLJ profile customizer.
.java files are processed by the Java compiler and are also used by the SQLJ translator for type resolution.
.ser profiles and .jar files are processed only by the profile customizer.
Note that you can specify .sqlj files together with .java files on the command line, or you can specify .ser files together with .jar files, but you cannot mix the two categories. (See "Use of JAR Files for Profiles" for details about how .jar files are processed.)
If you have .sqlj files and .java files with interdependencies (each requiring access to code in the others), then enter them all on the command line for a single execution of SQLJ. You cannot specify them for separate executions of SQLJ, because then SQLJ would be unable to resolve all the types.
|
Note:
As an alternative to entering |
The SQLJ translator takes steps to try to prevent having multiple source files define the same class in the same location. If your command-line file list includes multiple references to the same .sqlj or .java file, all but the first reference are discarded from the command line. In addition, if you list a .java file and .sqlj file with the same base name and in the same location without using the -dir option, only the .sqlj file is processed. This processing also applies to wild-card file name characters.
Consider the following command-line examples, presuming that your current directory is /myhome/mypackage, which contains the files Foo.sqlj and Foo.java:
sqlj Foo.sqlj /myhome/mypackage/Foo.sqlj
These both refer to the same file, so the translator discards /myhome/mypackage/Foo.sqlj from the command line.
sqlj Foo.sqlj Foo.java
The translator discards Foo.java from the command line. Otherwise, this command line would result in the translator both writing to and reading from Foo.java in the same execution.
sqlj Foo.*
Again, the translator discards Foo.java from the command line. Otherwise, the translator would find both Foo.sqlj and Foo.java, which again would cause it to both write to and read from Foo.java in the same execution.
sqlj -dir=outdir -d=outclasses Foo.sqlj Foo.java
This is okay, because the generated Foo.java will be in the outdir subdirectory, while the Foo.java being read is in the /myhome/mypackage directory. Presuming that Foo.java and Foo.sqlj define classes in different packages, the .class files created by Java compilation will be placed in different subdirectories under the outclasses directory hierarchy.
This processing of the command line means that you can, for example, type the following command and have it execute without difficulty (with file references being automatically discarded as necessary):
sqlj *.sqlj *.java
This is convenient in many situations.
Below is a sample command line. This example uses some advanced concepts more fully explained later in this chapter, but is presented in the interest of showing a complete example of command-line syntax.
sqlj -J-Duser.language=ja -warn=none -J-prof -encoding=SJIS *Bar.sqlj Foo*.java
The sqlj script invokes a JVM, passes it the class name of the SQLJ translator, then passes it the command-line arguments (which later passes them to the translator, compiler, and customizer, as appropriate). If there are any options for the JVM, as designated by -J, the script passes them to the JVM ahead of the translator class file name (just as you would type Java options prior to typing the class file name if you were invoking Java by hand).
After these steps are completed, the results are equivalent to the user having typed in the next example (presuming SushiBar.sqlj, DiveBar.sqlj, FooBar.java, and FooBaz.java were all in the current directory).
java -Duser.language=ja -prof sqlj.tools.Sqlj -warn=none -encoding=SJIS SushiBar.sqlj DiveBar.sqlj FooBar.java FooBaz.java
(This is one wrap-around command line.)
For more information about how JVM options are handled, see "Options to Pass to the Java Virtual Machine (-J)".
You can use the SQLJ -n option (or, alternatively, -vm=echo) to echo the command line that the sqlj script would construct and pass to the SQLJ translator, without executing it. This includes settings in the SQLJ_OPTIONS environment variable as well as on the command line, but does not include settings in properties files.
For more information, see "Command Line Echo without Execution (-n)".
You can use properties files, instead of the command line, to set options for the SQLJ translator, Java compiler, and SQLJ profile customizer.
In addition, if your Java compiler will be running in a separate JVM and you want to specify options to this JVM regarding operation of the compiler, then you can use properties files to supply such options. Such options are passed to the JVM at the time the compiler is run, after the SQLJ translation step. (It is more typical, however, to pass options to the compiler's JVM by using the command-line -C-J prefix.)
You cannot use properties files to set the following SQLJ options, flags, and prefixes:
-classpath
-help, -help-long, -help-alias, -C-help, -P-help
-J
-n
-passes
-props
-version, -version-long
-vm
It is not possible to use properties files to specify options to the JVM, for example, because properties files are read after the JVM is invoked.
You also cannot do the following in properties files:
javac options that are supported as SQLJ options (-depend, -g, -nowarn, -O, -verbose)
However, as discussed in "Properties File Syntax" below, you can use the "compile." prefix to set javac options directly . For example:
compile.depend compile.g
loadjava (-e, -h, -p, -u, -v)
Discussion of SQLJ properties files applies only to client-side SQLJ, not server-side SQLJ. There is a different mechanism for specifying options to SQLJ in the server. For information, see "Option Support in the Server Embedded Translator".
Notes:
Option settings in a properties file are placed one per line. Lines with SQLJ options, compiler options, and customizer options can be interspersed. (They are parsed by the SQLJ front end and processed appropriately.)
Syntax for the different kinds of options is as follows:
sqlj. (including the period) instead of an initial hyphen; only options that start with sqlj. are passed to the SQLJ translator. For example:
sqlj.warn=none sqlj.linemap=true
compile. (including the period) instead of -C-; only options that start with compile. are passed to the Java compiler. For example:
compile.verbose
(The Java compiler -verbose option outputs status messages during the compile.)
profile. (including the period) instead of -P-; only options that start with profile. are passed to the profile customizer. For example:
profile.backup
(The profile customizer backup option saves a copy of the previous profile.)
You can also specify options to a particular customizer by using profile.C as follows:
profile.Csummary
(For the Oracle customizer, the summary option displays a summary of the Oracle features used.)
Any profile customization other than the default Oracle customization is considered an advanced feature and is covered in Chapter 10, "Profiles and Customization".
#). For example:
# Comment line.
As on the command line, a flag can be enabled/disabled in a properties file with =true/=false, =on/=off, =1/=0, or =yes/=no. A flag can also be enabled simply by entering it without a setting, such as the following:
sqlj.linemap
The following are sample properties file entries:
# Set user and JDBC driver sqlj.user=scott sqlj.driver=oracle.jdbc.OracleDriver # Turn on the compiler verbose option compile.verbose
These entries are equivalent to having the following on the SQLJ command line:
sqlj -user=scott -driver=oracle.jdbc.OracleDriver -C-verbose
Following is a sample properties file that specifies settings for a connection context class SourceContext that you declared:
# JDBC driver sqlj.driver=oracle.jdbc.OracleDriver # Oracle 8.0.4 on spock.natdecsys.com sqlj.user@SourceContext=sde sqlj.password@SourceContext=fornow sqlj.url@SourceContext=jdbc:oracle:thin:@207.67.155.3:1521:nds # Warning settings sqlj.warn=all # Cache sqlj.cache=on
Regardless of whether a properties file is specified in the SQLJ command line, the SQLJ front end looks for files named "sqlj.properties". It looks for them in the Java home directory, the user home directory, and the current directory, in that order. It processes each sqlj.properties file it finds, overriding previously set options as it encounters new ones. Thus, options set in the sqlj.properties file in the current directory override those set in the sqlj.properties file in the user home directory or Java home directory.
Also see "Order of Precedence of Option Settings".
Oracle SQLJ supports use of an environment variable called SQLJ_OPTIONS as an alternative to the command line for setting SQLJ options. Any option referred to as "command-line only", meaning it cannot be set in a properties file, can also be set using the SQLJ_OPTIONS variable.
You can use the SQLJ_OPTIONS variable to set any SQLJ option, but it is intended especially for option settings to be passed to the JVM. And it is particularly useful for command-line-only options, such as -classpath, that you use repeatedly with the same setting.
Following is an example of a SQLJ_OPTIONS setting:
-vm=jview -J-verbose
When you use SQLJ_OPTIONS, SQLJ effectively inserts the SQLJ_OPTIONS settings, in order, at the beginning of the SQLJ command line, prior to any other command-line option settings.
SQLJ takes option settings in the following order. At each step, it overrides any previous settings for any given option.
sqlj.properties file in the Java home directory; if it finds one, it sets options as specified there.
sqlj.properties file in the user home directory; if it finds one, it sets options as specified there.
sqlj.properties file in the current directory; if it finds one, it sets options as specified there.
SQLJ_OPTIONS environment variable and effectively prepends them to the beginning of the command line. It sets options as specified in SQLJ_OPTIONS.
-props option and sets options as specified there.
Presume SQLJ is run as follows:
sqlj -user=scott -props=myprops.properties -dir=/home/java
And presume the file myprops.properties is in the current directory and contains the following entries:
sqlj.user=tony sqlj.dir=/home/myjava
These settings are processed as if they were inserted into the command line where the -props option was specified. Therefore, the tony entry takes precedence over the scott entry for the user option, but the /home/java entry takes precedence over the /home/myjava entry for the dir option.
This section documents the syntax and functionality of the basic flags and options you can specify in running SQLJ. These options allow you to run in a fairly standard mode of operation. 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".)
More advanced command-line flags and options are discussed in "Advanced Translator Options" and "Translator Support and Options for Alternative Environments".
The following basic options can be specified only on the SQLJ command line or, equivalently, in the SQLJ_OPTIONS environment variable. They cannot be specified in properties files.
The command-line-only flags (the -help flags, -version flags, and -n) do not support =true syntax. Enable them by typing only the flag name, as in the following example:
supported: sqlj -version-long ...
not supported: sqlj -version-long=true ...
The -props option specifies a properties file from which SQLJ can read option settings (an alternative to specifying option settings on the command line).
See "Properties Files for Option Settings" for information about the format of these files, the details of how they are used in relation to command-line options, and where SQLJ looks for default properties files.
-props=filename
-props=myprops.properties
n/a
n/a
none
For compatibility with the syntax of most JVMs and compilers, SQLJ recognizes the -classpath option if it is specified on the command line. In setting this option, you can use either a space, as with most JVMs or compilers, or "=", as with other SQLJ options. The following examples (both on Solaris) demonstrate this:
-classpath=.:./classes:/vobs/dbjava/classes/classes111.zip:/jdbc-1.2.zip
or:
-classpath .:./classes:/vobs/dbjava/classes/classes111.zip:/jdbc-1.2.zip
The -classpath option sets the Java classpath for both the JVM and the Java compiler. If you do not want to use the same classpath for both, set them separately using the SQLJ -J and -C prefixes, described in "Prefixes that Pass Option Settings to Other Executables".
sqlj -classpath=<class_path>
sqlj -classpath=/jdbc-1.2.zip:/classes/bin
n/a
n/a
none
The following three settings of the -help flag, specified on the command-line, instruct SQLJ to display varying levels of information about SQLJ options:
You can enable this option by typing the desired setting on the command line as in the following examples:
sqlj -help
or:
sqlj -help-long
or:
sqlj -help-alias
No input-file translation is performed when you use the -help flag in any of these forms, even if you include file names and other options on the command line as well. SQLJ assumes that you either want to run the translator or you want help, but not both.
You can also receive information about the profile customizer or Java compiler, requesting help through the -P and -C prefixes as in the following examples. These prefixes are discussed in "Prefixes that Pass Option Settings to Other Executables". As with the -help flag, no translation is performed if you request customizer or compiler help.
sqlj -P-help sqlj -C-help
As with other command-line-only flags, -help (as well as -P-help and -C-help) does not support =true syntax. Enable it by typing only the desired flag setting.
|
Notes:
|
The most basic level of help is achieved by specifying the -help setting. This provides the following:
-help flag settings available
This setting provides a complete list of SQLJ option information, including the following for each option:
int or String)
This setting provides a synopsis of the command-line abbreviations supported for compatibility with the loadjava utility.
sqlj help_flag_settings
sqlj -help sqlj -help -help-alias sqlj -help-long sqlj -warn=none,null -help-long sqlj -help-alias
n/a
n/a
none
The following settings of the -version flag, specified on the command-line, instruct SQLJ to display varying levels of information about SQLJ and JDBC driver versions:
You can enable this option by typing the desired setting on the command line as in the following examples:
sqlj -version
or:
sqlj -version-long
No input-file translation is performed when you use the -version option, even if you include file names and other options on the command line. SQLJ assumes that you either want to run the translator or you want version information, but not both. Properties files and anything else you type on the command line are ignored.
As with other command-line-only flags, -version does not support =true syntax. Enable it by typing only the flag name.
The -version setting displays the SQLJ release number, such as "Oracle SQLJ 9.0.1".
The -version-long setting displays information about the SQLJ and SQLJ runtime library release and build versions, the JDBC driver release number if one can be found, and the Java environment. For example, if an Oracle JDBC driver is used, this option would display something such as "Oracle JDBC version 9.0 (9.0.1.0)".
This flag offers a good way to check your SQLJ installation and the JDBC and JDK versions you are using.
sqlj version_flag_settings
sqlj -version sqlj -version -version-long sqlj -version-long
n/a
n/a
none
The -n flag, specified on the command line, instructs the sqlj script to construct the full command line that would be passed to the SQLJ translator, including any SQLJ_OPTIONS settings, and echo it to the user without having the SQLJ translator execute it. This includes capturing and echoing the name of the JVM that would be launched to execute the SQLJ translator and echoing the full class name of the translator. This does not include settings from properties files.
This is useful in showing you the following:
-u and other abbreviations supported for loadjava compatibility)
SQLJ_OPTIONS settings and command-line settings
The -n option can appear anywhere on the command line or in the SQLJ_OPTIONS variable.
As with other command-line-only flags, -n does not support =true syntax. Enable it by typing only the flag name.
Consider the following sample scenario:
SQLJ_OPTIONS:
-user=scott/tiger@jdbc:oracle:thin:@ -classpath=/myclasses/bin
% sqlj -n -e SJIS myapp.sqlj
You would see the following echo:
java -classpath /myclasses/bin sqlj.tools.Sqlj -user=scott/tiger@jdbc:oracle:thin:@ -C-classpath=/myclasses/bin -encoding=SJIS myapp.sqlj
(This is all one wrap-around line.)
|
Note:
|
-n
-n
n/a
n/a
false
The following option specifies encoding for SQLJ input and output source files:
These options specify where SQLJ output files are placed:
The -encoding option specifies the encoding to be applied to .sqlj and .java input files and .java generated files for globalization support. For compatibility with javac, you can use either a space or "=" in setting this option on the command line, as in the following examples:
-encoding=SJIS -encoding SJIS
If setting sqlj.encoding in a properties file, however, use "=", not a space.
When this option is specified, it is also passed to the Java compiler (unless the -compiler-encoding-flag is off), which uses it to specify encoding for .java files processed by the compiler.
Note the following:
-classpath and -d options described below, if you do use an "=" in setting the -encoding option, then it is stripped out when the option string is passed to the JVM and compiler. This is because JVMs and compilers do not support the "=" syntax in their option settings.
loadjava utility, -e is recognized as equivalent to -encoding when specified on the command line. See "Options for loadjava Compatibility".
-encoding option 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 create escape sequences for a natively encoded file--see "Using native2ascii for Source File Encoding".)
-encoding=Java_character_encoding
-encoding=SJIS
sqlj.encoding=Java_character_encoding
sqlj.encoding=SJIS
setting in JVM system property file.encoding
The -d option specifies the root output directory for profiles generated by the SQLJ translator, and is also passed to the Java compiler to specify the root output directory for .class files generated by the compiler. Whether profiles are generated as .ser files (default) or .class files (if the -ser2class option is enabled) is irrelevant in using the -d option. (For information about -ser2class, see "Conversion of .ser File to .class File (-ser2class)".)
Whenever a directory is specified, the output files are generated under this directory according to the package name, if applicable. For example, if you have source files in package a.b.c and specify directory /mydir, output files will be placed in directory /mydir/a/b/c.
If you specify a relative directory path, this will be from your current directory.
For compatibility with javac, you can use either a space or "=" in setting this option on the command line, as in the following examples (both of which make /root the root directory for generated profile files):
-d=/root -d /root
If setting -d in a properties file, however, use "=", not a space (for example, sqlj.d=/root).
If your current directory is /root/home/mydir and you set the -d option to the relative directory path mysubdir/myothersubdir as follows, then /root/home/mydir/mysubdir/myothersubdir will be the root directory for generated profile files:
-d=mysubdir/myothersubdir
You can also use standard syntax such as a period for the current directory or two periods to go up a level (the second example immediately below will go up a level, then back down to a parallel directory called paralleldir):
-d=. -d=../paralleldir
If the -d option is empty or not specified, then .class files and .ser files generated by the translation process will be placed as follows:
.class file corresponding to a .java file that was generated by the translator is placed in the same directory as the generated .java file, which is according to the -dir option.
.class file corresponding to a .java file that you specified on the command line will be placed in the same directory as the .java file.
.ser file is placed in the same directory as the .sqlj source file from which it resulted.
-d=directory_path
-d=/topleveldir/mydir
sqlj.d=directory_path
sqlj.d=/topleveldir/mydir
none (.class files go with .java files; .ser files go with .sqlj files)
The -dir option specifies the root directory for .java files generated by the SQLJ translator.
Whenever a directory is specified, the output files are generated under this directory according to the package name, if applicable. For example, if you have source files in package a.b.c and specify directory /mydir, then output files will be placed in directory /mydir/a/b/c.
If you specify a relative directory path, it will be from your current directory.
A simple example is as follows, which will make /root the root directory for generated .java files:
-dir=/root
If your current directory is /root/home/mydir and you set the -dir option to the relative directory path mysubdir/myothersubdir as follows:
-dir=mysubdir/myothersubdir
then /root/home/mydir/mysubdir/myothersubdir will be the root directory for generated .java files.
You can also use standard syntax such as a period for the current directory or two periods to go up a level (the second example immediately below will go up a level, then back down to a parallel directory called paralleldir):
-dir=. -dir=../paralleldir
If the -dir option is not specified, then files are generated under the same directory as the original .sqlj source file (not under the current directory).
If you specifically want the output directory to be the same as your .sqlj source directory (perhaps overriding other -dir settings, such as in properties files), then you can use the -dir option as follows:
-dir=
-dir=directory_path
-dir=/topleveldir/mydir
sqlj.dir=directory_path
sqlj.dir=/topleveldir/mydir
none (use directory of .sqlj source file)
You can use the following options for the database connection for online semantics-checking:
There is no requirement that the SQLJ translator connect to the same database or schema as the application does at runtime. The connection information in application source code can be independent of the connection information in the SQLJ options.
A situation where you will probably want to use a different connection for translation than for runtime is if you are developing in a different environment than the one to which you will deploy.
Simple semantics-checking not involving a database connection is referred to as offline checking. The more thorough semantics-checking requiring a connection is referred to as online checking. Online checking offers one of the prime advantages of the SQLJ strong-typing paradigm--type incompatibilities that would normally result in runtime SQL exceptions are caught during translation, before users ever run the application.
The -user option enables online semantics-checking and specifies the user name (schema name) for the exemplar schema, which is the sample database schema that you provide to the translator for it to use in performing the checking. You can also use the -user option to specify the password and URL, as opposed to using the -password and -url options separately.
Note that there is no other flag to enable or disable online semantics-checking; SQLJ enables it or disables it according to the presence or absence of the -user option.
Discussion of the -user option is split into two categories--1) effect of -user when you are employing the default connection context class only; and 2) effect of -user when you are employing non-default or multiple connection context classes. Non-default connection context classes are discussed in "Connection Contexts".
General discussion of connection considerations, such as when to use multiple instances of the DefaultContext class and when to declare additional connection context classes, is in "Connection Considerations".
|
Notes:
|
The most basic usage of the -user option is as follows:
-user=scott
When you are using only the default connection or other instances of the DefaultContext class, such a setting will apply to all your SQLJ executable statements. This example results in online checking against the scott schema.
You can also specify the password, URL, or both along with the user name, using syntax as in the following examples (with "/" preceding the password and "@" preceding the URL):
-user=scott/tiger
or:
-user=scott@jdbc:oracle:oci:@
or:
-user=scott/tiger@jdbc:oracle:oci:@
Otherwise the URL can be specified through the -url option, and the password can be specified interactively or through the -password option.
You can disable online semantics-checking by setting the -user option to an empty string:
-user=
Again, when you are using only the default connection or other instances of the DefaultContext class, this will apply to all your SQLJ executable statements.
Disabling online semantics-checking is useful, for example, if you have online checking enabled in a properties file but want to override that on the command line, or have it enabled in the default properties file but want to override that in a user-specified properties file (specified using the -props option).
There is also a special user name, URL.CONNECT, which you can use when the URL specifies the user and password as well as the other details of the connection. To see what the URL would look like in such a case, see "Connection URL for Online Semantics-Checking (-url)".
If you declare and use additional connection context classes in your application, then you can specify -user settings for the testing of SQLJ executable statements that use instances of those classes. Specify a user name for online checking against a particular connection context class (CtxClass, for example) as follows:
-user@CtxClass=scott
This results in online checking against the scott schema for any of your SQLJ executable statements that specify a connection context instance of the class CtxClass.
As with the default connection context class, you can also specify the password or URL in your -user setting for a particular connection context class, as in the following example:
-user@CtxClass=scott/tiger@jdbc:oracle:oci:@
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.)
Employ the -user option separately for each connection context class for which you want to enable online checking and set a user name; these settings have no influence on each other:
-user@CtxClass1=user1 -user@CtxClass2=user2 -user@CtxClass3=user3
When you are using multiple connection context classes in your application, a -user setting that does not specify a class will apply to the DefaultContext class as well as to all classes for which you do not otherwise specify a -user setting. Presumably, though, you will specify a -user setting for each connection context class, given that different connection context classes are typically intended for use with different sets of SQL objects.
Consider a situation where you have declared connection context classes CtxClass1, CtxClass2, and CtxClass3 and you set -user as follows:
-user@CtxClass2=scott/tiger -user=bill/lion
Any statement in your application that uses an instance of CtxClass2 will be checked against the scott schema. Any statement that uses an instance of DefaultContext, CtxClass1, or CtxClass3 will be checked against the bill schema.
In addition, once you enable online checking by setting the -user option, you can disable online checking for a particular connection context by setting the -user option again with an empty user name for that connection context. For example, consider the following setting:
-user@CtxClass2=
This disables online semantics-checking for any SQLJ executable statements that specify a connection object that is an instance of CtxClass2.
To disable online semantics-checking for the default connection context class and any other connection context classes for which you do not specify a user name:
-user=
-user<@conn_context_class>=username</password><@url>
-user=scott -user=scott/tiger -user=scott@jdbc:oracle:oci:@ -user=scott/tiger@jdbc:oracle:oci:@ -user= -user=URL.CONNECT -user@CtxClass=scott/tiger -user@CtxClass=
sqlj.user<@conn _context_class>=username</password><@url>
sqlj.user=scott sqlj.user=scott/tiger sqlj.user=scott@jdbc:oracle:oci:@ sqlj.user=scott/tiger@jdbc:oracle:oci:@ sqlj.user= sqlj.user=URL.CONNECT sqlj.user@CtxClass=scott/tiger sqlj.user@CtxClass=
none (no online semantics-checking)
|
Note:
Be aware of the difference in format between specifying user, password, and URL in the |
The -password option specifies the user password for the database connection for online semantics-checking. For the -password setting to be meaningful, the -user option must also be set .
You can also specify the password as part of the -user option setting. See "Online Semantics-Checking and User Name (-user)". Do not use the -password option for a connection context class if you have already set its password in the -user option, which takes precedence.
For the most part, functionality of the -password option parallels that of the -user option. That is, if your application uses only the default connection or other instances of DefaultContext, the next example will set the password for the schema to be used in checking all of your SQLJ statements.
-password=tiger
If you declare and use additional connection context classes, CtxClass1 for example, then you will presumably employ the -user option to specify additional exemplar schemas to use in testing statements that use those connection context classes. Similarly, use the -password option to specify passwords for those schemas, as in the following example:
-password@CtxClass1=tiger
A connection context class without a password setting, either through the -password setting or the -user setting, uses the password setting for the default connection context class. If you set no password for the default connection context class, then SQLJ prompts you interactively for that password. If you also set no password for a user-defined connection context class, then SQLJ prompts you interactively for that password as well. An exception to this discussion is where user name URL.CONNECT is used, as discussed in "Online Semantics-Checking and User Name (-user)". In this case, user name and password are determined from the string specified in the -url setting, and any setting of the -password option is ignored.
You can specifically set an empty password to override other settings of the -password option, such as in a properties file, and be prompted interactively. You can do this for the DefaultContext class or any particular connection context class, as in the following examples:
-password=
or:
-password@CtxClass1=
If you actually want to use an empty password to log in, specify EMPTY.PASSWORD as in the following examples:
-password=EMPTY.PASSWORD
or:
-password@CtxClass2=EMPTY.PASSWORD
The Oracle9i database, however, does not permit an empty password.
-password<@conn_context_class>=user_password
-password=tiger -password= -password=EMPTY.PASSWORD -password@CtxClass=tiger
sqlj.password<@conn_context_class>=user_password
sqlj.password=tiger sqlj.password= sqlj.password=EMPTY.PASSWORD sqlj.password@CtxClass=tiger
none (password for DefaultContext is used, or user is prompted)
The -url option specifies a URL for establishing a database connection for online semantics-checking. As necessary, the URL can include a host name, port number, and Oracle SID.
You can also specify the URL as part of the -user option setting. See "Online Semantics-Checking and User Name (-user)". Do not use the -url option for a connection context class if you have already set its URL in the -user option, which takes precedence.
For the most part, functionality of the -url option parallels that of the -user option. That is, if your application uses only the default connection or other instances of DefaultContext, the following example would set the URL to use for the connection for checking all your SQLJ statements:
-url=jdbc:oracle:oci:@
Or, to include the host name, port number, and SID:
-url=jdbc:oracle:thin:@hostname:1521:orcl
If you do not begin a URL setting with jdbc: then the setting is assumed to be of the form host:port:sid and by default is automatically prefixed with the following:
jdbc:oracle:thin:@
A -url setting of localhost:1521:orcl, for example, results in the following URL:
jdbc:oracle:thin:@localhost:1521:orcl
You can remove or alter this default prefix with the -default-url-prefix option. See "Default URL Prefix (-default-url-prefix)" for more information.
You can specify the user and password in the -url setting, instead of in the -user and -password settings. In such a case, set -user to URL.CONNECT, as follows:
-url=jdbc:oracle:oci:scott/tiger@ -user=URL.CONNECT
If you declare and use additional connection context classes, CtxClass1 for example, you will presumably specify additional exemplar schemas to use in testing statements that use those connection context classes. You can use the -url option to specify URLs for those schemas, as in the following example:
-url@CtxClass1=jdbc:oracle:oci:@
Any connection context class without a URL setting, either through the -url setting or the -user setting, uses the URL setting for the default connection context class, presuming a URL has been set for the default context class.
-url<@conn_context_class>=URL
-url=jdbc:oracle:oci:@ -url=jdbc:oracle:thin:@hostname:1521:orcl -url=jdbc:oracle:oci:scott/tiger@ -url=hostname:1521:orcl -url@CtxClass=jdbc:oracle:oci:@
sqlj.url<@conn_context_class>=URL
sqlj.url=jdbc:oracle:oci:@ sqlj.url=jdbc:oracle:thin:@hostname:1521:orcl sqlj.url=jdbc:oracle:oci:scott/tiger@ sqlj.url=hostname:1521:orcl sqlj.url@CtxClass=jdbc:oracle:oci:@
jdbc:oracle:oci:@
|
Note:
Be aware of the difference in format between specifying user, password, and URL in the |
Use the -default-url-prefix option to alter or remove the default prefix.
The following is the default prefix for any URL setting you specify that does not already start with jdbc:
jdbc:oracle:thin:@
This allows you to use a shorthand in specifying a URL setting, either in the -user option or the -url option--it is permissible to specify only the host, port, and SID of the database. As an example, presume you set a URL as follows:
-url=myhost:1521:orcl
or:
-user=scott/tiger@myhost:1521:orcl
By default, the URL will be interpreted to be the following:
jdbc:oracle:thin:@myhost:1521:orcl
If you specify a full URL that starts with jdbc:, then the default prefix will not be used, such as in the following example:
-url=jdbc:oracle:oci:@orcl
However, if you want your URL settings to default to the OCI driver, for example, instead of the Thin driver, then set the default prefix as follows:
-default-url-prefix=jdbc:oracle:oci:@
With this prefix, a setting of -url=orcl is equivalent to the -url=jdbc:oracle:oci:@orcl setting above.
If you do not want any prefix, then set the -default-url-prefix option to an empty string, as follows:
-default-url-prefix=
-default-url-prefix=url_prefix
-default-url-prefix=jdbc:oracle:oci:@ -default-url-prefix=
sqlj.default-url-prefix=url_prefix
sqlj.default-url-prefix=jdbc:oracle:oci:@ sqlj.default-url-prefix=
jdbc:oracle:thin:@
The -driver option specifies the JDBC driver class to register for interpreting JDBC connection URLs for online semantics-checking. Specify a driver class or comma-separated list of classes.
The default, OracleDriver, supports the Oracle OCI, Thin, and server-side JDBC drivers for use with Oracle9i.
-driver=driver1<,driver2,driver3,...>
-driver=oracle.jdbc.OracleDriver -driver=oracle.jdbc.OracleDriver,sun.jdbc.odbc.JdbcOdbcDriver
sqlj.driver=driver1<,driver2,driver3,...>
sqlj.driver=oracle.jdbc.OracleDriver sqlj.driver=oracle.jdbc.OracleDriver,sun.jdbc.odbc.JdbcOdbcDriver
oracle.jdbc.OracleDriver
The following options specify what types of conditions SQLJ should monitor, whether to generate real-time error and status messages, and whether to include "cause" and "action" information with translator error messages:
The following options enable line-mapping from the generated Java .class file back to the .sqlj source file, so that you can trace runtime errors back to the appropriate location in your original source code. Use -jdblinemap in conjunction with the Sun Microsystems jdb debugger; otherwise use -linemap.
There are various warnings and informational messages that the SQLJ translator can display as dictated by conditions it encounters during the translation. The -warn option consists of a set of flags that specify which of those warnings and messages should be displayed (in other words, which conditions should be monitored and which should be ignored).
All the flags for this option must be combined into a single, comma-separated string.
Table 8-2 documents the conditions that can be tested, what the true and false flag values are for each condition, what a true flag value means, and which value is the default.
The verbose/noverbose flag works differently from the others. It does not enable a particular test but enables output of general informational messages about the semantics-checking.
The global all/none flag takes priority over default settings. You can use it to enable or disable all flags, or to serve as an initialization to make sure all flags are off before you turn selected flags on, or the converse.
The all setting is equivalent to the following:
cast,precision,nulls,portable,strict,verbose
And the none setting is equivalent to the following:
nocast,noprecision,nonulls,noportable,nostrict,noverbose
There is no default for all/none; there are only defaults for individual flags.
For example, use the following sequence to make sure only the nulls flag is on:
-warn=none,nulls
And the following sequence will have the same result, because the verbose setting will be overridden:
-warn=verbose,none,nulls
Or use the following to make sure everything except the portability flag is on:
-warn=all,noportable
And the following sequence will have the same result, because the nonulls setting will be overridden:
-warn=nonulls,all,noportable
Other than placement of the all/none flag, the order in which flags appear in a -warn setting is unimportant, except in the case of conflicting settings. If there are conflicts--such as in -warn=portable,noportable--then the last (right-most) setting is used.
Separate settings of the -warn option in properties files and on the command line are not cumulative. Only the last setting is processed. In the following example, the -warn=portable setting is ignored--that flag and all other flags besides nulls/nonulls are set according to their defaults:
-warn=portable -warn=nonulls
-warn=comma-separated_list_of_flags
-warn=none,nulls,precision
sqlj.warn=comma-separated_list_of_flags
sqlj.warn=none,nulls,precision
cast,precision,nulls,noportable,strict,noverbose
The -status flag instructs SQLJ to output additional status messages throughout all aspects of the SQLJ process--translation, semantics-checking, compilation, and customization. Messages are output as each file is processed and at each stage of SQLJ operation.
|
Notes:
|
-status=true/false
-status=true
sqlj.status=true/false
sqlj.status=false
false
The -explain flag instructs the SQLJ translator to include "cause" and "action" information (as available) with translator error message output (for the first occurrence of each error).
This is the same information provided in "Translation Time Messages", starting.
-explain=true/false
-explain=true
sqlj.explain=true/false
sqlj.explain=false
false
The -linemap flag instructs SQLJ to map line numbers from a SQLJ source code file to locations in the corresponding .class file. (This will be the .class file created during compilation of the .java file generated by the SQLJ translator.) As a result, when Java runtime errors occur, the line number reported by the JVM is the line number in the SQLJ source code, making it much easier to debug.
Normally, the instructions in a .class file map to source code lines in the corresponding .java file. This would be of limited use to SQLJ developers, though, as they would still need to map line numbers in the generated .java file to line numbers in their original .sqlj file.
The SQLJ translator modifies the .class file to implement the -linemap option, replacing line numbers and the file name from the generated .java file with corresponding line numbers and the file name from the original .sqlj file. This process is known as instrumenting the class file.
In performing this, SQLJ takes the following into account:
-d option setting, which determines the root directory for .class files
-dir option setting, which determines the root directory for generated .java files
-linemap=true/false
-linemap=true
sqlj.linemap=true/false
sqlj.linemap=false
false
This option is equivalent to the -linemap option (discussed in the preceding section), but you should use it instead of -linemap if you are using the jdb debugger provided with the Sun Microsystems JDK.
This is because jdb can access only source files with a .java file name extension. With the -jdblinemap setting, SQLJ does the following:
.java file generated by the translator with the contents of the original .sqlj file.
.java file name, instead of the .sqlj file name, in the generated .class file.
In this way, the SQLJ source code is accessible to jdb.
-jdblinemap=true/false
-jdblinemap=true
sqlj.jdblinemap=true/false
sqlj.jdblinemap=false
false
Oracle9i SQLJ allows Oracle-specific code generation, which generates Oracle JDBC code directly, as an alternative to standard SQLJ code generation. With Oracle-specific code generation, no profiles are generated, and the SQLJ runtime is largely bypassed during code execution.
Because profile customization is not applicable with Oracle-specific code generation, some generally useful optimization options, formerly available only through the Oracle customizer, are now available directly through the SQLJ translator.
This section describes these code generation and optimization options:
-codegen
-optcols
-optparams
-optparamdefaults
For standard SQLJ code generation, use the Oracle customizer
Note:
optcols, optparams, and optparamdefaults options instead. See "Oracle Customizer Options".
Oracle SQLJ offers the alternative of generating Oracle JDBC code directly instead of generating standard code that calls the SQLJ runtime (which in turn contains calls to Oracle JDBC). With Oracle-specific code generation, there are no profile files, and the SQLJ runtime is largely bypassed during program execution.
Use the SQLJ translator -codegen option to specify Oracle-specific code generation, as follows:
-codegen=oracle
The default is standard SQLJ code generation, but you can also explicitly specify this as follows:
-codegen=iso
See "Oracle-Specific Code Generation (No Profiles)" for information about advantages, disadvantages, limitations, and special considerations regarding Oracle-specific code generation.
-codegen=iso/oracle
-codegen=oracle
sqlj.codegen=iso/oracle
sqlj.codegen=oracle
iso
For Oracle-specific code generation, use the SQLJ translator -optcols flag to instruct the translator to determine types and sizes of iterator or result set columns. This enables registration of the columns with the Oracle JDBC driver when your application runs, saving round trips to Oracle9i depending on the particular driver implementation. Specifically, this is effective for the Thin driver and positional iterators.
For an overview of column definitions, see "Column Definitions".
|
Note:
For standard SQLJ code generation, use the Oracle customizer |
You can enable or disable this flag on the SQLJ command line or in a properties file.
Enable it on the command line as follows:
-optcols
or:
-optcols=true
This flag is disabled by default, but you can also disable it explicitly. Disable it on the command line as follows:
-optcols=false
Column definitions require a database connection for examination of the columns of tables being queried, so the SQLJ translator -user, -password, and -url options must also be set appropriately. For example:
sqlj -user=scott/tiger@jdbc:oracle:oci:@ -optcols MyApp.sqlj
-optcols<=true/false>
-optcols
profile.optcols<=true/false>
profile.optcols
false
For Oracle-specific code generation, use the SQLJ translator -optparams flag to enable parameter size definitions. If this flag is enabled, SQLJ will register your input and output parameters (host variables) to optimize JDBC resource allocations according to sizes you specify, with the following precedence:
-optparamdefaults option setting
If there is no source code hint or default datatype size for a given host variable, then resource allocation is left to JDBC.
For an overview of parameter size definitions and a discussion of source code hints, see "Parameter Size Definitions".
|
Note:
For standard SQLJ code generation, use the Oracle customizer |
You can enable or disable the -optparams flag on the command line or in a SQLJ properties file.
Enable it on the command line as follows:
-optparams
or:
-optparams=true
This flag is disabled by default, but you can also disable it explicitly. Disable it on the command line as follows:
-optparams=false
Following is a command-line example (omitting a setting for the -optparamdefaults option, which is discussed in the next section):
sqlj -optparams -optparamdefaults=defaults-string MyApp.sqlj
-optparams<=true/false>
-optparams
profile.optparams<=true/false>
profile.optparams
false
If you enable the -optparams option to set parameter sizes, use the -optparamdefaults option as desired to set default sizes for specified datatypes. If -optparams is not enabled, then any -optparamdefaults setting is ignored.
If a host variable has a source code hint to specify its size, that takes precedence over the corresponding datatype default size set with this option. If there is no source code hint or corresponding datatype default size for a particular host variable, then resource allocation for that variable is determined by the JDBC driver, just as it would be if -optparams were not enabled.
There is no requirement to use the -optparamdefaults option, although it is typically used whenever -optparams is enabled. If -optparams is enabled and there are no default size settings, then resources are allocated either according to source code hints (if any) or according to the JDBC driver.
For an overview of parameter size definitions and a discussion of source code hints, see "Parameter Size Definitions".
|
Note:
For standard SQLJ code generation, use the Oracle customizer |
You can set the -optparamdefaults flag on the command line or in a SQLJ properties file.
Set it on the command line as follows:
-optparamdefaults=datatype1(size1),datatype2(size2),...
All sizes are in bytes. Do not include any white space. Use empty parentheses for a null setting.
For example, the following will set sizes of 30 bytes for VARCHAR2 and 1000 bytes for RAW, and will specify a null size setting for CHAR. So for any host variable corresponding to the CHAR datatype, if there is no source code hint, then the JDBC driver is left to allocate the resources.
-optparamdefaults=VARCHAR2(30),RAW(1000),CHAR()
The -optparamdefaults option recognizes the following datatype names:
CHAR
VARCHAR, VARCHAR2 (synonymous)
LONG, LONGVARCHAR (synonymous)
BINARY, RAW (synonymous)
VARBINARY
LONGVARBINARY, LONGRAW (synonymous)
The -optparamdefaults option also recognizes group names and wildcards, as follows:
CHAR_TYPE covers CHAR, VARCHAR/VARCHAR2, and LONG/LONGVARCHAR.
RAW_TYPE covers BINARY/RAW, VARBINARY, and LONGVARBINARY/LONGRAW.
% by itself covers all recognized datatypes, or, appended to a partial name, covers a subset of datatypes. For example, VAR% includes all datatypes that start with "VAR".
The -optparamdefaults setting is processed from left to right. When using group names or wildcards, you can override a group setting for particular datatypes.
The following example sets a general default size of 50 bytes, overrides that with a setting of 500 bytes for raw types, then overrides the raw type group setting with a null setting for VARBINARY (leaving that to JDBC for corresponding host variables with no source code hints):
-optparamdefaults=%(50),RAW_TYPE(500),VARBINARY()
Following is a command-line example, including the -optparams setting as well:
sqlj -optparams -optparamdefaults=CHAR_TYPE(50),RAW_TYPE(500),CHAR(10) MyApp.sqlj
-optparamdefaults=defaults-string
-optparamdefaults=VAR%(50),LONG%(500),RAW_TYPE()
profile.optparamdefaults=defaults-string
profile.optparamdefaults=VAR%(50),LONG%(500),RAW_TYPE()
null
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".
The following flags mark options to be passed to the Java interpreter, Java compiler, and SQLJ profile customizer:
-J (mark options for the Java interpreter)
-C (mark options for the Java compiler)
-P (mark options for the profile customizer)
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:
|
-J-Java_option
-J-Duser.language=ja
n/a
n/a
n/a
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:
-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.OracleDriver -P-Csummary
profile.<C>profile_customizer_option
profile.driver=oracle.jdbc.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:
The following flag instructs SQLJ to convert profiles from serialized resource (.ser) files to class files after customization:
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:
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.
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.
|
Notes:
There are situations where it is sensible for
(An example of a situation where |
-compile=true/false
-compile=false
sqlj.compile=true/false
sqlj.compile=false
true (compile)
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.
-profile=true/false
-profile=false
sqlj.profile=true/false
sqlj.profile=false
true (customize)
With standard SQLJ code generation, 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
-ser2class=true/false
-ser2class=true
sqlj.ser2class=true/false
sqlj.ser2class=false
false
It may not be sufficient for the SQLJ type resolution process to examine 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:
-checksource=true/false
-checksource=true
sqlj.checksource=true/false
sqlj.checksource=false
true
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 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, there are the following categories of checkers (for both online and offline checking):
The Oracle80 and Oracle7 checkers are incompatible with the Oracle8i and Oracle9i 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 or Oracle9i JDBC driver and check against an Oracle 7.3.x subset of types.
If you are using an Oracle database (or perhaps the middle-tier database cache) 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 be used only 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 database connection--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.
-offline<@conn_context_class>=checker_class
-offline=oracle.sqlj.checker.Oracle80OfflineChecker
-offline@CtxClass=oracle.sqlj.checker.Oracle80OfflineChecker
sqlj.offline<@conn_context_class>=checker_class
sqlj.offline=oracle.sqlj.checker.Oracle80OfflineChecker
sqlj.offline@CtxClass=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 established for online checking. (At analysis time, a connection is passed to each online checker, and the checker decides whether it recognizes the database.)
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.
-online<@conn_context_class>=checker_class(list)
-online=oracle.sqlj.checker.Oracle80JdbcChecker
-online=oracle.sqlj.checker.Oracle80JdbcChecker,sqlj.semantics.JdbcChecker
-online@CtxClass=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@CtxClass=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. Delete the SQLChecker.cache file to empty the cache.
-cache=true/false
-cache=true
sqlj.cache=true/false
sqlj.cache=false
false
By default, Oracle9i SQLJ is configured to run under the Sun Microsystems JDK 1.2.x (or higher) or 1.1.x and to use the Sun Microsystems compiler javac. These are not requirements, however. You can configure SQLJ to work with alternative JVMs or compilers. To do so, you must supply SQLJ with the following information:
-vm option)
-compiler-executable option)
A set of SQLJ options allows you to provide this information. These options are described in "Java and Compiler Options" below.
SQLJ also defaults to the Oracle profile customizer, but can work with alternative customizers as well. See "Customization Options" for how to instruct SQLJ to use a different customizer.
The following options relate to the operation of the JVM and Java compiler:
-vm (specify the JVM; command-line only)
-compiler-executable (specify the Java compiler)
-compiler-encoding-flag
-compiler-output-file
-compiler-pipe-output-flag
Some compilers, such as the standard javac, require a Java source file name to match the name of the public class (if any) defined there. Therefore, by default the SQLJ translator verifies that this is true. You can use the following option, however, to instruct SQLJ not to verify this:
For some JVM and compiler configurations, there might be problems with the way SQLJ normally invokes the compiler. You can use the following option to alleviate this by breaking SQLJ processing into a two-pass process:
You can also pass options directly to the particular JVM or compiler you use, through the -J and -C prefixes discussed in "Prefixes that Pass Option Settings to Other Executables".
|
Note:
The |
Use the -vm option if you want to specify a particular JVM for SQLJ to use. Otherwise SQLJ uses the standard java from the Sun Microsystems JDK.
You cannot set this option in a properties file, because properties files are read after the JVM is invoked.
If you do not specify a directory path along with the name of the JVM executable file, then SQLJ looks for the executable according to the setting of your operating system PATH variable.
|
Note:
Special functionality of this option, |
-vm=JVM_path+name
-vm=/myjavadir/myjavavm
n/a
n/a
java
Use the -compiler-executable option if you want to specify a particular Java compiler for SQLJ to use. Otherwise SQLJ uses the standard javac from the Sun Microsystems JDK.
If you do not specify a directory path along with the name of the compiler executable file, then SQLJ looks for the executable according to the setting of your operating system PATH variable.
The following is required of any Java compiler that you use:
STDOUT on a UNIX system) or, alternatively, to a file (as directed by the -compiler-output-file option, described below).
-d option, which determines the root directory for class files.
As always, SQLJ processes compiler line information so that it refers to line numbers in the original .sqlj file, not in the produced .java file.
|
Note:
If you use a compiler that does not support an |
-compiler-executable=Java_compiler_path+name
-compiler-executable=/myjavadir/myjavac
sqlj.compiler-executable=Java_compiler_path+name
sqlj.compiler-executable=myjavac
javac
As mentioned in "Encoding for Input and Output Source Files (-encoding)", it is typical that when you employ the -encoding option to specify an encoding character set for SQLJ to use, SQLJ passes this to the Java compiler for the compiler to use as well. Set the -compiler-encoding-flag to false if you do not want SQLJ to pass the character encoding to the compiler (if, for example, you are using a compiler other than javac, and it does not support an -encoding option by that name).
-compiler-encoding-flag=true/false
-compiler-encoding-flag=false
sqlj.compiler-encoding-flag=true/false
sqlj.compiler-encoding-flag=false
true
If you have instructed the Java compiler to output its results to a file, then use the -compiler-output-file option to make SQLJ aware of the file name. Otherwise SQLJ assumes that the compiler outputs to the standard output device (such as STDOUT on a UNIX system). As appropriate, specify an absolute path, or a relative path from the current directory.
-compiler-output-file=output_file_path+name
-compiler-output-file=/myjavadir/mycmploutput
sqlj.compiler-output-file=output_file_path+name
sqlj.compiler-output-file=/myjavadir/mycmploutput
none (standard output)
By default, the javac compiler provided with the Sun Microsystems JDK writes error and message output to STDERR. SQLJ, however, expects such compiler output to be written to STDOUT so it can be captured reliably.
If SQLJ sets the javac.pipe.output system property to true, which is SQLJ's default behavior when it invokes the Java compiler, then compiler error and message output will be sent to STDOUT. You can specify -compiler-pipe-output-flag=false, however, to instruct SQLJ to not set this system property when it invokes the Java compiler. You should do this, for example, if the Java compiler you are using does not support the javac.pipe.output system property.
You can set this flag in a properties file, as well as on the command line or in the SQLJ_OPTIONS environment variable.
-compiler-pipe-output-flag=true/false
-compiler-pipe-output-flag=false
sqlj.compiler-pipe-output-flag=true/false
sqlj.compiler-pipe-output-flag=false
true
This flag instructs SQLJ whether to verify that the SQLJ source file name matches the name of the public class (if any) defined there. Some compilers, such as the standard javac, require this to be the case; others do not.
To maximize portability of your code, this flag should be enabled, which it is by default.
(It is advisable for the source file name to always match the name of the public class defined, or, if there is no public class, the name of the first class defined. For example, public class MyPublicClass should be defined in a MyPublicClass.sqlj source file.)
-checkfilename=true/false
-checkfilename=false
sqlj.checkfilename=true/false
sqlj.checkfilename=false
true
By default, the following sequence occurs when you invoke the sqlj script:
sqlj script invokes your JVM, which runs the SQLJ translator.
.sqlj files, generating translated .java files.
.java files.
For some JVM and compiler configurations, however, the compiler invocation in step 3 will not return, and your translation will suspend.
If you encounter this situation, the solution is to instruct SQLJ to run in two passes, with the compilation step in between. To accomplish this, you must enable the two-pass execution flag as follows:
-passes
The -passes option must be specified on the command line or, equivalently, in the SQLJ_OPTIONS environment variable. It cannot be specified in a properties file.
With -passes enabled, the following sequence occurs when you invoke the sqlj script:
sqlj script invokes your JVM, which runs the SQLJ translator for its first pass.
.sqlj files, generating translated .java files.
sqlj script invokes the Java compiler, which compiles the generated .java files.
sqlj script invokes your JVM again, which runs the SQLJ translator for its second pass.
With this sequence, you circumvent any problems the JVM might have in invoking the Java compiler.
-passes
-passes
n/a
n/a
off
The following options relate to the customization of your SQLJ profiles:
Use the -default-customizer option to instruct SQLJ to use a profile customizer other than the default, which is:
oracle.sqlj.runtime.util.OraCustomizer
In particular, use this option if you are not using an Oracle database.
This option takes a fully qualified Java class name as its argument.
|
Notes:
You can override this option with the |
-default-customizer=customizer_classname
-default-customizer=sqlj.myutil.MyCustomizer
sqlj.default-customizer=customizer_classname
sqlj.default-customizer=sqlj.myutil.MyCustomizer
oracle.sqlj.runtime.util.OraCustomizer
As with the JVM and compiler, you can pass options directly to the profile customizer harness using a prefix, in this case -P. This is discussed in "Options to Pass to the Profile Customizer (-P)".
Details about these options, both general customization options and Oracle-specific customizer options, are covered in "Customization Options and Choosing a Customizer".
|
 Copyright © 1996-2001, Oracle Corporation. All Rights Reserved. |
|