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.