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 discusses general command-line syntax for the script sqlj that you use to run the SQLJ translator, and lists all of the options available. It then discusses SQLJ properties files, which can be used instead of the command line to set most options, and the SQLJ_OPTIONS environment variable, which can be used in addition to or instead of the command line for setting options. For detailed information about settings for the 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 VM and passes the class name of the SQLJ translator (sqlj.tools.Sqlj) to the VM. The VM invokes the translator and handles things 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 be passed to other executables.
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 .class files it must have for type resolution of variables in your SQLJ source files.
|
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 Java VM, which the SQLJ script invokes, and to the Java compiler and SQLJ profile customizer, which the Java VM 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; simply typing the flag name on the command line 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
|
Notes:
|
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 the Oracle8i server, 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 Oracle8i Java Stored Procedures Developer's Guide.
|
Note:
This alternative option syntax is only recognized on the command line or in the |
For compatibility with javac, the Java compiler provided with the Sun Microsystems JDK, the following javac options are accepted directly by SQLJ without the -C prefix if specified on the command line. As indicated: 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 Java VM)
-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)
-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, both options for the customizer harness front end and for the default Oracle customizer, 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 Java VM, it passes all of its command-line arguments to the VM, 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 prefix are Java VM options and are used by the VM directly. Such options must be specified on the command line or in the SQLJ_OPTIONS environment variable.
-J, -C, or -P prefixes are SQLJ options and are passed to the SQLJ translator as the Java VM invokes it.
-C prefix are Java compiler options and are passed to the compiler as the Java VM invokes it.
Note that there are three SQLJ options that 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 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 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 is passed by SQLJ to both the Java compiler and the Java VM 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 compiler and VM.
-P prefix are SQLJ profile customizer options and are passed to the customizer as the Java VM 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.
In most cases an application requires only one .sqlj file, but you should use additional files if you declare additional public classes, such as iterator and connection context classes.
.java files are processed by the Java compiler and are also used by the SQLJ translator for type resolution.
.ser by default, or optionally .class) 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 handled.)
If you have .sqlj files and .java files with interdependencies (each requiring access to code in the others), you must 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 of the types.
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. Also, 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
This would result in the translator both writing to and reading from Foo.java in the same execution, so the translator discards Foo.java from the command line.
sqlj Foo.*
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. Again, the translator discards Foo.java from the command line.
sqlj -dir=outdir 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.
This processing of the command line means that you can, for example, type the following command and have it execute without difficulty (with files references being automatically discarded as necessary):
sqlj *.sqlj *.java
This may be 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 Java VM, passes the class name of the SQLJ translator to the VM, then passes the command-line arguments to the VM (which later passes them to the translator, compiler, and customizer, as appropriate). If there are any options for the Java VM, as designated by -J, the script passes them to the VM 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 the following (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
(The above is all one line; it just wraps around.)
For more information about how Java VM options are handled, see "Options to Pass to Java VM (-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 "Echo Command Line without Execution (-n)".
You can use properties files instead of the command line to supply options to the SQLJ translator, Java compiler, and SQLJ profile customizer.
In addition, if your Java compiler will be running in a separate Java VM and you want to specify options to this VM regarding operation of the compiler, then you can use properties files to supply such options to this VM. Such options are passed to the VM at the time the compiler is run, after the SQLJ translation step. (It is more typical, however, to pass options to the compiler's VM 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 Java VM, for example, because properties files are read after the VM is invoked.
You also cannot do the following in properties files:
javac options supported by SQLJ (-depend, -g, -nowarn, -O, -verbose)
loadjava (-e, -h, -p, -u, -v).
|
Notes: 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". |
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 handled appropriately.)
Syntax for the various 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.driver.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.driver.OracleDriver -C-verbose
Following is a sample properties file that specifies settings for a connection context class that you declared:
# JDBC driver sqlj.driver=oracle.jdbc.driver.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 Java VM. And it is particularly useful for command-line-only options, such as -classpath, that you may 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 one is found, options are set as specified there.
sqlj.properties file in the user home directory; if one is found, options are set as specified there.
sqlj.properties file in the current directory; if one is found, options are set as specified there.
SQLJ_OPTIONS environment variable and effectively prepends them to the beginning of the command line. 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.
