Oracle9i SQLJ Developer's Guide and Reference
Release 1 (9.0.1)

Part Number A90212-01
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

8
Translator Command Line and Options

Once you have written your source code, you must translate it using the SQLJ translator. This chapter discusses the SQLJ translator command line, options, and properties files.

The following topics are discussed:

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 the options available. It then discusses SQLJ properties files, which you can use instead of the command line to set most options, and the SQLJ_OPTIONS environment variable, which you can use in addition to or instead of the command line for setting options.

For detailed information about settings for 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.


Note:

It is not required that all the options precede the file list. Options may appear anywhere in the command line and are processed in order.

All command-line options apply to all files being translated. It is not possible to have file-specific option settings. 


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.

If the -checksource flag is enabled (its default setting), the SQLJ translator can also find classes it needs in uncompiled .java files in the classpath. See "Source Check for Type Resolution (-checksource)".


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

Notes Regarding Options Flags and Prefixes

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 the Java compiler 

n/a 

Advanced 

-cache 

flag to enable caching of online semantics-checking results (to reduce trips to database) 

false 

Advanced 

-checkfilename 

flag to specify whether a warning is issued during translation if a source file name does not correspond to the name of the public class (if any) defined there 

true 

Environment 

-checksource 

flag to instruct SQLJ type resolution to examine source files in addition to class files in certain circumstances 

true 

Advanced 

-classpath
(command-line only) 

option to specify the classpath to the JVM and Java compiler (passed to javac

none 

Basic 

-codegen 

option to specify type of code generation: iso for standard SQLJ code generation; oracle for Oracle-specific code generation with direct Oracle JDBC calls 

iso 

Basic 

-compile 

flag to enable/disable the Java compilation step (for .java files generated during the 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

(If this option is not set, then SQLJ assumes that compiler output goes to standard output.) 

none 

Environment 

-compiler-pipe-output-flag 

flag instructing SQLJ whether to set the 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 the output directory for profile (.ser) files generated by SQLJ and .class files generated by the compiler (passed to javac

empty (use directory of .java files for .class files; use directory of .sqlj files for .ser files) 

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 the JDBC driver class to register; specify a class name or comma-separated list of class names 

oracle.jdbc.
OracleDriver 

Basic 

-encoding
(also recognized as -e if on command line) 

option to specify the encoding that SQLJ and the compiler will use in globalization support (passed to javac

JVM 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 

-jdblinemap 

variant of -linemap option for use with Sun Microsystems jdb debugger 

false 

Basic 

-J
(command-line only) 

prefix that marks options to pass to the JVM  

n/a 

Advanced 

-linemap 

flag to enable mapping of line numbers between generated Java class file and original SQLJ code 

false 

Basic 

-n
(command-line only; alternatively -vm=echo) 

flag instructing the 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 the offline checker to use for semantics-checking; specify a list of fully qualified class names 

oracle.sqlj.checker.
OracleChecker 

Advanced 

-online 

option to specify the online checker to use for semantics-checking; specify a fully qualified class name (you must also set -user to enable online checking) 

oracle.sqlj.checker.
OracleChecker 

Advanced 

-optcols 

flag to enable iterator column type and size definitions to optimize performance (used with Oracle-specific code generation only, otherwise use equivalent Oracle customizer option) 

false 

Basic 

-optparams 

flag to enable parameter size definitions to optimize JDBC resource allocation (used with -optparamdefaults; used with Oracle-specific code generation only, otherwise use equivalent Oracle customizer options) 

false 

Basic 

-optparamdefaults 

option to set parameter size defaults for particular datatypes (used with -optparams; used with Oracle-specific code generation only, otherwise use equivalent Oracle customizer options) 

false 

Basic 

-P 

prefix that marks options to pass to the SQLJ profile customizer 

n/a 

Advanced 

-passes
(command-line only) 

flag instructing the 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 the user password for the database connection for online semantics-checking 

none 

Basic 

-profile 

flag to enable/disable the profile customization step (for profile files generated during current SQLJ run) 

true 

Advanced 

-props
(command-line only) 

option to specify a properties file (an alternative to the 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 the database URL for the database connection for online semantics-checking 

jdbc:oracle:oci:@ 

Basic 

-user
(also recognized as -u if on command line) 

option to enable online semantics-checking and set the user name (and optionally password and URL) for the 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 JVM to use for running the SQLJ translator 

java 

Environment 

-warn 

comma-separated list of flags to enable or disable different SQLJ warnings; individual flags are cast/nocast precision/noprecision, nulls/nonulls, portable/noportable, strict/nostrict, and verbose/noverbose; global flag is all/none 

cast
precision
nulls
noportable
strict
noverbose 

Basic 

Options for loadjava Compatibility

For compatibility with the loadjava utility used to load Java and SQLJ applications into Oracle9i, 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 Oracle9i Java Tools Reference.


Note:

This alternative option syntax is recognized only 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 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. 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--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".

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

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 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 .java file names on the command line, you can enable the -checksource option and then just be sure that the .java files are in the classpath. See "Source Check for Type Resolution (-checksource)"


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

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.

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 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 in the next example (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)".

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 "Command Line Echo without Execution (-n)".

Properties Files for Option Settings

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:

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:

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 processed appropriately.)

Syntax for the different 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.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.OracleDriver -C-verbose

Properties File: Non-Default Connection Context Classes

Following is a sample properties file that specifies settings for a connection context class SourceContext that you declared:

# JDBC driver
sqlj.driver=oracle.jdbc.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 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.


Note:

How to set environment variables is specific to your operating system. There can 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. It sets options to default settings (where applicable).

  2. It looks for a sqlj.properties file in the Java home directory; if it finds one, it sets options as specified there.

  3. It looks for a sqlj.properties file in the user home directory; if it finds one, it sets options as specified there.

  4. It looks for a sqlj.properties file in the current directory; if it finds one, it sets options as specified there.

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

  6. It looks for option settings on the command line and sets options as specified there. When 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 option settings of the file into the position on the command line where the -props option was specified.

    • SQLJ reads options on the command line, with options from a -props file inserted, 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.

Basic Translator Options

This section documents the syntax and functionality of the basic flags and options you can specify in running SQLJ. These options allow you to run in a fairly standard mode of operation. For options that can also be specified in a properties file (such as sqlj.properties), that syntax is noted as well. (See "Properties Files for Option Settings".)

More advanced command-line flags and options are discussed in "Advanced Translator Options" and "Translator Support and Options for Alternative Environments".

Basic Options for Command Line Only

The following basic options can be specified only on the SQLJ command line or, equivalently, in the SQLJ_OPTIONS environment variable. They cannot be specified in properties files.

The command-line-only flags (the -help flags, -version flags, and -n) do not support =true syntax. Enable them by typing only the flag name, as in the following example:

supported: sqlj -version-long ...

not supported: sqlj -version-long=true ...


Note:

Additionally, there are advanced options, flags, and prefixes that can be set only on the command line or in SQLJ_OPTIONS: -J, -passes, and -vm.  


Input Properties File (-props)

The -props option specifies a properties file from which SQLJ can read option settings (an alternative to specifying option settings on the command line).

See "Properties Files for Option Settings" for information about the format of these files, the details of how they are used in relation to command-line options, and where SQLJ looks for default properties files.

Command-line syntax
-props=filename
Command-line example
-props=myprops.properties
Properties file syntax

n/a

Properties file example

n/a

Default value

none

Classpath for Java Virtual Machine and Compiler (-classpath)

For compatibility with the syntax of most JVMs and compilers, SQLJ recognizes the -classpath option if it is specified on the command line. In setting this option, you can use either a space, as with most JVMs or compilers, or "=", as with other SQLJ options. The following examples (both on Solaris) demonstrate this:

-classpath=.:./classes:/vobs/dbjava/classes/classes111.zip:/jdbc-1.2.zip

or:

-classpath .:./classes:/vobs/dbjava/classes/classes111.zip:/jdbc-1.2.zip

The -classpath option sets the Java classpath for both the JVM and the Java compiler. If you do not want to use the same classpath for both, set them separately using the SQLJ -J and -C prefixes, described in "Prefixes that Pass Option Settings to Other Executables".


Note:

As with other options described later in this chapter, if you do use "=" in setting the -classpath option, then it is stripped out when the option string is passed to the JVM and compiler. This is because JVMs and compilers do not support the "=" syntax in their option settings. 


Command-line syntax
sqlj -classpath=<class_path>
Command-line example
sqlj -classpath=/jdbc-1.2.zip:/classes/bin
Properties file syntax

n/a

Properties file example

n/a

Default value

none

SQLJ Option Information (-help)

The following three settings of the -help flag, specified on the command-line, instruct SQLJ to display varying levels of information about SQLJ options:

You can enable this option by typing the desired setting on the command line as in the following examples:

sqlj -help

or:

sqlj -help-long

or:

sqlj -help-alias

No input-file translation is performed when you use the -help flag in any of these forms, even if you include file names and other options on the command line as well. SQLJ assumes that you either want to run the translator or you want help, but not both.

You can also receive information about the profile customizer or Java compiler, requesting help through the -P and -C prefixes as in the following examples. These prefixes are discussed in "Prefixes that Pass Option Settings to Other Executables". As with the -help flag, no translation is performed if you request customizer or compiler help.

sqlj -P-help

sqlj -C-help

As with other command-line-only flags, -help (as well as -P-help and -C-help) does not support =true syntax. Enable it by typing only the desired flag setting.


Notes:

  • For compatibility with the loadjava utility, -h is recognized as equivalent to -help when specified on the command line. See "Options for loadjava Compatibility".

  • You can use multiple -help flag settings on the same command line, including -P-help and -C-help.

  • Although -P and -C settings can generally be set in properties files, -P-help and -C-help are command-line-only.

  • Help is also provided if you run SQLJ without specifying any files to process. This is equivalent to using the -help setting.

 
The -help Setting

The most basic level of help is achieved by specifying the -help setting. This provides the following:

The -help-long Setting

This setting provides a complete list of SQLJ option information, including the following for each option:

The -help-alias Setting

This setting provides a synopsis of the command-line abbreviations supported for compatibility with the loadjava utility.

Command-line syntax
sqlj help_flag_settings
Command-line examples
sqlj -help
sqlj -help -help-alias
sqlj -help-long
sqlj -warn=none,null -help-long
sqlj -help-alias
Properties file syntax

n/a

Properties file example

n/a

Default value

none

SQLJ Version Number (-version)

The following settings of the -version flag, specified on the command-line, instruct SQLJ to display varying levels of information about SQLJ and JDBC driver versions:

You can enable this option by typing the desired setting on the command line as in the following examples:

sqlj -version

or:

sqlj -version-long

No input-file translation is performed when you use the -version option, even if you include file names and other options on the command line. SQLJ assumes that you either want to run the translator or you want version information, but not both. Properties files and anything else you type on the command line are ignored.

As with other command-line-only flags, -version does not support =true syntax. Enable it by typing only the flag name.

The -version Setting

The -version setting displays the SQLJ release number, such as "Oracle SQLJ 9.0.1".

The -version-long Setting

The -version-long setting displays information about the SQLJ and SQLJ runtime library release and build versions, the JDBC driver release number if one can be found, and the Java environment. For example, if an Oracle JDBC driver is used, this option would display something such as "Oracle JDBC version 9.0 (9.0.1.0)".

This flag offers a good way to check your SQLJ installation and the JDBC and JDK versions you are using.

Command-line syntax
sqlj version_flag_settings
Command-line example
sqlj -version
sqlj -version -version-long
sqlj -version-long
Properties file syntax

n/a

Properties file example

n/a

Default value

none

Command Line Echo without Execution (-n)

The -n flag, specified on the command line, instructs the sqlj script to construct the full command line that would be passed to the SQLJ translator, including any SQLJ_OPTIONS settings, and echo it to the user without having the SQLJ translator execute it. This includes capturing and echoing the name of the JVM that would be launched to execute the SQLJ translator and echoing the full class name of the translator. This does not include settings from properties files.

This is useful in showing you the following:

The -n option can appear anywhere on the command line or in the SQLJ_OPTIONS variable.

As with other command-line-only flags, -n does not support =true syntax. Enable it by typing only the flag name.

Consider the following sample scenario:

You would see the following echo:

java -classpath /myclasses/bin sqlj.tools.Sqlj 
-user=scott/tiger@jdbc:oracle:thin:@ -C-classpath=/myclasses/bin -encoding=SJIS 
myapp.sqlj

(This is all one wrap-around line.)


Note:

  • As an alternative to -n, you can use the -vm=echo setting.

  • Another effective way to check option settings is to use the -help-long flag. This displays current settings for all options, including other options you set on the command line as well as settings in properties files and in SQLJ_OPTIONS. See "SQLJ Option Information (-help)".

 
Command-line syntax
-n
Command-line example
-n
Properties file syntax

n/a

Properties file example

n/a

Default value
false

Options for Output Files and Directories

The following option specifies encoding for SQLJ input and output source files:

These options specify where SQLJ output files are placed:

Encoding for Input and Output Source Files (-encoding)

The -encoding option specifies the encoding to be applied to .sqlj and .java input files and .java generated files for globalization support. For compatibility with javac, you can use either a space or "=" in setting this option on the command line, as in the following examples:

-encoding=SJIS

-encoding SJIS

If setting sqlj.encoding in a properties file, however, use "=", not a space.

When this option is specified, it is also passed to the Java compiler (unless the -compiler-encoding-flag is off), which uses it to specify encoding for .java files processed by the compiler.

Note the following:

Command-line syntax
-encoding=Java_character_encoding
Command-line example
-encoding=SJIS
Properties file syntax
sqlj.encoding=Java_character_encoding
Properties file example
sqlj.encoding=SJIS
Default value

setting in JVM system property file.encoding

Output Directory for Generated .ser and .class Files (-d)

The -d option specifies the root output directory for profiles generated by the SQLJ translator, and is also passed to the Java compiler to specify the root output directory for .class files generated by the compiler. Whether profiles are generated as .ser files (default) or .class files (if the -ser2class option is enabled) is irrelevant in using the -d option. (For information about -ser2class, see "Conversion of .ser File to .class File (-ser2class)".)

Whenever a directory is specified, the output files are generated under this directory according to the package name, if applicable. For example, if you have source files in package a.b.c and specify directory /mydir, output files will be placed in directory /mydir/a/b/c.

If you specify a relative directory path, this will be from your current directory.

For compatibility with javac, you can use either a space or "=" in setting this option on the command line, as in the following examples (both of which make /root the root directory for generated profile files):

-d=/root

-d /root

If setting -d in a properties file, however, use "=", not a space (for example, sqlj.d=/root).

If your current directory is /root/home/mydir and you set the -d option to the relative directory path mysubdir/myothersubdir as follows, then /root/home/mydir/mysubdir/myothersubdir will be the root directory for generated profile files:

-d=mysubdir/myothersubdir

You can also use standard syntax such as a period for the current directory or two periods to go up a level (the second example immediately below will go up a level, then back down to a parallel directory called paralleldir):

-d=.

-d=../paralleldir

If the -d option is empty or not specified, then .class files and .ser files generated by the translation process will be placed as follows:

Command-line syntax
-d=directory_path
Command-line example
-d=/topleveldir/mydir
Properties file syntax
sqlj.d=directory_path
Properties file example
sqlj.d=/topleveldir/mydir
Default value

none (.class files go with .java files; .ser files go with .sqlj files)

Output Directory for Generated .java Files (-dir)

The -dir option specifies the root directory for .java files generated by the SQLJ translator.

Whenever a directory is specified, the output files are generated under this directory according to the package name, if applicable. For example, if you have source files in package a.b.c and specify directory /mydir, then output files will be placed in directory /mydir/a/b/c.

If you specify a relative directory path, it will be from your current directory.

A simple example is as follows, which will make /root the root directory for generated .java files:

-dir=/root

If your current directory is /root/home/mydir and you set the -dir option to the relative directory path mysubdir/myothersubdir as follows:

-dir=mysubdir/myothersubdir

then /root/home/mydir/mysubdir/myothersubdir will be the root directory for generated .java files.

You can also use standard syntax such as a period for the current directory or two periods to go up a level (the second example immediately below will go up a level, then back down to a parallel directory called paralleldir):

-dir=.

-dir=../paralleldir

If the -dir option is not specified, then files are generated under the same directory as the original .sqlj source file (not under the current directory).

If you specifically want the output directory to be the same as your .sqlj source directory (perhaps overriding other -dir settings, such as in properties files), then you can use the -dir option as follows:

-dir=


Notes:

  • If you specify the -dir option but not the -d option, then generated .class files will also be placed in the directory specified by -dir, but generated .ser files will be placed in the directory of the .sqlj file.

  • Throughout this discussion, the forward-slash (/) was used as the file separator. Be aware, however, that in specifying this or similar options, you must use the file separator of your operating system, as specified in the file.separator system property of your JVM.

 
Command-line syntax
-dir=directory_path
Command-line example
-dir=/topleveldir/mydir
Properties file syntax
sqlj.dir=directory_path
Properties file example
sqlj.dir=/topleveldir/mydir
Default value

none (use directory of .sqlj source file)

Connection Options

You can use the following options for the database connection for online semantics-checking:

There is no requirement that the SQLJ translator connect to the same database or schema as the application does at runtime. The connection information in application source code can be independent of the connection information in the SQLJ options.

A situation where you will probably want to use a different connection for translation than for runtime is if you are developing in a different environment than the one to which you will deploy.

Online Semantics-Checking and User Name (-user)

Simple semantics-checking not involving a database connection is referred to as offline checking. The more thorough semantics-checking requiring a connection is referred to as online checking. Online checking offers one of the prime advantages of the SQLJ strong-typing paradigm--type incompatibilities that would normally result in runtime SQL exceptions are caught during translation, before users ever run the application.

The -user option enables online semantics-checking and specifies the user name (schema name) for the exemplar schema, which is the sample database schema that you provide to the translator for it to use in performing the checking. You can also use the -user option to specify the password and URL, as opposed to using the -password and -url options separately.

Note that there is no other flag to enable or disable online semantics-checking; SQLJ enables it or disables it according to the presence or absence of the -user option.

Discussion of the -user option is split into two categories--1) effect of -user when you are employing the default connection context class only; and 2) effect of -user when you are employing non-default or multiple connection context classes. Non-default connection context classes are discussed in "Connection Contexts".

General discussion of connection considerations, such as when to use multiple instances of the DefaultContext class and when to declare additional connection context classes, is in "Connection Considerations".


Notes:

  • For compatibility with the loadjava utility, -u is recognized as equivalent to -user when specified on the command line. See "Options for loadjava Compatibility".

  • User names cannot contain the characters "/" or "@".

  • You are allowed to use a space instead of "=" in a user name setting on the command line, as in the following examples:

    -user scott/tiger
    -user@CtxClass scott/tiger
    -u scott/tiger
    -u@CtxClass scott/tiger
    
    
  • If a password contains the character "@", then you cannot set the password through the -user option. You must use separate -user and -password settings.

  • If your login name is a member of the DBA group, you may have special privilege to connect as SYSDBA to the SYS schema. In this case, you can specify the user name SYS or INTERNAL.

 
Effect of -user When Using Default Connection Context Class Only

The most basic usage of the -user option is as follows:

-user=scott

When you are using only the default connection or other instances of the DefaultContext class, such a setting will apply to all your SQLJ executable statements. This example results in online checking against the scott schema.

You can also specify the password, URL, or both along with the user name, using syntax as in the following examples (with "/" preceding the password and "@" preceding the URL):

-user=scott/tiger

or:

-user=scott@jdbc:oracle:oci:@

or:

-user=scott/tiger@jdbc:oracle:oci:@

Otherwise the URL can be specified through the -url option, and the password can be specified interactively or through the -password option.

You can disable online semantics-checking by setting the -user option to an empty string:

-user=

Again, when you are using only the default connection or other instances of the DefaultContext class, this will apply to all your SQLJ executable statements.

Disabling online semantics-checking is useful, for example, if you have online checking enabled in a properties file but want to override that on the command line, or have it enabled in the default properties file but want to override that in a user-specified properties file (specified using the -props option).

There is also a special user name, URL.CONNECT, which you can use when the URL specifies the user and password as well as the other details of the connection. To see what the URL would look like in such a case, see "Connection URL for Online Semantics-Checking (-url)".

Effect of -user When Using Non-Default or Multiple Connection Context Classes

If you declare and use additional connection context classes in your application, then you can specify -user settings for the testing of SQLJ executable statements that use instances of those classes. Specify a user name for online checking against a particular connection context class (CtxClass, for example) as follows:

-user@CtxClass=scott

This results in online checking against the scott schema for any of your SQLJ executable statements that specify a connection context instance of the class CtxClass.

As with the default connection context class, you can also specify the password or URL in your -user setting for a particular connection context class, as in the following example:

-user@CtxClass=scott/tiger@jdbc:oracle:oci:@

The CtxClass connection context class must be declared in your source code or previously compiled into a .class file. (See "Connection Contexts" for more information.)

Employ the -user option separately for each connection context class for which you want to enable online checking and set a user name; these settings have no influence on each other:

-user@CtxClass1=user1 -user@CtxClass2=user2 -user@CtxClass3=user3

When you are using multiple connection context classes in your application, a -user setting that does not specify a class will apply to the DefaultContext class as well as to all classes for which you do not otherwise specify a -user setting. Presumably, though, you will specify a -user setting for each connection context class, given that different connection context classes are typically intended for use with different sets of SQL objects.

Consider a situation where you have declared connection context classes CtxClass1, CtxClass2, and CtxClass3 and you set -user as follows:

-user@CtxClass2=scott/tiger -user=bill/lion

Any statement in your application that uses an instance of CtxClass2 will be checked against the scott schema. Any statement that uses an instance of DefaultContext, CtxClass1, or CtxClass3 will be checked against the bill schema.

In addition, once you enable online checking by setting the -user option, you can disable online checking for a particular connection context by setting the -user option again with an empty user name for that connection context. For example, consider the following setting:

-user@CtxClass2=

This disables online semantics-checking for any SQLJ executable statements that specify a connection object that is an instance of CtxClass2.

To disable online semantics-checking for the default connection context class and any other connection context classes for which you do not specify a user name:

-user=

Command-line syntax
-user<@conn_context_class>=username</password><@url>
Command-line examples
-user=scott
-user=scott/tiger
-user=scott@jdbc:oracle:oci:@
-user=scott/tiger@jdbc:oracle:oci:@
-user=
-user=URL.CONNECT
-user@CtxClass=scott/tiger
-user@CtxClass=
Properties file syntax
sqlj.user<@conn _context_class>=username</password><@url>
Properties file examples
sqlj.user=scott
sqlj.user=scott/tiger
sqlj.user=scott@jdbc:oracle:oci:@
sqlj.user=scott/tiger@jdbc:oracle:oci:@
sqlj.user=
sqlj.user=URL.CONNECT
sqlj.user@CtxClass=scott/tiger
sqlj.user@CtxClass=
Default value

none (no online semantics-checking)


Note:

Be aware of the difference in format between specifying user, password, and URL in the -user option and specifying them in the -url option. In the -url option, the user name and password are included in the URL, immediately following the JDBC driver type; in the -user option they precede the URL. Also see "Connection URL for Online Semantics-Checking (-url)"


User Password for Online Semantics-Checking (-password)

The -password option specifies the user password for the database connection for online semantics-checking. For the -password setting to be meaningful, the -user option must also be set .

You can also specify the password as part of the -user option setting. See "Online Semantics-Checking and User Name (-user)". Do not use the -password option for a connection context class if you have already set its password in the -user option, which takes precedence.

For the most part, functionality of the -password option parallels that of the -user option. That is, if your application uses only the default connection or other instances of DefaultContext, the next example will set the password for the schema to be used in checking all of your SQLJ statements.

-password=tiger

If you declare and use additional connection context classes, CtxClass1 for example, then you will presumably employ the -user option to specify additional exemplar schemas to use in testing statements that use those connection context classes. Similarly, use the -password option to specify passwords for those schemas, as in the following example:

-password@CtxClass1=tiger

A connection context class without a password setting, either through the -password setting or the -user setting, uses the password setting for the default connection context class. If you set no password for the default connection context class, then SQLJ prompts you interactively for that password. If you also set no password for a user-defined connection context class, then SQLJ prompts you interactively for that password as well. An exception to this discussion is where user name URL.CONNECT is used, as discussed in "Online Semantics-Checking and User Name (-user)". In this case, user name and password are determined from the string specified in the -url setting, and any setting of the -password option is ignored.

You can specifically set an empty password to override other settings of the -password option, such as in a properties file, and be prompted interactively. You can do this for the DefaultContext class or any particular connection context class, as in the following examples:

-password=

or:

-password@CtxClass1=

If you actually want to use an empty password to log in, specify EMPTY.PASSWORD as in the following examples:

-password=EMPTY.PASSWORD

or:

-password@CtxClass2=EMPTY.PASSWORD

The Oracle9i database, however, does not permit an empty password.


Notes:

  • When specified on the command line, -p is recognized as equivalent to -password.

  • You are allowed to use a space instead of "=" in a password setting on the command line, as in the following examples:

    -password tiger
    -password@CtxClass tiger
    -p tiger
    -p@CtxClass tiger
    
 
Command-line syntax
-password<@conn_context_class>=user_password
Command-line examples
-password=tiger
-password=
-password=EMPTY.PASSWORD
-password@CtxClass=tiger
Properties file syntax
sqlj.password<@conn_context_class>=user_password
Properties file examples
sqlj.password=tiger
sqlj.password=
sqlj.password=EMPTY.PASSWORD
sqlj.password@CtxClass=tiger
Default value

none (password for DefaultContext is used, or user is prompted)

Connection URL for Online Semantics-Checking (-url)

The -url option specifies a URL for establishing a database connection for online semantics-checking. As necessary, the URL can include a host name, port number, and Oracle SID.

You can also specify the URL as part of the -user option setting. See "Online Semantics-Checking and User Name (-user)". Do not use the -url option for a connection context class if you have already set its URL in the -user option, which takes precedence.

For the most part, functionality of the -url option parallels that of the -user option. That is, if your application uses only the default connection or other instances of DefaultContext, the following example would set the URL to use for the connection for checking all your SQLJ statements:

-url=jdbc:oracle:oci:@

Or, to include the host name, port number, and SID:

-url=jdbc:oracle:thin:@hostname:1521:orcl

If you do not begin a URL setting with jdbc: then the setting is assumed to be of the form host:port:sid and by default is automatically prefixed with the following:

jdbc:oracle:thin:@

A -url setting of localhost:1521:orcl, for example, results in the following URL:

jdbc:oracle:thin:@localhost:1521:orcl

You can remove or alter this default prefix with the -default-url-prefix option. See "Default URL Prefix (-default-url-prefix)" for more information.

You can specify the user and password in the -url setting, instead of in the -user and -password settings. In such a case, set -user to URL.CONNECT, as follows:

-url=jdbc:oracle:oci:scott/tiger@ -user=URL.CONNECT

If you declare and use additional connection context classes, CtxClass1 for example, you will presumably specify additional exemplar schemas to use in testing statements that use those connection context classes. You can use the -url option to specify URLs for those schemas, as in the following example:

-url@CtxClass1=jdbc:oracle:oci:@

Any connection context class without a URL setting, either through the -url setting or the -user setting, uses the URL setting for the default connection context class, presuming a URL has been set for the default context class.


Notes:

  • Remember that any connection context class with a URL setting must also have a user name setting for online checking to occur.

  • You are allowed to use a space instead of "=" in a URL setting on the command line, as in the following examples:

    -url jdbc:oracle:oci:@
    -url@CtxClass jdbc:oracle:oci:@
    
 
Command-line syntax
-url<@conn_context_class>=URL
Command-line examples
-url=jdbc:oracle:oci:@
-url=jdbc:oracle:thin:@hostname:1521:orcl
-url=jdbc:oracle:oci:scott/tiger@
-url=hostname:1521:orcl
-url@CtxClass=jdbc:oracle:oci:@
Properties file syntax
sqlj.url<@conn_context_class>=URL
Properties file examples
sqlj.url=jdbc:oracle:oci:@
sqlj.url=jdbc:oracle:thin:@hostname:1521:orcl
sqlj.url=jdbc:oracle:oci:scott/tiger@
sqlj.url=hostname:1521:orcl
sqlj.url@CtxClass=jdbc:oracle:oci:@
Default value
jdbc:oracle:oci:@


Note:

Be aware of the difference in format between specifying user, password, and URL in the -user option and specifying them in the -url option. (In the -url option, the user name and password are included in the URL, immediately following the JDBC driver type; in the -user option they precede the URL.) Also see "Online Semantics-Checking and User Name (-user)"


Default URL Prefix (-default-url-prefix)

Use the -default-url-prefix option to alter or remove the default prefix.

The following is the default prefix for any URL setting you specify that does not already start with jdbc:

jdbc:oracle:thin:@

This allows you to use a shorthand in specifying a URL setting, either in the -user option or the -url option--it is permissible to specify only the host, port, and SID of the database. As an example, presume you set a URL as follows:

-url=myhost:1521:orcl

or:

-user=scott/tiger@myhost:1521:orcl

By default, the URL will be interpreted to be the following:

jdbc:oracle:thin:@myhost:1521:orcl

If you specify a full URL that starts with jdbc:, then the default prefix will not be used, such as in the following example:

-url=jdbc:oracle:oci:@orcl

However, if you want your URL settings to default to the OCI driver, for example, instead of the Thin driver, then set the default prefix as follows:

-default-url-prefix=jdbc:oracle:oci:@

With this prefix, a setting of -url=orcl is equivalent to the -url=jdbc:oracle:oci:@orcl setting above.

If you do not want any prefix, then set the -default-url-prefix option to an empty string, as follows:

-default-url-prefix=

Command-line syntax
-default-url-prefix=url_prefix
Command-line examples
-default-url-prefix=jdbc:oracle:oci:@
-default-url-prefix=
Properties file syntax
sqlj.default-url-prefix=url_prefix
Properties file examples
sqlj.default-url-prefix=jdbc:oracle:oci:@
sqlj.default-url-prefix=
Default value
jdbc:oracle:thin:@

JDBC Drivers to Register for Online Semantics-Checking (-driver)

The -driver option specifies the JDBC driver class to register for interpreting JDBC connection URLs for online semantics-checking. Specify a driver class or comma-separated list of classes.

The default, OracleDriver, supports the Oracle OCI, Thin, and server-side JDBC drivers for use with Oracle9i.

Command-line syntax
-driver=driver1<,driver2,driver3,...>
Command-line examples
-driver=oracle.jdbc.OracleDriver
-driver=oracle.jdbc.OracleDriver,sun.jdbc.odbc.JdbcOdbcDriver
Properties file syntax
sqlj.driver=driver1<,driver2,driver3,...>
Properties file examples
sqlj.driver=oracle.jdbc.OracleDriver
sqlj.driver=oracle.jdbc.OracleDriver,sun.jdbc.odbc.JdbcOdbcDriver
Default value
oracle.jdbc.OracleDriver

Reporting and Line-Mapping Options

The following options specify what types of conditions SQLJ should monitor, whether to generate real-time error and status messages, and whether to include "cause" and "action" information with translator error messages:

The following options enable line-mapping from the generated Java .class file back to the .sqlj source file, so that you can trace runtime errors back to the appropriate location in your original source code. Use -jdblinemap in conjunction with the Sun Microsystems jdb debugger; otherwise use -linemap.

Translator Warnings (-warn)

There are various warnings and informational messages that the SQLJ translator can display as dictated by conditions it encounters during the translation. The -warn option consists of a set of flags that specify which of those warnings and messages should be displayed (in other words, which conditions should be monitored and which should be ignored).

All the flags for this option must be combined into a single, comma-separated string.

Table 8-2 documents the conditions that can be tested, what the true and false flag values are for each condition, what a true flag value means, and which value is the default.

Table 8-2 Tests and Flags for SQLJ Warnings  
Tests and Flag Functions  TRUE/FALSE Values 

Test for requirement of subtypes of declared object type in an inheritance hierarchy--Enable cast to receive warnings when usage of SQL object types in a SQL inheritance hierarchy requires that subtypes of a declared type must be passed at runtime. 

cast (default)

nocast 

Data precision test--Enable precision to receive warnings if there was a possible loss of precision when moving values from database columns to Java host variables. 

precision (default)

noprecision 

Conversion loss test for nullable data--Enable nulls to receive warnings if there was possible conversion loss when moving nullable columns or nullable Java types from database columns to Java host variables. 

nulls (default)

nonulls 

Portability test--Enable portable to check SQLJ clauses for portability and receive warnings if there are non-portable clauses. (Where non-portable refers to the use of extensions to the SQLJ standard, such as vendor-specific types or features.) 

portable

noportable (default) 

Strict matching test for named iterators--Enable strict to instruct SQLJ to require that the number of columns selected from the database must equal the number of columns in the named iterator being populated. A warning is issued for any column in the database cursor for which there is no corresponding column in the iterator. The nostrict setting allows more (but not fewer) columns in the database cursor; unmatched columns are ignored.  

strict (default)

nostrict 

Translation-time informational messages--Enable verbose to provide additional informational messages about the translation process (such as what database connections were made for online checking). 

verbose

noverbose (default) 

Global enabling/disabling of warnings--Use all or none to enable or disable all warnings. 

all

none 

The verbose/noverbose flag works differently from the others. It does not enable a particular test but enables output of general informational messages about the semantics-checking.


Note:

Do not confuse -warn=verbose with the -status flag. The -status flag provides real-time informational messages about all aspects of SQLJ translation--translation, semantics-checking, compilation, and profile customization. The -warn=verbose flag results in additional reporting about the translation phase only. 


The global all/none flag takes priority over default settings. You can use it to enable or disable all flags, or to serve as an initialization to make sure all flags are off before you turn selected flags on, or the converse.

The all setting is equivalent to the following:

cast,precision,nulls,portable,strict,verbose

And the none setting is equivalent to the following:

nocast,noprecision,nonulls,noportable,nostrict,noverbose

There is no default for all/none; there are only defaults for individual flags.

For example, use the following sequence to make sure only the nulls flag is on:

-warn=none,nulls

And the following sequence will have the same result, because the verbose setting will be overridden:

-warn=verbose,none,nulls

Or use the following to make sure everything except the portability flag is on:

-warn=all,noportable

And the following sequence will have the same result, because the nonulls setting will be overridden:

-warn=nonulls,all,noportable

Other than placement of the all/none flag, the order in which flags appear in a -warn setting is unimportant, except in the case of conflicting settings. If there are conflicts--such as in -warn=portable,noportable--then the last (right-most) setting is used.

Separate settings of the -warn option in properties files and on the command line are not cumulative. Only the last setting is processed. In the following example, the -warn=portable setting is ignored--that flag and all other flags besides nulls/nonulls are set according to their defaults:

-warn=portable -warn=nonulls


Note:

The cast, precision, nullability, and strictness tests are part of online semantics-checking and require a database connection. 


Command-line syntax
-warn=comma-separated_list_of_flags
Command-line example
-warn=none,nulls,precision
Properties file syntax
sqlj.warn=comma-separated_list_of_flags
Properties file example
sqlj.warn=none,nulls,precision
Default values
cast,precision,nulls,noportable,strict,noverbose

Real-Time Status Messages (-status)

The -status flag instructs SQLJ to output additional status messages throughout all aspects of the SQLJ process--translation, semantics-checking, compilation, and customization. Messages are output as each file is processed and at each stage of SQLJ operation.


Notes:

  • Do not confuse -warn=verbose with the -status flag. The -status flag provides real-time informational messages about all aspects of SQLJ translation. The -warn=verbose flag results in additional reporting about the translation phase only.

  • For compatibility with the loadjava utility, -v is recognized as equivalent to -status when specified on the command line. See "Options for loadjava Compatibility".

 
Command-line syntax
-status=true/false
Command-line example
-status=true
Properties file syntax
sqlj.status=true/false
Properties file example
sqlj.status=false
Default value
false

Cause and Action for Translator Errors (-explain)

The -explain flag instructs the SQLJ translator to include "cause" and "action" information (as available) with translator error message output (for the first occurrence of each error).

This is the same information provided in "Translation Time Messages", starting.

Command-line syntax
-explain=true/false
Command-line example
-explain=true
Properties file syntax
sqlj.explain=true/false
Properties file example
sqlj.explain=false
Default value
false

Line-Mapping to SQLJ Source File (-linemap)

The -linemap flag instructs SQLJ to map line numbers from a SQLJ source code file to locations in the corresponding .class file. (This will be the .class file created during compilation of the .java file generated by the SQLJ translator.) As a result, when Java runtime errors occur, the line number reported by the JVM is the line number in the SQLJ source code, making it much easier to debug.

Normally, the instructions in a .class file map to source code lines in the corresponding .java file. This would be of limited use to SQLJ developers, though, as they would still need to map line numbers in the generated .java file to line numbers in their original .sqlj file.

The SQLJ translator modifies the .class file to implement the -linemap option, replacing line numbers and the file name from the generated .java file with corresponding line numbers and the file name from the original .sqlj file. This process is known as instrumenting the class file.

In performing this, SQLJ takes the following into account:

Command-line syntax
-linemap=true/false
Command-line example
-linemap=true
Properties file syntax
sqlj.linemap=true/false
Properties file example
sqlj.linemap=false
Default value
false

Line-Mapping to SQLJ Source File for jdb Debugger (-jdblinemap)

This option is equivalent to the -linemap option (discussed in the preceding section), but you should use it instead of -linemap if you are using the jdb debugger provided with the Sun Microsystems JDK.

This is because jdb can access only source files with a .java file name extension. With the -jdblinemap setting, SQLJ does the following:

In this way, the SQLJ source code is accessible to jdb.

Command-line syntax
-jdblinemap=true/false
Command-line example
-jdblinemap=true
Properties file syntax
sqlj.jdblinemap=true/false
Properties file example
sqlj.jdblinemap=false
Default value
false

Options for Code Generation, Column Optimizations, and Parameter Optimizations

Oracle9i SQLJ allows Oracle-specific code generation, which generates Oracle JDBC code directly, as an alternative to standard SQLJ code generation. With Oracle-specific code generation, no profiles are generated, and the SQLJ runtime is largely bypassed during code execution.

Because profile customization is not applicable with Oracle-specific code generation, some generally useful optimization options, formerly available only through the Oracle customizer, are now available directly through the SQLJ translator.

This section describes these code generation and optimization options:

Code Generation (-codegen)

Oracle SQLJ offers the alternative of generating Oracle JDBC code directly instead of generating standard code that calls the SQLJ runtime (which in turn contains calls to Oracle JDBC). With Oracle-specific code generation, there are no profile files, and the SQLJ runtime is largely bypassed during program execution.

Use the SQLJ translator -codegen option to specify Oracle-specific code generation, as follows:

-codegen=oracle

The default is standard SQLJ code generation, but you can also explicitly specify this as follows:

-codegen=iso

See "Oracle-Specific Code Generation (No Profiles)" for information about advantages, disadvantages, limitations, and special considerations regarding Oracle-specific code generation.


Note:

If an application compiles under both JDK 1.1.x and JDK 1.2.x and is translated with the -codegen=oracle setting, and if JDK 1.2.x was used to compile it, then the application will likely not run under JDK 1.1.x. You should use JDK 1.1.x to compile an application that will run under 1.1.x. 


Command-line syntax
-codegen=iso/oracle
Command-line example
-codegen=oracle
Properties file syntax
sqlj.codegen=iso/oracle
Properties file example
sqlj.codegen=oracle
Default value
iso

Column Definitions (-optcols)

For Oracle-specific code generation, use the SQLJ translator -optcols flag to instruct the translator to determine types and sizes of iterator or result set columns. This enables registration of the columns with the Oracle JDBC driver when your application runs, saving round trips to Oracle9i depending on the particular driver implementation. Specifically, this is effective for the Thin driver and positional iterators.

For an overview of column definitions, see "Column Definitions".


Note:

For standard SQLJ code generation, use the Oracle customizer optcols option instead. See "Oracle Customizer Column Definition Option (optcols)"


You can enable or disable this flag on the SQLJ command line or in a properties file.

Enable it on the command line as follows:

-optcols

or:

-optcols=true

This flag is disabled by default, but you can also disable it explicitly. Disable it on the command line as follows:

-optcols=false

Column definitions require a database connection for examination of the columns of tables being queried, so the SQLJ translator -user, -password, and -url options must also be set appropriately. For example:

sqlj -user=scott/tiger@jdbc:oracle:oci:@ -optcols MyApp.sqlj


Notes:

  • Because definitions are done for all columns that you select, it is advisable in your SQL operations to explicitly select the columns you will use, rather than using a SELECT * where you might not actually use all the columns selected. A situation where you select more than you need exposes you to a greater risk of runtime errors if any changes were made to the table between customization and runtime, especially when you have customized with column definitions. You might want to translate with the SQLJ -warn=strict flag set, which will warn you if additional (unwanted) columns will be selected by your query.

  • Column definitions are not possible for any iterator or result set that includes one or more object or collection columns.

  • An error will be generated if you enable the -optcols option without setting the user name, password, and URL for a database connection.

  • The translator does not have to connect to the same schema or even the same database that your application will connect to at runtime, but the relevant columns will have to be in the same order and of identical types and sizes to avoid runtime errors.

 
Command-line syntax
-optcols<=true/false>
Command-line example
-optcols
Properties file syntax
profile.optcols<=true/false>
Properties file example
profile.optcols
Default value
false

Parameter Definitions (-optparams)

For Oracle-specific code generation, use the SQLJ translator -optparams flag to enable parameter size definitions. If this flag is enabled, SQLJ will register your input and output parameters (host variables) to optimize JDBC resource allocations according to sizes you specify, with the following precedence:

  1. size specified in a source code hint, if any

  2. default size, if any, specified for the corresponding datatype in the -optparamdefaults option setting

If there is no source code hint or default datatype size for a given host variable, then resource allocation is left to JDBC.

For an overview of parameter size definitions and a discussion of source code hints, see "Parameter Size Definitions".


Note:

For standard SQLJ code generation, use the Oracle customizer optparams option instead. See "Oracle Customizer Parameter Definition Option (optparams)"


You can enable or disable the -optparams flag on the command line or in a SQLJ properties file.

Enable it on the command line as follows:

-optparams

or:

-optparams=true

This flag is disabled by default, but you can also disable it explicitly. Disable it on the command line as follows:

-optparams=false


Note:

Unlike the -optcols option, the -optparams option does not require a database connection, because you are providing the size specifications yourself. 


Following is a command-line example (omitting a setting for the -optparamdefaults option, which is discussed in the next section):

sqlj -optparams -optparamdefaults=defaults-string MyApp.sqlj

Command-line syntax
-optparams<=true/false>
Command-line example
-optparams
Properties file syntax
profile.optparams<=true/false>
Properties file example
profile.optparams
Default value
false

Parameter Default Size (-optparamdefaults)

If you enable the -optparams option to set parameter sizes, use the -optparamdefaults option as desired to set default sizes for specified datatypes. If -optparams is not enabled, then any -optparamdefaults setting is ignored.

If a host variable has a source code hint to specify its size, that takes precedence over the corresponding datatype default size set with this option. If there is no source code hint or corresponding datatype default size for a particular host variable, then resource allocation for that variable is determined by the JDBC driver, just as it would be if -optparams were not enabled.

There is no requirement to use the -optparamdefaults option, although it is typically used whenever -optparams is enabled. If -optparams is enabled and there are no default size settings, then resources are allocated either according to source code hints (if any) or according to the JDBC driver.

For an overview of parameter size definitions and a discussion of source code hints, see "Parameter Size Definitions".


Note:

For standard SQLJ code generation, use the Oracle customizer optparamdefaults option instead. See "Oracle Customizer Parameter Default Size Option (optparamdefaults)"


You can set the -optparamdefaults flag on the command line or in a SQLJ properties file.

Set it on the command line as follows:

-optparamdefaults=datatype1(size1),datatype2(size2),...

All sizes are in bytes. Do not include any white space. Use empty parentheses for a null setting.

For example, the following will set sizes of 30 bytes for VARCHAR2 and 1000 bytes for RAW, and will specify a null size setting for CHAR. So for any host variable corresponding to the CHAR datatype, if there is no source code hint, then the JDBC driver is left to allocate the resources.

-optparamdefaults=VARCHAR2(30),RAW(1000),CHAR()

The -optparamdefaults option recognizes the following datatype names:

The -optparamdefaults option also recognizes group names and wildcards, as follows:

The -optparamdefaults setting is processed from left to right. When using group names or wildcards, you can override a group setting for particular datatypes.

The following example sets a general default size of 50 bytes, overrides that with a setting of 500 bytes for raw types, then overrides the raw type group setting with a null setting for VARBINARY (leaving that to JDBC for corresponding host variables with no source code hints):

-optparamdefaults=%(50),RAW_TYPE(500),VARBINARY()

Following is a command-line example, including the -optparams setting as well:

sqlj -optparams -optparamdefaults=CHAR_TYPE(50),RAW_TYPE(500),CHAR(10) MyApp.sqlj


Note:

If at runtime the actual size exceeds the registered size of any parameter, runtime errors will occur. 


Command-line syntax
-optparamdefaults=defaults-string
Command-line example
-optparamdefaults=VAR%(50),LONG%(500),RAW_TYPE()
Properties file syntax
profile.optparamdefaults=defaults-string
Properties file example
profile.optparamdefaults=VAR%(50),LONG%(500),RAW_TYPE()
Default value
null

Advanced Translator Options

This section documents the syntax and functionality of the advanced flags and options you can specify in running SQLJ, as well as prefixes employed to pass options to the JVM, Java compiler, or SQLJ profile customizer. These options allow you to exercise any of the specialized features of Oracle SQLJ. For options that can also be specified in a properties file (such as sqlj.properties), that syntax is noted as well. (See "Properties Files for Option Settings" for more information.)

Additional advanced options, intended specifically for situations where you are using alternative Java environments, are discussed in "Translator Support and Options for Alternative Environments". More basic command line flags and options are discussed in "Basic Translator Options".

Prefixes that Pass Option Settings to Other Executables

The following flags mark options to be passed to the Java interpreter, Java compiler, and SQLJ profile customizer:

Options to Pass to the Java Virtual Machine (-J)

The -J prefix, specified on the command line, marks options to be passed to the JVM from which SQLJ was invoked. This prefix immediately precedes a JVM option, with no spaces in between. After stripping off the -J prefix, the sqlj script passes the Java option to the JVM.

For example:

-J-Duser.language=ja

After stripping the -J prefix, the sqlj script passes the -Duser.language argument as is to the JVM. In the Sun Microsystems JDK, the flag -Duser.language=ja sets the system property user.language to the value ja (Japanese), but specific flags are dependent on the actual Java executable you are using and are not interpreted or acted upon by the sqlj script in any way.

You cannot pass options to the JVM from a properties file, because properties files are read after the JVM is invoked.


Notes:

  • While it is not possible to use a properties file to pass options directly to the JVM in which the SQLJ translator runs, it is possible to use the SQLJ_OPTIONS environment variable for this purpose. See "SQLJ_OPTIONS Environment Variable for Option Settings". It is also possible (if applicable) to use a properties file to pass options to the JVM in which the Java compiler runs. See "Options to Pass to the Java Compiler (-C)" for information.

  • The JVM file.encoding setting does not apply to Java properties files--sqlj.properties and connect.properties, for example. Properties files always use the encoding 8859_1. This is a feature of Java in general, not SQLJ in particular. You can, however, use Unicode escape sequences in a properties file. (You can use the native2ascii utility to determine escape sequences--see "Using native2ascii for Source File Encoding".)

 
Command-line syntax
-J-Java_option
Command-line example
-J-Duser.language=ja
Properties file syntax

n/a

Properties file example

n/a

Default value

n/a

Options to Pass to the Java Compiler (-C)

The -C prefix marks options to pass to the Java compiler invoked from the sqlj script. This prefix immediately precedes a Java compiler option, with no spaces in between. After stripping off the -C prefix, the sqlj script passes the compiler option to the Java compiler (typically, but not necessarily, javac).

For example:

-C-nowarn

After stripping the -C prefix, the sqlj script passes the -nowarn argument as is to the compiler. (The -nowarn flag is a javac option to suppress warning messages during compilation.)

One Java compiler option, -classpath, is slightly modified when it is passed to the compiler. All other compiler options are passed without change. (Note that if you want the same classpath setting for the JVM and compiler, then you can use the SQLJ -classpath option, instead of -J-classpath and -C-classpath.)

Specify the classpath setting to the Java compiler, using the following syntax:

-C-classpath=path

For example:

-C-classpath=/user/jdk/bin

The equals sign is necessary for SQLJ parsing but is automatically replaced with a space when the option is passed to the Java compiler. After the -C is stripped off and the equals sign is replaced, the option is passed to the compiler as follows:

-classpath /user/jdk/bin

If the Java compiler runs in its own JVM, then you can pass options to that JVM through the compiler. Accomplish this by prefixing the JVM option with -C-J with no spaces between this prefix combination and the option.

For example:

-C-J-Duser.language=de

Observe the following restrictions in using the -C prefix:

Command-line syntax
-C-Java_compiler_option
Command-line example
-C-nowarn
Properties file syntax
compile.Java_compiler_option
Properties file example
compile.nowarn
Default value

n/a

Options to Pass to the Profile Customizer (-P)

During the customization phase, the sqlj script invokes a front-end customizer harness, which coordinates the customization and runs your particular customizer. The -P prefix marks options for customization, as follows:

The -P and -P-C prefixes immediately precede a customizer option, with no spaces in between. After stripping off the prefix, the sqlj script passes the customizer option as is to the profile customizer.

One use of the -P prefix is to override the default customizer determined by the SQLJ -default-customizer option, as follows:

-P-customizer=your_customizer_class

Example of generic option:

-P-backup

The -backup flag is a generic customizer option to backup the previous customization before generating a new one.

Here is an example of a vendor-specific customizer option (in this case, Oracle-specific):

-P-Csummary

(The summary flag is an Oracle customizer option that prints a summary of the customizations performed.)


Notes:

  • Note that there is no hyphen between "-P-C" and a vendor-specific customizer option. With other prefixes and prefix combinations, there is a hyphen between the prefix and the option.

  • The customizer help option (-P-help) can be specified only on the command line or in the SQLJ_OPTIONS variable, not in a properties file. As with the SQLJ -help option, no translation will be done. This is true even if you also specify files to process. (SQLJ assumes that you want help or you want translation, but not both.)

  • If you specify customization options but turn off customization for .sqlj files (and have no .ser files on the command line), then the customization options are silently ignored.

  • The -P prefix is not applicable for Oracle-specific code generation (-codegen=oracle), where no profiles are produced and so no customization is performed.

 

For information about available generic and Oracle-specific customizer options, see "Customization Options and Choosing a Customizer".

Command-line syntax
-P-<C>profile_customizer_option
Command-line examples
-P-driver=oracle.jdbc.OracleDriver
-P-Csummary
Properties file syntax
profile.<C>profile_customizer_option
Properties file example
profile.driver=oracle.jdbc.OracleDriver
profile.Csummary
Default value

n/a

Flags for Special Processing

As mentioned above, .sqlj files are typically processed by the SQLJ translator, Java compiler, and SQLJ profile customizer. The following flags limit this processing, directing the SQLJ startup script to skip the indicated process:

The following flag instructs SQLJ to convert profiles from serialized resource (.ser) files to class files after customization:

The following flag instructs SQLJ type resolution, in certain circumstances, to examine source files as well as class files or files specified on the SQLJ command line:

Compilation Flag (-compile)

The -compile flag enables or disables processing of .java files by the compiler. This applies both to generated .java files and to .java files specified on the command line. This flag is useful, for example, if you want to compile .java files later using a compiler other than javac. The flag is true by default; setting it to false disables compilation.

When you process a .sqlj file with -compile=false, you are responsible for compiling and customizing it later as necessary.

Setting -compile=false also implicitly sets -profile=false. In other words, whenever -compile is false, both compilation and customization are skipped. If you set -compile=false and -profile=true, then your -profile setting is ignored.


Notes:

There are situations where it is sensible for -compile to be set to false even when .java files must be accessed for type resolution. You might do this, for example, if you are translating a .sqlj file, the translator will need one or more .java files for type resolution during translation, but you want to compile all your .java files later using a particular compiler.

(An example of a situation where .java files must be accessed for type resolution is if you are using Oracle9i objects in your SQLJ application and using the Oracle JPublisher utility to map these objects to custom Java types. The .java files produced by JPublisher must be available to the SQLJ translator for type resolution during translation. See "Compiling Custom Java Classes" for more information.) 


Command-line syntax
-compile=true/false
Command-line example
-compile=false
Properties file syntax
sqlj.compile=true/false
Properties file example
sqlj.compile=false
Default value

true (compile)

Profile Customization Flag (-profile)

The -profile flag enables or disables processing of generated profile (.ser) files by the SQLJ profile customizer. However, this applies only to .ser files generated by the SQLJ translator from .sqlj files that you specify on the current command line; it does not apply to previously generated .ser files (or to .jar files) that you specify on the command line. The flag is true by default; setting it to false disables customization.

This option behaves differently from the -compile option for files specified on the command line. Any .ser and .jar files specified on the command line are still customized if -profile=false; however, .java files specified on the command line are not compiled if -compile=false. The reason for this is that you might want other operations, such as line mapping, to be performed on a .java file. There are, however, no other operations that can be performed on a .ser or .jar file specified on the command line.

When you process a .sqlj file with -profile=false, you are responsible for customizing it later, as necessary.


Notes:

  • Set this option to false if you do not want your application to require the Oracle SQLJ runtime and an Oracle JDBC driver when it runs. (Or specify a non-default customizer, using the -default-customizer option.) If no customization is performed, then the generic SQLJ runtime will be used when your application runs.

  • Setting -compile=false also implicitly sets -profile=false. In other words, whenever -compile is false, both compilation and customization are skipped. If you set -compile=false and -profile=true, then your -profile setting is ignored.

  • This option is not applicable for Oracle-specific code generation (-codegen=oracle), where no profiles are produced and so no customization is performed.

 
Command-line syntax
-profile=true/false
Command-line example
-profile=false
Properties file syntax
sqlj.profile=true/false
Properties file example
sqlj.profile=false
Default value

true (customize)

Conversion of .ser File to .class File (-ser2class)

With standard SQLJ code generation, the -ser2class flag instructs SQLJ to convert generated .ser files to .class files. This is necessary if you are using SQLJ to create an applet that will be run from a browser that does not support resource file names with the .ser suffix. (This is true of Netscape Navigator 4.x, for example.)

This also simplifies the naming of schema objects for your profiles in situations where you are translating a SQLJ program on a client and then loading classes and resource files into the server. Loaded class schema objects have a simpler naming convention than loaded resource schema objects. (This is discussed in "Loaded Class and Resource Schema Objects".)

The conversion is performed after profile customization so that it includes your customizations.

The base names of converted files are identical to those of the original files; the only difference in the file name is .ser being replaced by .class. For example:

Foo_SJProfile0.ser

is converted to:

Foo_SJProfile0.class


Notes:

  • The original .ser file is not saved.

  • Once a profile has been converted to a .class file, it cannot be further customized. You would have to delete the .class file and rerun SQLJ to recreate the profile.

  • Where encoding is necessary, the -ser2class option always uses 8859_1 encoding, ignoring the SQLJ -encoding setting.

  • If you use Oracle-specific code generation (-codegen=oracle), then no profiles are produced and the -ser2class option is irrelevant. In fact, you may prefer to use Oracle-specific code generation (presuming you use the SQLJ library runtime11 or runtime12 library) if your motivation is to eliminate .ser files.

 
Command-line syntax
-ser2class=true/false
Command-line example
-ser2class=true
Properties file syntax
sqlj.ser2class=true/false
Properties file example
sqlj.ser2class=false
Default value
false

Source Check for Type Resolution (-checksource)

It may not be sufficient for the SQLJ type resolution process to examine only class files in the classpath and class or source files specified on the SQLJ command line. The -checksource flag instructs SQLJ to also examine source files in the classpath under the following circumstances:

Command-line syntax
-checksource=true/false
Command-line example
-checksource=true
Properties file syntax
sqlj.checksource=true/false
Properties file example
sqlj.checksource=false
Default value
true

Semantics-Checking Options

The following options specify characteristics of online and offline semantics-checking:

Discussion of these options is preceded by a discussion of OracleChecker--the default front-end class for semantics-checking--and an introduction to the Oracle semantics-checkers.

Semantics-Checkers and the OracleChecker Front End (default checker)

The default checker is oracle.sqlj.checker.OracleChecker (for both online and offline checking). This class acts as a front end and runs the appropriate semantics-checker, depending on your environment and whether you choose offline or online checking.

For Oracle, there are the following categories of checkers (for both online and offline checking):

The Oracle80 and Oracle7 checkers are incompatible with the Oracle8i and Oracle9i JDBC drivers, and the Oracle8 and Oracle8To7 checkers are incompatible with the Oracle 8.0.x and Oracle 7.3.x JDBC drivers. The Oracle8To7 checkers were created so that there is a way to use an Oracle8i or Oracle9i JDBC driver and check against an Oracle 7.3.x subset of types.

Online Checking with Oracle Database and JDBC Driver

If you are using an Oracle database (or perhaps the middle-tier database cache) and Oracle JDBC driver with online checking, then OracleChecker will choose a checker based on the lower of your database version and JDBC driver version. Table 8-3 summarizes the choices for the possible combinations of database version and driver version, and also notes any other Oracle checkers that would be legal.

Table 8-3 Oracle Online Semantics-Checkers Chosen by OracleChecker  
Database Version  JDBC Version  Chosen Online Checker  Other Legal Online Checkers 

Oracle9i, 8i, or 8.0.x 

Oracle9i or 8i 

Oracle8JdbcChecker 

Oracle8To7JdbcChecker 

Oracle9i, 8i, or 8.0.x 

Oracle 8.0.x 

Oracle80JdbcChecker 

Oracle7JdbcChecker 

Oracle9i, 8i, or 8.0.x 

Oracle 7.3.x 

Oracle7JdbcChecker 

none 

Oracle 7.3.x 

Oracle9i or 8i 

Oracle8To7JdbcChecker 

none 

Oracle 7.3.x 

Oracle 8.0.x 

Oracle7JdbcChecker 

none 

Oracle 7.3.x 

Oracle 7.3.x 

Oracle7JdbcChecker 

none 

Offline Checking with Oracle JDBC Driver

If you are using an Oracle JDBC driver with offline checking, then OracleChecker will choose a checker based on your JDBC driver version. Table 8-4 summarizes the possible choices. (Note that there is an Oracle8To7OfflineChecker, but it can be used only by selecting it manually.)

Table 8-4 Oracle Offline Semantics-Checkers Chosen by OracleChecker  
JDBC Version  Chosen Offline Checker  Other Legal Offline Checkers 

Oracle9i or 8i 

Oracle8OfflineChecker 

Oracle8To7OfflineChecker 

Oracle 8.0.x 

Oracle80OfflineChecker 

Oracle7OfflineChecker 

Oracle 7.3.x 

Oracle7OfflineChecker 

none 

Not Using Oracle Database and JDBC Driver

If OracleChecker detects that you do not use an Oracle JDBC driver, then it runs one of the following checkers:

Offline Semantics-Checker (-offline)

The -offline option specifies a Java class that implements the semantics-checking component of SQLJ for offline checking. With offline checking, there is no database connection--only SQL syntax and usage of Java types is checked. (For information about what offline and online semantics-checkers accomplish and how they function, see "Semantics-Checking".)

Note that offline checking is neither enabled nor disabled by the -offline option. Offline checking runs only when online checking does not--either because online checking is not enabled or because the database connection cannot be established.

You can specify different offline checkers for different connection contexts, with a limit of one checker per context (do not list multiple offline checkers for one connection context).

The default OracleChecker, a front-end class discussed in "Semantics-Checkers and the OracleChecker Front End (default checker)", will serve your needs unless you want to specify a particular checker that would not be chosen by OracleChecker. For example, you might run offline checking on a machine with an Oracle 8.0 JDBC driver, but your application (or at least statements using a particular connection context class) will run against an Oracle 7.3 database. In this case you will want to check these statements using the Oracle7 checker.

The following example shows how to select the Oracle7 offline checker for a particular connection context (CtxClass):

-offline@CtxClass=oracle.sqlj.checker.Oracle7OfflineChecker

This results in SQLJ using oracle.sqlj.checker.Oracle7OfflineChecker for offline checking of any of your SQLJ executable statements that specify a connection object that is a CtxClass instance.

The CtxClass connection context class must be declared in your source code or previously compiled into a .class file. (See "Connection Contexts" for more information.)

Use the -offline option separately for each connection context offline checker you want to specify; these settings have no influence on each other. For example:

-offline@CtxClass2=oracle.sqlj.checker.Oracle7OfflineChecker
-offline@CtxClass3=sqlj.semantics.OfflineChecker

To specify the offline checker for the default connection context and any other connection contexts for which you do not specify an offline checker:

-offline=oracle.sqlj.checker.Oracle7OfflineChecker

Any connection context without an offline checker setting uses the offline checker setting of the default connection context, presuming an offline checker has been set for the default context.

Command-line syntax
-offline<@conn_context_class>=checker_class
Command-line examples
-offline=oracle.sqlj.checker.Oracle80OfflineChecker
-offline@CtxClass=oracle.sqlj.checker.Oracle80OfflineChecker
Properties file syntax
sqlj.offline<@conn_context_class>=checker_class
Properties file examples
sqlj.offline=oracle.sqlj.checker.Oracle80OfflineChecker
sqlj.offline@CtxClass=oracle.sqlj.checker.Oracle80OfflineChecker
Default value
oracle.sqlj.checker.OracleChecker

Online Semantics-Checker (-online)

The -online option specifies a Java class or list of classes that implement the online semantics-checking component of SQLJ. This involves connecting to a database.

Remember that online checking is not enabled by the -online option--you must enable it through the -user option. The -password, -url, and -driver options must be set appropriately as well. (For information about what offline and online semantics-checkers accomplish and how they function, see "Semantics-Checking".)

You can specify different online checkers for different connection contexts, and you can list multiple checkers (separated by commas) for any given context. In cases where multiple checkers are listed for a single context, SQLJ uses the first checker (reading from left to right in the list) that accepts the database connection established for online checking. (At analysis time, a connection is passed to each online checker, and the checker decides whether it recognizes the database.)

The default OracleChecker, a front-end class discussed in "Semantics-Checkers and the OracleChecker Front End (default checker)", will serve your needs unless you want to specify a particular checker that would not be chosen by OracleChecker. For example, you might run online checking on a machine with an Oracle 8.0 database and JDBC driver, but your application (or at least statements using a particular connection context class) will eventually run against an Oracle 7.3 database. In this case you will want to check these statements using the Oracle7 checker.

The following example shows how to select the Oracle7 online checker for the DefaultContext class (and any other connection context classes without a specified setting):

-online=oracle.sqlj.checker.Oracle7JdbcChecker

To specify a list of drivers and allow the proper class to be selected depending on what kind of database is being accessed:

-online=oracle.sqlj.checker.Oracle7JdbcChecker,sqlj.semantics.JdbcChecker

With this specification, if connection is made to an Oracle database, then SQLJ uses the oracle.sqlj.checker.Oracle7JdbcChecker semantics-checker. If connection is made to any other kind of database, then SQLJ uses the generic sqlj.semantics.JdbcChecker semantics-checker. This is similar functionally to what the default OracleChecker does but ensures that you use an Oracle7 checker instead of an Oracle8 checker if you connect to an Oracle database.

To specify the online checker for a particular connection context (CtxClass):

-online@CtxClass=oracle.sqlj.checker.Oracle7JdbcChecker

This results in the use of oracle.sqlj.checker.Oracle7JdbcChecker for online checking of any of your SQLJ executable statements that specify a connection object that is an instance of CtxClass, presuming you enable online checking for CtxClass.

The CtxClass connection context class must be declared in your source code or previously compiled into a .class file. (See "Connection Contexts" for more information.)

Use the -online option separately for each connection context online checker you want to specify; these settings have no influence on each other:

-online@CtxClass2=oracle.sqlj.checker.Oracle80JdbcChecker
-online@CtxClass3=sqlj.semantics.JdbcChecker

Any connection context without an online checker setting uses the online checker setting of the default connection context, presuming you set an online checker for the default context.

Command-line syntax
-online<@conn_context_class>=checker_class(list)
Command-line examples
-online=oracle.sqlj.checker.Oracle80JdbcChecker
-online=oracle.sqlj.checker.Oracle80JdbcChecker,sqlj.semantics.JdbcChecker
-online@CtxClass=oracle.sqlj.checker.Oracle80JdbcChecker
Properties file syntax
sqlj.online<@conn_context_class>=checker_class(list)
Properties file examples
sqlj.online=oracle.sqlj.checker.Oracle80JdbcChecker
sqlj.online=oracle.sqlj.checker.Oracle80JdbcChecker,sqlj.semantics.JdbcChecker
sqlj.online@CtxClass=oracle.sqlj.checker.Oracle80JdbcChecker
Default value
oracle.sqlj.checker.OracleChecker

Caching of Online Semantics-Checker Results (-cache)

Use the -cache option to enable caching of the results generated by the online checker. This avoids additional database connections during subsequent SQLJ translation runs. The analysis results are cached in a file, SQLChecker.cache, that is placed in your current directory.

The cache contains serialized representations of all SQL statements successfully translated (translated without error or warning messages), including all statement parameters, return types, translator settings, and modes.

The cache is cumulative and continues to grow through successive invocations of the SQLJ translator. Delete the SQLChecker.cache file to empty the cache.

Command-line syntax
-cache=true/false
Command-line example
-cache=true
Properties file syntax
sqlj.cache=true/false
Properties file example
sqlj.cache=false
Default value
false

Translator Support and Options for Alternative Environments

By default, Oracle9i SQLJ is configured to run under the Sun Microsystems JDK 1.2.x (or higher) or 1.1.x and to use the Sun Microsystems compiler javac. These are not requirements, however. You can configure SQLJ to work with alternative JVMs or compilers. To do so, you must supply SQLJ with the following information:

A set of SQLJ options allows you to provide this information. These options are described in "Java and Compiler Options" below.

SQLJ also defaults to the Oracle profile customizer, but can work with alternative customizers as well. See "Customization Options" for how to instruct SQLJ to use a different customizer.


Note:

Be aware of the limitations of any operating system and environment you use. In particular, the complete, expanded SQLJ command line must not exceed the maximum command-line size (for example, 250 characters for Windows 95 and 4000 characters for Windows NT). Consult your operating system documentation. 


Java and Compiler Options

The following options relate to the operation of the JVM and Java compiler:

Some compilers, such as the standard javac, require a Java source file name to match the name of the public class (if any) defined there. Therefore, by default the SQLJ translator verifies that this is true. You can use the following option, however, to instruct SQLJ not to verify this:

For some JVM and compiler configurations, there might be problems with the way SQLJ normally invokes the compiler. You can use the following option to alleviate this by breaking SQLJ processing into a two-pass process:

You can also pass options directly to the particular JVM or compiler you use, through the -J and -C prefixes discussed in "Prefixes that Pass Option Settings to Other Executables".


Note:

The -vm option, -passes option, and -J prefix cannot be used in a properties file. You can set them on the command line or, more conveniently, in the SQLJ_OPTIONS environment variable. See "SQLJ_OPTIONS Environment Variable for Option Settings"


Name of the Java Virtual Machine (-vm)

Use the -vm option if you want to specify a particular JVM for SQLJ to use. Otherwise SQLJ uses the standard java from the Sun Microsystems JDK.

You cannot set this option in a properties file, because properties files are read after the JVM is invoked.

If you do not specify a directory path along with the name of the JVM executable file, then SQLJ looks for the executable according to the setting of your operating system PATH variable.


Note:

Special functionality of this option, -vm=echo, is supported. This is equivalent to the -n option, instructing the sqlj script to construct the full command line that would be passed to the SQLJ translator, and echo it to the user without having the translator execute it. For more information, see "Command Line Echo without Execution (-n)"


Command-line syntax
-vm=JVM_path+name 
Command-line example
-vm=/myjavadir/myjavavm
Properties file syntax

n/a

Properties file example

n/a

Default value
java

Name of the Java Compiler (-compiler-executable)

Use the -compiler-executable option if you want to specify a particular Java compiler for SQLJ to use. Otherwise SQLJ uses the standard javac from the Sun Microsystems JDK.

If you do not specify a directory path along with the name of the compiler executable file, then SQLJ looks for the executable according to the setting of your operating system PATH variable.

The following is required of any Java compiler that you use:

As always, SQLJ processes compiler line information so that it refers to line numbers in the original .sqlj file, not in the produced .java file.


Note:

If you use a compiler that does not support an -encoding option, then disable the -compiler-encoding-flag, described in "Compiler Encoding Support (-compiler-encoding-flag)"


Command-line syntax
-compiler-executable=Java_compiler_path+name
Command-line example
-compiler-executable=/myjavadir/myjavac
Properties file syntax
sqlj.compiler-executable=Java_compiler_path+name
Properties file example
sqlj.compiler-executable=myjavac
Default value
javac

Compiler Encoding Support (-compiler-encoding-flag)

As mentioned in "Encoding for Input and Output Source Files (-encoding)", it is typical that when you employ the -encoding option to specify an encoding character set for SQLJ to use, SQLJ passes this to the Java compiler for the compiler to use as well. Set the -compiler-encoding-flag to false if you do not want SQLJ to pass the character encoding to the compiler (if, for example, you are using a compiler other than javac, and it does not support an -encoding option by that name).

Command-line syntax
-compiler-encoding-flag=true/false
Command-line example
-compiler-encoding-flag=false
Properties file syntax
sqlj.compiler-encoding-flag=true/false
Properties file example
sqlj.compiler-encoding-flag=false
Default value
true

Compiler Output File (-compiler-output-file)

If you have instructed the Java compiler to output its results to a file, then use the -compiler-output-file option to make SQLJ aware of the file name. Otherwise SQLJ assumes that the compiler outputs to the standard output device (such as STDOUT on a UNIX system). As appropriate, specify an absolute path, or a relative path from the current directory.


Note:

You cannot use this option if you enable -passes, which requires output to STDOUT


Command-line syntax
-compiler-output-file=output_file_path+name
Command-line example
-compiler-output-file=/myjavadir/mycmploutput
Properties file syntax
sqlj.compiler-output-file=output_file_path+name
Properties file example
sqlj.compiler-output-file=/myjavadir/mycmploutput
Default value

none (standard output)

Compiler Message Output Pipe (-compiler-pipe-output-flag)

By default, the javac compiler provided with the Sun Microsystems JDK writes error and message output to STDERR. SQLJ, however, expects such compiler output to be written to STDOUT so it can be captured reliably.

If SQLJ sets the javac.pipe.output system property to true, which is SQLJ's default behavior when it invokes the Java compiler, then compiler error and message output will be sent to STDOUT. You can specify -compiler-pipe-output-flag=false, however, to instruct SQLJ to not set this system property when it invokes the Java compiler. You should do this, for example, if the Java compiler you are using does not support the javac.pipe.output system property.

You can set this flag in a properties file, as well as on the command line or in the SQLJ_OPTIONS environment variable.


Notes:

  • If you are using a Java compiler that originates from Sun Microsystems and that writes its output to STDERR by default, then you must leave -compiler-pipe-output-flag enabled if you enable -passes, which requires output to STDOUT.

  • Sun Microsystems JDK 1.3.x versions appear to no longer support javac.pipe.output functionality.

 
Command-line syntax
-compiler-pipe-output-flag=true/false
Command-line example
-compiler-pipe-output-flag=false
Properties file syntax
sqlj.compiler-pipe-output-flag=true/false
Properties file example
sqlj.compiler-pipe-output-flag=false
Default value
true

Source File Name Check (-checkfilename)

This flag instructs SQLJ whether to verify that the SQLJ source file name matches the name of the public class (if any) defined there. Some compilers, such as the standard javac, require this to be the case; others do not.

To maximize portability of your code, this flag should be enabled, which it is by default.

(It is advisable for the source file name to always match the name of the public class defined, or, if there is no public class, the name of the first class defined. For example, public class MyPublicClass should be defined in a MyPublicClass.sqlj source file.)


Note:

If you are translating in the server, where there is no equivalent naming requirement, there is no -checkfilename option, and the translator executes no such check. 


Command-line syntax
-checkfilename=true/false
Command-line example
-checkfilename=false
Properties file syntax
sqlj.checkfilename=true/false
Properties file example
sqlj.checkfilename=false
Default value
true

SQLJ Two-Pass Execution (-passes)

By default, the following sequence occurs when you invoke the sqlj script:

  1. The sqlj script invokes your JVM, which runs the SQLJ translator.

  2. The translator completes the semantics-checking and translation of your .sqlj files, generating translated .java files.

  3. The translator invokes your Java compiler, which compiles the generated .java files.

  4. The translator processes the compiler output.

  5. If any profile files were generated, the translator invokes a profile customizer to customize them.

For some JVM and compiler configurations, however, the compiler invocation in step 3 will not return, and your translation will suspend.

If you encounter this situation, the solution is to instruct SQLJ to run in two passes, with the compilation step in between. To accomplish this, you must enable the two-pass execution flag as follows:

-passes

The -passes option must be specified on the command line or, equivalently, in the SQLJ_OPTIONS environment variable. It cannot be specified in a properties file.


Notes:

  • If you enable -passes, then compiler output must go to STDOUT, so leave -compiler-pipe-output-flag enabled (which is its default). In addition, you cannot use the -compiler-output-file option, which would result in output to a file instead of to STDOUT.

  • Like other command-line-only flags (-help, -version, -n), the -passes flag does not support =true syntax.

 

With -passes enabled, the following sequence occurs when you invoke the sqlj script:

  1. The sqlj script invokes your JVM, which runs the SQLJ translator for its first pass.

  2. The translator completes the semantics-checking and translation of your .sqlj files, generating translated .java files.

  3. The JVM is terminated.

  4. The sqlj script invokes the Java compiler, which compiles the generated .java files.

  5. The sqlj script invokes your JVM again, which runs the SQLJ translator for its second pass.

  6. The translator processes compiler output.

  7. If any profile files were generated, the JVM runs your profile customizer to customize them.

With this sequence, you circumvent any problems the JVM might have in invoking the Java compiler.

Command-line syntax
-passes
Command-line example
-passes
Properties file syntax

n/a

Properties file example

n/a

Default value
off

Customization Options

The following options relate to the customization of your SQLJ profiles:

Default Profile Customizer (-default-customizer)

Use the -default-customizer option to instruct SQLJ to use a profile customizer other than the default, which is:

oracle.sqlj.runtime.util.OraCustomizer

In particular, use this option if you are not using an Oracle database.

This option takes a fully qualified Java class name as its argument.


Notes:

You can override this option with the -P-customizer option in your SQLJ command line (or properties file). For more information, see "Options to Pass to the Profile Customizer (-P)"


Command-line syntax
-default-customizer=customizer_classname
Command-line example
-default-customizer=sqlj.myutil.MyCustomizer
Properties file syntax
sqlj.default-customizer=customizer_classname
Properties file example
sqlj.default-customizer=sqlj.myutil.MyCustomizer
Default value
oracle.sqlj.runtime.util.OraCustomizer


Note:

When you use an Oracle database, Oracle recommends that you use the default OraCustomizer for your profile customization. 


Options Passed Directly to the Customizer

As with the JVM and compiler, you can pass options directly to the profile customizer harness using a prefix, in this case -P. This is discussed in "Options to Pass to the Profile Customizer (-P)".

Details about these options, both general customization options and Oracle-specific customizer options, are covered in "Customization Options and Choosing a Customizer".


Go to previous page Go to next page
Oracle
Copyright © 1996-2001, Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index