Translator Command Line and Properties Files

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.

SQLJ Options, Flags, and Prefixes

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

For an example and discussion of command-line syntax and operations, see "Command-Line Syntax and Operations".

Summary of SQLJ Options

Table 8-1 below lists options supported by the SQLJ translator, categorized as follows:

• Flags and options listed as "Basic" are discussed in "Basic Translator Options".

• Flags, options, and prefixes listed as "Advanced" are discussed in "Advanced Translator Options".

• Flags and options listed as "Environment" are discussed in "Translator Support and Options for Alternative Environments". These flags and options are for situations where you are using a non-standard Java VM, compiler, or customizer.

• Options listed as "javac Compatible" are 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".

Table 8-1 SQLJ Translator Options

Option	Description	Default	Category
-C	prefix that marks options to pass to Java compiler	n/a	Advanced
-cache	flag for whether to cache the online semantics-checking results (to reduce trips to database)	false	Advanced
-classpath (command-line only)	option to specify CLASSPATH to Java VM and Java compiler (passed to javac)	none	Basic
-compile	flag to run the Java compilation step (for .java files generated during current SQLJ run, or previously generated .java files specified on the command line)	true	Advanced
-compiler-executable	option to specify the Java compiler to use	javac	Environment
-compiler-encoding-flag	flag to tell SQLJ whether to pass the -encoding setting (if that option is set) to the Java compiler	true	Environment
-compiler-output-file	option to specify a file to which the Java compiler output should be written (There is no default value; however, if this option is not set, SQLJ assumes that compiler output goes to standard output.)	none	Environment
-compiler-pipe-output-flag	flag instructing SQLJ whether to set javac.pipe.output system property, which determines whether the Java compiler outputs errors and messages to STDOUT instead of STDERR	true	Environment
-d	option to set output directory for profile (.ser) files generated by SQLJ and .class files generated by compiler (passed to javac)	empty (use directory of .java file; i.e., use same directory as -dir option)	Basic
-default-customizer	option to specify the profile customizer to use; specify a class name	oracle.sqlj.runtime.util.OraCustomizer	Environment
-default-url-prefix	option to set the default prefix for URL settings	jdbc:oracle:thin:	Basic
-depend (command-line only)	passed to javac only	n/a	javac Compatible
-dir	option to set output directory for SQLJ-generated .java files	empty (use directory of .sqlj input file)	Basic
-driver	option to specify JDBC driver class to register; specify a class name or comma-separated list of class names	oracle.jdbc.driver. OracleDriver	Basic
-encoding (also recognized as -e if on command line)	option to specify NLS encoding for SQLJ and compiler to use (passed to javac)	VM file.encoding setting	Basic
-explain	flag to request "cause" and "action" information to be displayed with translator error messages	false	Basic
-g (command-line only)	passed to javac; enables -linemap	n/a	javac Compatible
-help (also recognized as -h) -help-long -help-alias (all command-line only)	flags to display different levels of information about SQLJ option names, descriptions, and current values	not enabled	Basic
-J (command-line only)	prefix that marks options to pass to the Java VM	n/a	Advanced
-linemap	flag to enable mapping of line numbers between generated Java source code and original SQLJ code	false	Basic
-n (command-line only; alternatively -vm=echo)	flag instructing sqlj script to echo the full command line as it would be passed to the SQLJ translator (including settings in SQLJ_OPTIONS), without having the translator execute it	n/a	Basic
-nowarn (command-line only)	passed to javac; sets -warn=none	n/a	javac Compatible
-O (command-line only)	passed to javac; disables -linemap	n/a	javac Compatible
-offline	option to specify offline checker to use for semantics-checking; specify a fully qualified class name	oracle.sqlj.checker. OracleChecker	Advanced
-online	option to specify online checker to use for semantics-checking; specify a fully qualified class name	oracle.sqlj.checker. OracleChecker	Advanced
-P	prefix that marks options to pass to SQLJ profile customizer	n/a	Advanced
-passes (command-line only)	flag instructing sqlj script to run SQLJ in two separate passes, with compilation in between	false	Environment
-password (also recognized as -p if on command line)	option to set user password for database connection for online semantics-checking	none	Basic
-profile	flag to run the profile customization step (for profile files generated during current SQLJ run)	true	Advanced
-props (command-line only)	option to specify properties file (alternative to command line for setting options); sqlj.properties is also still read	none	Basic
-ser2class	flag to instruct SQLJ to translate generated .ser profiles to .class files	false	Advanced
-status (also recognized as -v if on command line)	flag requesting SQLJ to display status messages as it runs	false	Basic
-url	option to set database URL for connection for online semantics-checking	jdbc:oracle:oci8:@	Basic
-user (also recognized as -u if on command line)	option to enable online semantics-checking and set username (and optionally password and URL) for database connection	none (no online semantics-checking)	Basic
-verbose (command-line only)	passed to javac; enables -status	n/a	javac Compatible
-version -version-long (both command-line only)	flag to display different levels of SQLJ and JDBC driver version information	not enabled	Basic
-vm (command-line only)	option to specify Java VM to use	java	Environment
-warn	comma-separated list of flags to enable or disable various SQLJ warnings--individual flags are precision/noprecision, nulls/nonulls, portable/noportable, strict/nostrict, and verbose/noverbose; global flag is all/none	precision nulls noportable strict noverbose	Basic

Options for loadjava 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.

Options for javac Compatibility

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)

  See "CLASSPATH for Java VM 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)

  See "Line-Mapping to SQLJ Source File (-linemap)".

• -nowarn (instructs javac to generate no warnings; also sets SQLJ -warn=none)

  See "Translator Warnings (-warn)".

• -O (instructs javac to optimize; also sets SQLJ -linemap=false)

  See "Line-Mapping to SQLJ Source File (-linemap)".

• -verbose (instructs javac to output real-time status messages; also sets SQLJ -status=true)

  See "Real-Time Status Messages (-status)".

Profile Customizer Options

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".

Command-Line Syntax and Operations

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.

Use of Command Line Arguments

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.

Arguments from the Option List

Option list arguments are used in the following ways:

• Options designated by the -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.

• Options not designated by the -J, -C, or -P prefixes are SQLJ options and are passed to the SQLJ translator as the Java VM invokes it.

• Options designated by the -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.

• Options designated by the -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".

Arguments from the File List

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.

• profile files (.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.

Processing to Avoid Source Conflicts

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.

Command Line Example and Results

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)".

Echoing the Command Line without Executing

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)".

Properties Files for Option Settings

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:

• Set javac options supported by SQLJ (-depend, -g, -nowarn, -O, -verbose)

• Use option abbreviations that are recognized on the command line for compatibility with loadjava (-e, -h, -p, -u, -v).

Properties File Syntax

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:

• Each SQLJ option is prefixed by 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
  
  

• Each Java compiler option is prefixed by 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.)

• General profile customization options (that apply regardless of the particular customizer you are using) are prefixed by 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".

• Comment lines start with a pound sign (#). For example:

  # Comment line.
  
  

• Blank lines are also permitted.

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

Properties File: Simple Example

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

Properties File: Non-Default Connection Context Classes

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

Default Properties Files

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".

SQLJ_OPTIONS Environment Variable for 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.

Order of Precedence of Option Settings

SQLJ takes option settings in the following order. At each step, it overrides any previous settings for any given option.

1. Sets options to default settings (where applicable).

2. Looks for a sqlj.properties file in the Java home directory; if one is found, options are set as specified there.

3. Looks for a sqlj.properties file in the user home directory; if one is found, options are set as specified there.

4. Looks for a sqlj.properties file in the current directory; if one is found, options are set as specified there.

5. Looks for option settings in the SQLJ_OPTIONS environment variable and effectively prepends them to the beginning of the command line. Sets options as specified in SQLJ_OPTIONS.

6. Looks for option settings on the command line; options are set as specified there. While SQLJ processes the command line, it looks in any file specified by the -props option and sets options as specified there.

Example

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.

---