Release 3 (8.1.7)
Part Number A83723-01
 Library |
 Product |
 Contents |
 Index |
| Oracle8i SQLJ Developer's Guide and Reference Release 3 (8.1.7) Part Number A83723-01 |
|
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 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 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.
The SQLJ translator can also find classes it needs in uncompiled .java files in the CLASSPATH, if you enable the -checksource flag. 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, 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 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 Developer's Guide.
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. 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 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)
-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 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.
-J, -C, or -P prefixes are SQLJ options and are passed to the SQLJ translator as the JVM invokes it.
-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 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 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
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 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 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
(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 supported by SQLJ (-depend, -g, -nowarn, -O, -verbose)
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.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 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 one is found, sets options as specified there.
sqlj.properties file in the user home directory; if one is found, sets options as specified there.
sqlj.properties file in the current directory; if one is found, sets options 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.
|
 Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
|