Oracle8i SQLJ Developer's Guide and Reference
Release 8.1.5

A64684-01

Library

Product

Contents

Index

Prev  Chap Top Next

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.


Notes:

  • Discussion of the SQLJ command line applies only to client-side translation, not server-side translation. There is a different mechanism for specifying options to SQLJ in the server. For information, see "Option Support in the Server Embedded Translator".

  • If you run the script by entering only sqlj, you will receive a synopsis of the most frequently used SQLJ options. In fact, this is true whenever you run the script without specifying any files to process. This is equivalent to using the -help flag setting.

 

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


Notes:

  • The names of command-line options, including options passed elsewhere, are case-sensitive and usually all lowercase. Option values are usually case-sensitive as well.

  • Several options, as indicated in Table 8-1 below, accept alternative syntax if specified on the command line to support compatibility with the Oracle loadjava utility.

  • Several javac options are recognized directly by SQLJ if specified on the command line, as indicated in Table 8-1. All of these are passed to your Java compiler (presumably javac), and some also affect SQLJ operation.

  • Most SQLJ options can also be set in a properties file. See "Properties Files for Option Settings".

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

  • If the same option appears more than once on the command line (or in the properties file), then the last value is used.

  • In this document, boolean flags are usually discussed as being 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".

Summary of SQLJ Options

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

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):

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 SQLJ_OPTIONS environment variable, not in properties files.  


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.

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:

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:

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:

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:

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:


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


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:

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


Note:

Always use the equals sign (=) in your option settings in a properties file, even though some options (such as -user, -password, and -url) allow use of a space instead of "=" on the command line.  


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.


Note:

How to set environment variables is specific to your operating system. There may also be OS-specific restrictions. For example, in Windows 95 you use the Environment tab in the System control panel. Additionally, since Windows 95 does not support the "=" character in variable settings, SQLJ supports the use of "#" instead of "=" in setting SQLJ_OPTIONS. Consult your operating system documentation.  


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.


Notes:

  • In sqlj.properties files, SQLJ reads option settings from top to bottom, with later entries taking precedence over earlier entries.

  • If there is a properties file specified by the -props option on the command line, SQLJ inserts the file's option settings into the position on the command line where the -props option was specified.

  • Options on the command line, with options from a -props file inserted, are read in order from left to right. Any later (right-hand) setting takes precedence over earlier (left-hand) settings.

 

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.




Prev

Top

Next
Oracle
Copyright © 1999 Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index