8 Translator Command Line and Options

% sqlj <optionlist> filelist

8.1.1 SQLJ Options, Flags, and Prefixes

This section discusses options supported by the SQLJ translator. Boolean options are referred to as flags. 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, are also listed.

Summary of SQLJ Options

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

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

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

• Flags and options listed as Environment are discussed in "Translator Support and Options for Alternative Environments". These flags and options are for use of a non-standard JVM, compiler, or customizer.

• Options with a category of javac are javac compiler options that SQLJ recognizes directly, without the compiler prefix. They are passed to the Java compiler, typically javac, and some also affect SQLJ translator settings. These options are discussed in "Option Support for javac".

Notes Regarding Options, Flags, and Prefixes

Keep the following in mind:

• Flags, options, and prefixes listed as command line only in the Description column of the preceding table cannot be set in a properties file.

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

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

• Most SQLJ options can also be set in a properties file.

• The SQLJ_OPTIONS environment variable can be used in addition to, or instead of, the command line for setting options.

• In this document, boolean flags are usually discussed as being true or false, but they can also be enabled or disabled by setting them to yes/no, on/off, or 1/0.

Options for loadjava Compatibility

For compatibility with the loadjava utility used to load Java and SQLJ applications into an Oracle Database 10g instance, the following alternative syntax is recognized for the indicated options when specified on the command line:

• -e (for -encoding)

• -h (for -help)

• -p (for -password)

• -u (for -user)

• -v (for verbose message output; equivalent to -status)

To maintain full consistency with loadjava syntax, you can use a space instead of equal sign (=) in setting these options, as in the following example:

-u scott/tiger -v -e SJIS

Option Support for javac

SQLJ supports option settings for javac, the Java compiler supplied with the Sun Microsystems Java Development Kit (JDK), in the following ways:

• Some javac options that take values are combined into SQLJ options (-classpath, -d, -encoding).

• For other javac options that take values, special processing has been implemented to correctly pass the value to the compiler (-bootclasspath, -extdirs, -target). These require a compiler prefix. They have no effect on SQLJ operation.

• Flags for javac are recognized on the command line without a compiler prefix (-depend, -deprecation, -g, -nowarn, -O, -verbose). Some of these flags affect SQLJ translator flag settings as well.

This is summarized in Table 8-2. All of these options can be set on the SQLJ command line or in a properties file, though sometimes a compiler prefix is required, as noted in the table.

Refer to javac documentation for additional information about javac option settings and functionality.

Syntax Notes for javac Options

Keep the following in mind regarding the javac options syntax:

• If you want to set different classpath values for the Java compiler and for the JVM that runs SQLJ, then you must use separate settings, one with a -C prefix and one with a -J prefix. Otherwise, no prefix is required.

• Do not use the -C prefix to specify the -d or -encoding compiler options. Note that this also means that SQLJ and the compiler use the same settings for -d and -encoding.

• You can optionally use the -C prefix for -depend, -deprecation, -g, -nowarn, -O, and -verbose.

• All javac options, aside from those that are also SQLJ options (-classpath, -d, and -encoding) require the compile. prefix if you set them in a properties file.

• For consistency, it is advisable to use an equal sign (=) for options that take values, but a space also works when using a compiler prefix (-C on the command line or compile. in a properties file).

Example

The following example, which is a single wraparound command line, uses the -C-bootclasspath, -C-extdirs, and -C-target options.

% sqlj -vm=/usr/local/packages/jdk1.2.2/bin/java
       -compiler-executable=/usr/local/packages/jdk1.2.2/bin/javac
       -C-bootclasspath=/usr/local/packages/jdk1.3.1/jre/lib/rt.jar
       -C-extdirs="" -C-target=1.1.8 Demo.sqlj

Profile Customizer Options

Profile customizer options, that is, 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 and Specialized Customizers". This is relevant for ISO standard code generation only (-codegen=iso).

8.1.2 Command-Line Syntax and Operations

The general sequence of events triggered by running the script sqlj was discussed in "SQLJ 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.

Use an equal 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. However, you must 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

Arguments from the Option List

Option list arguments are used in the following ways:

• Options not designated by the -J, -C, or -P prefixes are SQLJ options (except for directly supported compiler options) and are passed to the SQLJ translator as the JVM invokes it.

• Options designated by the -J prefix are JVM options and are used by the JVM directly. Such options must be specified on the command line or in the SQLJ_OPTIONS environment variable. As with translator options, use an equal sign (=) in setting the option, such as:

  -J-Djavac.pipe.output=true
  
  

  If you want to set different classpath values for the Java compiler and for the JVM that runs SQLJ, you must use separate settings, one with a -C prefix and one with a -J prefix.

• Options designated by the -C prefix are Java compiler options and are passed to the compiler as the JVM invokes it. Compiler options taking values require special support, which has been implemented for javac options. You can use an equal sign for these, as follows (though a space also works):

  -C-bootclasspath=/usr/local/packages/jdk1.3.1/jre/lib/rt.jar
  
  

• Options designated by the -P prefix are SQLJ profile customizer options and are passed to the customizer as the JVM invokes it (relevant only for ISO standard code generation, -codegen=iso). As with translator options, use an equal sign (=) in setting the option, such as:

  -P-user=scott/tiger
  
  

  Any profile customization other than what SQLJ performs automatically is considered an advanced feature.

  
  

  See Also: Appendix A, "Customization and Specialized Customizers"

  
  

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:

• The .sqlj files are processed by the SQLJ translator, Java compiler, and SQLJ profile customizer (profile customizer for -codegen=iso only).

• The .java files are processed by the Java compiler and are also used by the SQLJ translator for type resolution.

• The .ser profiles and .jar files are processed only by the profile customizer (relevant only for -codegen=iso).

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

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, then all but the first reference are discarded from the command line. In addition, if you list a .java and .sqlj file with the same base name and in the same location without using the -dir option, then only the .sqlj file is processed. This processing also applies to wildcard characters.

Consider the following command-line examples, where % is the system prompt. Assume that your current directory is /myhome/mypackage, which contains the files Foo.sqlj and Foo.java:

% sqlj Foo.sqlj /myhome/mypackage/Foo.sqlj

These both refer to the same file, so the translator discards /myhome/mypackage/Foo.sqlj from the command line.

% sqlj Foo.sqlj Foo.java

The translator discards Foo.java from the command line. Otherwise, this command line would result in the translator writing and reading from Foo.java in the same execution.

% sqlj Foo.*

Again, the translator discards Foo.java from the command line. Otherwise, the translator would find both Foo.sqlj and Foo.java, which again would cause it to write and read from Foo.java in the same execution.

% sqlj -dir=outdir -d=outclasses Foo.sqlj Foo.java

This is fine, because the generated Foo.java will be in the outdir subdirectory, while the Foo.java being read is in the /myhome/mypackage directory. Presuming that Foo.java and Foo.sqlj define classes in different packages, the .class files created by Java compilation will be placed in different subdirectories under the outclasses directory hierarchy.

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

The following is a sample command line, where % is the system prompt. 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. The JVM passes the SQLJ options to the translator and compiler. If there are any options for the JVM, as designated by -J, then 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 manually). There is no customization in this example, because it uses the default Oracle-specific code generation.

After these steps are completed, the results are equivalent to the user having typed the following (presuming SushiBar.sqlj, DiveBar.sqlj, FooBar.java, and FooBaz.java were all in the current directory):

% java -Duser.language=ja -prof sqlj.tools.Sqlj -warn=none -encoding=SJIS SushiBar.sqlj DiveBar.sqlj FooBar.java FooBaz.java

Note that this is one wraparound command line.

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.

8.1.3 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. However, it is typical to pass options to the JVM of the compiler by using the command-line -C-J prefix.

You cannot use properties files to set the following SQLJ options, flags, and prefixes:

• -classpath

• -help, -help-long, -help-alias, -C-help, -P-help

• -J

• -n

• -passes

• -props

• -version, -version-long

• -vm

It is not possible to use properties files to specify options to the JVM, for example, because properties files are read after the JVM is invoked.

Also note that in properties files you cannot use option abbreviations recognized on the command line for compatibility with loadjava (-e, -h, -p, -u, -v).

Properties File Syntax

Option settings in a properties file are placed one per line. Lines with SQLJ options, compiler options, and customizer options can be interspersed. They are parsed by the SQLJ front end and processed appropriately.

Syntax for the different kinds of options is as follows:

• Each SQLJ option is prefixed by sqlj. (including the period) instead of an initial hyphen. Only options that start with this prefix are passed to the SQLJ translator. For example:

  sqlj.warn=none
  sqlj.linemap=true
  
  

• Each Java compiler option is prefixed by compile. (including the period) instead of -C-. Options that start with this prefix are passed to the Java compiler. For example:

  compile.verbose
  compile.bootclasspath=/usr/local/packages/jdk1.3.1/jre/lib/rt.jar
  
  

• General profile customization options, which apply regardless of the particular customizer you are using, are prefixed by profile. (including the period) instead of -P-. Only options that start with this prefix are passed to the profile customizer. For example:

  profile.backup
  profile.user=scott/tiger
  
  

  You can also specify options to a particular customizer by using profile.C as follows:

  profile.Csummary
  profile.Coptparamdefaults=VAR%(50),LONG%(500),RAW_TYPE()
  
  

  Any profile customization other than the default Oracle customization is considered an advanced feature.

  
  

  See Also: Appendix A, "Customization and Specialized Customizers"

  
  

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

  # Comment line.
  
  

• Blank lines are also permitted.

As on the command line, a flag can be enabled or disabled in a properties file with true/false, on/off, 1/0, or yes/no. A flag can also be enabled simply by entering it without a setting, such as the following:

sqlj.linemap

Properties File: Simple Example

The following are sample properties file entries:

# Set user and JDBC driver
sqlj.user=scott
sqlj.driver=oracle.jdbc.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: Nondefault 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 9.2 on spock.natdecsys.com
sqlj.user@SourceContext=sde
sqlj.password@SourceContext=fornow
sqlj.url@SourceContext=jdbc:oracle:thin:@207.67.155.3:1521/myservice

# Warning settings
sqlj.warn=all

# Cache
sqlj.cache=on

Default Properties Files

Regardless of whether a properties file is specified on 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.

8.1.4 SQLJ_OPTIONS Environment Variable for Option Settings

The Oracle SQLJ implementation supports 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.

8.1.5 Order of Precedence of Option Settings

SQLJ takes option settings in the following order:

1. Sets options to default settings, where applicable.

2. Looks for a sqlj.properties file in the Java home directory. If it finds one, it sets options as specified there.

3. Looks for a sqlj.properties file in the user home directory. If it finds one, it sets options as specified there.

4. 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. As SQLJ processes the command line, it looks in any file specified by the -props option and sets options as specified there.

Example

Presume SQLJ is run as follows:

% sqlj -user=scott -props=myprops.properties -dir=/home/java

And presume the file myprops.properties is in the current directory and contains the following entries:

sqlj.user=tony
sqlj.dir=/home/myjava

These settings are processed as if they were inserted into the command line where the -props option was specified. Therefore, the tony entry takes precedence over the scott entry for the user option, but the /home/java entry takes precedence over the /home/myjava entry for the dir option.

8.2.1 Basic Options for the Command Line Only

The following basic options can be specified only on the SQLJ command line or, equivalently, in the SQLJ_OPTIONS environment variable:

• -props

• -classpath

• -help, -help-long, -help-alias, -P-help, -C-help

• -version, -version-long

• -n

These options cannot be specified in properties files. The command-line-only flags (-help, -version, and -n) do not support =true syntax. Enable them by typing only the flag name, as follows:

sqlj -version-long

Input Properties File (-props)

The -props option specifies a properties file from which SQLJ can read option settings. The command-line syntax is as follows:

-props=filename

For example:

-props=myprops.properties

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 the equal sign (=), as with other SQLJ options. The following examples (both for a UNIX environment) demonstrate this:

-classpath  .:.$ORACLE_HOME/jdbc/lib/classes12.jar:$ORACLE_HOME/jdbc/lib/orai18n.jar

-classpath= .:.$ORACLE_HOME/jdbc/lib/classes12.jar:$ORACLE_HOME/jdbc/lib/orai18n.jar

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, then set them separately using the SQLJ -J and -C prefixes.

The command-line syntax is as follows

sqlj -classpath=class_path

For example:

sqlj -classpath=/jdbc-1.2.zip:/classes/bin

SQLJ Option Information (-help)

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

• -help

• -help-long

• -help-alias

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

% sqlj -help

% sqlj -help-long

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

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

• A synopsis of the most frequently used SQLJ options

• A listing of the additional -help flag settings available

The -help-long setting provides a complete list of SQLJ option information, including the following for each option:

• Option name

• Option type (the Java type that the option takes as input, such as int or String)

• Description

• Current value

• How the current value was set (from the command line, from a properties file, or by default)

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

The command-line syntax is as follows:

sqlj help_flag_settings

For example:

sqlj -help
sqlj -help -help-alias
sqlj -help-long
sqlj -warn=none,null -help-long
sqlj -help-alias

By default, these settings are disabled.

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:

• -version

• -version-long

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

% sqlj -version

% 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 the =true syntax. Enable it by typing only the flag name.

The -version setting displays the SQLJ release number, as follows:

sqlj -version
Oracle SQLJ Release 10.2.0.1.0 Production
Copyright  1997, 2005, Oracle Corporation. All Rights Reserved.

The -version-long setting displays information about the SQLJ and SQLJ run time library release, 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 as follows:

sqlj -version-long
Oracle SQLJ Release 10.2.0.1.0 Production
Copyright  1997, 2005, Oracle Corporation. All Rights Reserved.
JDBC version: Oracle JDBC driver version 10.2 (10.2.0.1.0)
Java version: 1.2 (1.2.2)

This flag offers a good way to check your SQLJ installation and the JDBC and JDK versions you are using. The command-line syntax is as follows:

sqlj version_flag_settings

For example:

sqlj -version
sqlj -version -version-long
sqlj -version-long

By default, these settings are disabled.

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 displaying the following:

• The fully expanded form of any options you abbreviated, such as -u and other abbreviations supported for loadjava compatibility.

• The order in which options would be placed when the overall command string is constructed and passed to the translator.

• Possible conflicts between SQLJ_OPTIONS settings and command-line settings.

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 the =true syntax. Enable it by typing only the flag name.

Consider a sample scenario. You have the following setting for SQLJ_OPTIONS:

-user=scott/tiger@jdbc:oracle:thin:@ -classpath=/myclasses/bin

You enter the following command line:

% sqlj -n -e SJIS myapp.sqlj

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

Note that this is all one wraparound line.

The command-line syntax is as follows:

-n

For example:

-n

By default, this setting is disabled.

8.2.2 Options for Output Files and Directories

The -encoding option specifies encoding for SQLJ input and output source files. The following options specify where SQLJ output files are placed:

• -d

• -dir

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 equal sign (=) in setting this option on the command line, as in the following examples:

-encoding=SJIS

-encoding SJIS

However, if setting sqlj.encoding in a properties file, then 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:

• As with the -classpath and -d options, if you do use an = in setting the -encoding 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.

• For compatibility with the loadjava utility, -e is recognized as equivalent to -encoding when specified on the command line.

• The -encoding option does not apply to Java properties files, such as sqlj.properties and connect.properties. Properties files always use the encoding 8859_1. This is a feature of Java in general, not SQLJ in particular. However, you can use Unicode escape sequences in a properties file. You can use the native2ascii utility to create escape sequences for a natively encoded file.

  
  

  See Also: "Using native2ascii for Source File Encoding"

  
  

The command-line syntax is as follows:

-encoding=Java_character_encoding

For example:

-encoding=SJIS

The syntax for a properties file entry for this option is as follows:

sqlj.encoding=Java_character_encoding

For example

sqlj.encoding=SJIS

By default, this option is set to the 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 (relevant for ISO standard code generation, -codegen=iso), 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 for placement through the -d option.

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 the a.b.c package and specify directory, /mydir, output files will be placed in the /mydir/a/b/c directory. If you specify a relative directory path, then 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

However, if setting -d in a properties file, then 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 the 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, as follows:

-d=.

-d=../paralleldir

If the -d option is empty or not specified, then a generated .class file is placed in the same directory as the corresponding .java file, which is according to the -dir option for a .java file generated by SQLJ, and a generated .ser file is placed in the same directory as the corresponding .sqlj file.

The command-line syntax is as follows:

-d=directory_path

For example:

-d=/topleveldir/mydir

The syntax for a properties file entry for this option is as follows:

sqlj.d=directory_path

For example:

sqlj.d=/topleveldir/mydir

This option does not have any default value.

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 the a.b.c package and specify directory, /mydir, then output files will be placed in the /mydir/a/b/c directory. If you specify a relative directory path, then 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

Consider that 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, as follows:

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

The command-line syntax is as follows:

-dir=directory_path

For example:

-dir=/topleveldir/mydir

The syntax for a properties file entry for this option is as follows:

sqlj.dir=directory_path

For example:

sqlj.dir=/topleveldir/mydir

This option does not have any default value.

8.2.3 Connection Options

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

• -user

• -password

• -url

• -default-url-prefix

• -driver

There is no requirement for the SQLJ translator to connect to the same database or schema as the application does at run time. The connection information in application source code can be independent of the connection information in the SQLJ options. In fact, the deployment environment might be unavailable during development and testing.

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, namely that type incompatibilities that would normally result in run-time 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 or disables it according to the presence or absence of the -user option.

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

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

-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, as follows:

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

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, for example, CtxClass, 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 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.

Use 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. For example:

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

You can 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 as follows:

-user=

The general command-line syntax for this option is as follows:

-user<@conn_context_class>=username</password><@url>

For example:

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

The syntax for a properties file entry for this option is as follows:

sqlj.user<@conn _context_class>=username</password><@url>

For example:

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=

This option does not have a default value. By default, there is no online-semantics checking.

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. 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, then the following 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 use 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. 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=

-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

-password@CtxClass2=EMPTY.PASSWORD

However Oracle Database 10g does not permit an empty password.

The command-line syntax for this option is as follows:

-password<@conn_context_class>=user_password

For example:

-password=tiger
-password=
-password=EMPTY.PASSWORD
-password@CtxClass=tiger

The syntax for a properties file entry for this option is as follows:

sqlj.password<@conn_context_class>=user_password

For example:

sqlj.password=tiger
sqlj.password=
sqlj.password=EMPTY.PASSWORD
sqlj.password@CtxClass=tiger

This option does not have a default value. Either the password for DefaultContext is used or the 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 database service name (or SID, which is deprecated in Oracle Database 10g).

You can also specify the URL as part of the -user option setting. 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, then the following example would set the URL to use for the connection for checking all your SQLJ statements:

-url=jdbc:oracle:oci:@

Alternatively, to include the host name, port number, and service name:

-url=jdbc:oracle:thin:@myhost:1521/myservice

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

jdbc:oracle:thin:@

A -url setting of localhost:1521/myservice would result in the following URL:

jdbc:oracle:thin:@localhost:1521/myservice

You can remove or alter this default prefix with the -default-url-prefix option.

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.

The command-line syntax for this option is as follows:

-url<@conn_context_class>=URL

For example:

-url=jdbc:oracle:oci:@
-url=jdbc:oracle:thin:@hostname:1521/myservice
-url=jdbc:oracle:oci:scott/tiger@
-url=hostname:1521/myservice
-url@CtxClass=jdbc:oracle:oci:@

The syntax for a properties file entry for this option is as follows:

sqlj.url<@conn_context_class>=URL

For example:

sqlj.url=jdbc:oracle:oci:@
sqlj.url=jdbc:oracle:thin:@hostname:1521/myservice
sqlj.url=jdbc:oracle:oci:scott/tiger@
sqlj.url=hostname:1521/myservice
sqlj.url@CtxClass=jdbc:oracle:oci:@

The default value for this option is:

jdbc:oracle:oci:@

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 enables 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 service name (or SID, which is deprecated) of the database. As an example, presume you set a URL as follows:

-url=myhost:1521/myservice

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

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

jdbc:oracle:thin:@myhost:1521/myservice

If you specify a full URL that starts with jdbc:, then the default prefix will not be used.

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

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

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

-default-url-prefix=

The command-line syntax for this option is as follows:

-default-url-prefix=url_prefix

For example

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

The syntax for a properties file entry for this option is as follows:

sqlj.default-url-prefix=url_prefix

For example:

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

The default value for this option is:

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-delimited list of classes. The default, OracleDriver, supports the Oracle JDBC OCI, JDBC Thin, and server-side JDBC drivers for use with Oracle Database 10g.

The command-line syntax for this option is as follows:

-driver=driver1<,driver2,driver3,...>

For example:

-driver=oracle.jdbc.OracleDriver
-driver=oracle.jdbc.OracleDriver,sun.jdbc.odbc.JdbcOdbcDriver

The syntax for a properties file entry for this option is as follows:

sqlj.driver=driver1<,driver2,driver3,...>

For example:

sqlj.driver=oracle.jdbc.OracleDriver
sqlj.driver=oracle.jdbc.OracleDriver,sun.jdbc.odbc.JdbcOdbcDriver

The default value for this option is:

oracle.jdbc.OracleDriver

8.2.4 Options for Reporting and Line-Mapping

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:

• -warn

• -status

• -explain

The following options enable line-mapping from the generated Java .class file back to the .sqlj source file, so that you can trace run-time errors back to the appropriate location in your original source code:

• -linemap

• -jdblinemap

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

Table 8-3 lists 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.

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.

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 ensure that all flags are off before you turn selected flags on, or all flags are on before you turn selected flags off.

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.

Following are some examples:

• Use the following sequence to ensure that only the nulls flag is on:

  -warn=none,nulls
  
  

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

  -warn=verbose,none,nulls
  
  

• Use the following to ensure that everything except the portability flag is on:

  -warn=all,noportable
  
  

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

The command-line syntax for this option is as follows:

-warn=comma-delimited_list_of_flags

For example:

-warn=none,nulls,precision

The syntax for a properties file entry for this option is as follows:

sqlj.warn=comma-delimited_list_of_flags

For example:

sqlj.warn=none,nulls,precision

The default value for this option is as follows:

cast,precision,nulls,noportable,strict,noverbose

Real-Time Status Messages (-status)

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

The command-line syntax for this option is as follows:

-status<=true|false>

For example:

-status

The syntax for a properties file entry for this option is as follows:

sqlj.status<=true|false>

For example:

sqlj.status

The default value for this option is:

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.

The command-line syntax for this option is as follows:

-explain<=true|false>

For example:

-explain

The syntax for a properties file entry for this option is as follows:

sqlj.explain<=true|false>

For example:

sqlj.explain

The default value for this option is:

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 run-time 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:

• The -d option setting, which determines the root directory for .class files

• The -dir option setting, which determines the root directory for generated .java files

The command-line syntax for this option is as follows:

-linemap<=true|false>

For example:

-linemap

The syntax for a properties file entry for this option is as follows:

sqlj.linemap<=true|false>

For example:

sqlj.linemap

The default value for this option is:

false

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

This option is equivalent to the -linemap option, but you should use it instead of -linemap if you are using the Sun Microsystems jdb debugger. This is because jdb can access only source files with a .java file name extension.

With the -jdblinemap setting, SQLJ does the following:

• Overwrites the contents of the .java file generated by the translator with the contents of the original .sqlj file

• Preserves the .java file name, instead of the .sqlj file name, in the generated .class file

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

The command-line syntax for this option is as follows:

-jdblinemap<=true|false>

For example:

-jdblinemap

The syntax for a properties file entry for this option is as follows:

sqlj.jdblinemap<=true|false>

For example:

sqlj.jdblinemap

The default value for this option is:

false

8.2.5 Options for DMS

The Oracle SQLJ implementation provides translator front-end options to support DMS:

• -instrument: Enable instrumentation and designate a name for the application (the collective of the components being translated).

• -components: Specify the components (packages and classes) to be instrumented.

Instrumentation for DMS (-instrument)

Use the SQLJ -instrument option to enable instrumentation and specify an application name. In this context, the term application refers to all the SQLJ and Java components specified for translation in the SQLJ command line.

Possible settings of the -instrument option are as follows:

• application_name: To enable instrumentation and use the specified application name, optionally prefixed with a package name in the standard Java dot syntax. Use a slash (/), with no spaces, between the package name and the application name.

• true: To enable instrumentation and use the default application name, defaultApp.

• false (default): To disable instrumentation.

If instrumentation is enabled, a SQLJ DMS properties file is created. Its name and location are according to the -instrument setting, starting from the current directory, according to the package name and also according to any setting of the SQLJ -d option. If no application name is specified, as is the case with the setting true, then the properties file is named sqlmonitor.properties in the current directory.

As a simple example, a setting of -instrument=myapp will result in creation of the properties file, myapp.properties, in the current directory.

Now consider the following example, for an application name of stock and the package com.acme:

% sqlj -instrument=com.acme/stock Stock.sqlj Trading.sqlj

In this case, the properties file ./com/acme/stock.properties is created.

Now consider the following example:

% sqlj -instrument=com.acme/stock -d /home Stock.sqlj Trading.sqlj

In this case, because of the -d option, the file /home/com/acme/stock.properties is created.

You can also set the -instrument option in sqlj.properties as follows:

sqlj.instrument=com.acme/stock

The command-line syntax for this option is as follows:

-instrument<=true|false|application_name>

For example:

-instrument=com.acme/stock

The syntax for a properties file entry for this option is as follows:

sqlj.instrument<=true|false|application_name>

For example:

sqlj.instrument=com.acme/stock

The default value for this option is:

false

Components to Instrument for DMS (-components)

When instrumentation is enabled through the -instrument option, use the -components option to specify the components to be instrumented for DMS monitoring. This is a subset of the components being translated, typically most or all of them to allow flexibility in what you can monitor during run time. At run time, instrumented components are monitored according to what is specified in the SQLJ DMS properties file.

Note that any components that are not instrumented during translation cannot be monitored during run time, regardless of what is specified in the properties file.

The -components option supports either of the following settings:

• list_of_components: A comma-delimited list of packages or classes to instrument

• all (default): Specification to instrument all components being translated

For the list of components, you can specify fully qualified class names, using the standard Java dot syntax, or you can specify package names to instrument all classes in the packages.

For example, to instrument the Stock and Trading classes:

% sqlj ... -components=com.acme.Stock,com.acme.Trading

Alternatively, here is an equivalent specification in the sqlj.properties file:

sqlj.components=com.acme.Stock,com.acme.Trading

The command-line syntax for this option is as follows:

-components=all|list_of_components

For example:

-components=com.acme.Stock,com.acme.Trading

The syntax for a properties file entry for this option is as follows:

sqlj.components=all|list_of_components

For example:

sqlj.components=com.acme.Stock,com.acme.Trading

The default value for this option is:

all

8.2.6 Options for Code Generation, Optimizations, and CHAR Comparisons

By default, the Oracle SQLJ implementation uses Oracle-specific code generation, which generates Oracle JDBC code directly, as an alternative to ISO standard SQLJ code generation. With Oracle-specific code generation, no profiles are generated, and the SQLJ run time 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.

There is also an option for CHAR comparisons in a WHERE clause, accounting for any blank padding in the column. This option is also available as either a translator option (for Oracle-specific code generation) or an Oracle customizer option (for ISO standard code generation).

This section describes the following code generation, optimization, and CHAR comparison and bind options:

• -codegen

• -optcols

• -optparams

• -optparamdefaults

• -fixedchar

• -ncharconv

Code Generation (-codegen)

The Oracle SQLJ implementation can either generate Oracle-specific JDBC code directly or generate ISO standard code that calls the SQLJ run time, which in turn calls JDBC. With Oracle-specific code generation, there are no profile files and the SQLJ run time is largely bypassed during program execution.

Use the SQLJ translator -codegen option if you want to specify code generation according to the ISO standard (the default in earlier releases), as follows:

-codegen=iso

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

-codegen=oracle

The command-line syntax for this option is as follows:

-codegen=iso|oracle

For example:

-codegen=iso

The syntax for as properties file entry for this option is as follows:

sqlj.codegen=iso|oracle

For example:

sqlj.codegen=iso

The default value for this option is:

oracle

Column Definitions (-optcols)

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 the database, depending on the particular driver implementation. Specifically, this is effective for the JDBC Thin driver and positional iterators.

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

The command-line syntax for this option is as follows:

-optcols<=true|false>

For example:

-optcols

The syntax for a properties file entry for this option is as follows:

sqlj.optcols<=true|false>

For example:

sqlj.optcols

The default value for this option is:

false

Parameter Definitions (-optparams)

Use the SQLJ translator -optparams flag to enable parameter size definitions. If this flag is enabled, SQLJ will register your input and output parameters 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 data type in the -optparamdefaults option setting

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

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

Following is a command-line example (omitting a setting for the -optparamdefaults option):

% sqlj -optparams -optparamdefaults=defaults_string MyApp.sqlj

The command-line syntax for this option is as follows:

-optparams<=true|false>

For example:

-optparams

The syntax for a properties file entry for this option is as follows:

sqlj.optparams<=true|false>

For example:

sqlj.optparams

The default value for this option is:

false

Parameter Default Size (-optparamdefaults)

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

If a host variable has a source code hint to specify its size, then that takes precedence over the corresponding data type default size set with this option. If there is no source code hint or corresponding data type 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.

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 data type, 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 data type names:

• CHAR

• VARCHAR, VARCHAR2 (synonymous)

• LONG, LONGVARCHAR (synonymous)

• BINARY, RAW (synonymous)

• VARBINARY

• LONGVARBINARY, LONGRAW (synonymous)

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

• CHAR_TYPE covers CHAR, VARCHAR/VARCHAR2, and LONG/LONGVARCHAR.

• RAW_TYPE covers BINARY/RAW, VARBINARY, and LONGVARBINARY/LONGRAW.

• A percent sign (%) by itself covers all recognized data types or appended to a partial name, covers a subset of data types. For example, VAR% includes all data types that start with "VAR".

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

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

The command-line syntax for this option is as follows:

-optparamdefaults=defaults_string

For example:

-optparamdefaults=VAR%(50),LONG%(500),RAW_TYPE()

The syntax for a properties file entry for this option is as follows:

sqlj.optparamdefaults=defaults_string

For example

sqlj.optparamdefaults=VAR%(50),LONG%(500),RAW_TYPE()

The default value for this option is:

null

CHAR Comparisons with Blank Padding (-fixedchar)

Set this flag to true to account for blank padding in CHAR database columns when binding character strings for WHERE clause comparisons. This way, for example, "mystring" would compare positively against "mystring ".

This functionality uses the JDBC setFixedCHAR() method, an Oracle extension to take padding into account. The standard JDBC setString() method does not account for blank padding.

Following is an example of -fixedchar usage:

% sqlj -fixedchar MyProgram.sqlj AnotherProg.java ...

The command-line syntax for this option is as follows:

-fixedchar<=true|false>

For example:

-fixedchar

The syntax for a properties file entry for this option is as follows:

sqlj.fixedchar<=true|false>

For example:

sqlj.fixedchar

The default value for this option is:

false

NCHAR Bind (-ncharconv)

Set this option if you want to use String host variables to bind to NCHAR columns. This option specifies that the SetFormOfUse method should be used in the generated code for all binds to character columns. You need to translate the SQLJ file with is option as follows:

% sqlj -ncharconv MyApp.sqlj AnotherApp.java ...

This option is supported by both codegen=oracle and codegen=iso.

The command-line syntax for this option is as follows:

-ncharconv<=true|false>

For example:

-ncharconv

The syntax for a properties file entry for this option is as follows:

sqlj.ncharconv<=true|false>

For example:

sqlj.ncharconv

The default value for this option is:

false

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

• -J (mark options for the Java interpreter)

• -C (mark options for the Java compiler)

• -P (mark options for the profile customizer, for ISO code generation only)

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=ja argument as is to the JVM. In the Sun Microsystems JDK, the -Duser.language=ja flag sets the user.language system property 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.

The command-line syntax for this option is as follows:

-J-Java_option

For example:

-J-Duser.language=ja

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

-C-nowarn

After stripping the -C prefix, the sqlj script passes the -nowarn argument as is to the compiler.

Generally, compiler options are passed without change, but when you use an equal sign (=) to set a compiler option that takes a value, such as for -bootclasspath, -extdirs, or -target, the equal sign is stripped out when the option is passed to the compiler. Consider the following example:

% sqlj -C-bootclasspath=/usr/local/packages/jdk1.3.1/jre/lib/rt.jar myfile.sqlj

Also note that 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:

• Do not use -C-encoding to specify encoding of .java files processed by the Java compiler. Instead, use the SQLJ -encoding option, which specifies encoding of .sqlj files processed by SQLJ and .java files generated by SQLJ, and is also passed to the compiler. This ensures that .sqlj files and .java files receive the same encoding.

• Do not use -C-d to specify an output directory for .class files. Instead, use the SQLJ -d option, which specifies the output directory for generated profile files (.ser), and is also passed to the Java compiler. This will ensure that .class files and .ser files are in the same directory.

The command-line syntax for this option is as follows:

-C-Java_compiler_option

For example:

-C-nowarn

The syntax for a properties file entry for this option is as follows:

compile.Java_compiler_option

For example:

compile.nowarn

Options to Pass to the Profile Customizer (-P)

During the customization phase (relevant only for ISO standard code generation), 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:

• Use -P by itself to pass generic options to the customizer harness that apply regardless of the customizer.

• Use -P-C to pass vendor-specific options to the particular customizer you are using.

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 a generic customizer option:

-P-backup

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

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

The command-line syntax for this option is as follows:

-P-<C>profile_customizer_option

For example:

-P-driver=oracle.jdbc.OracleDriver
-P-Csummary

The syntax for a properties file entry for this option is as follows:

profile.<C>profile_customizer_option

For example:

profile.driver=oracle.jdbc.OracleDriver
profile.Csummary

8.3.2 Flags for Special Processing

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

• -compile

• -profile

The -ser2class flag, for ISO code generation, directs SQLJ to convert profiles from serialized resource (.ser) files to class files after customization.

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

The -bind-by-identifier flag specifies that SQLJ treat multiple appearances of the same host variable in a given SQLJ statement as a single bind occurrence.

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.

The command-line syntax for this option is as follows:

-compile<=true|false>

For example:

-compile=false

The syntax for a properties file entry for this option is as follows:

sqlj.compile<=true|false>

For example:

sqlj.compile=false

The default value for this option is:

true

Profile Customization Flag (-profile)

For ISO code generation, the -profile flag enables or disables processing of generated profile files (.ser) 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 than 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 may 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.

The command-line syntax for this option is as follows:

-profile<=true|false>

For example:

-profile=false

The syntax for a properties file entry for this option is as follows:

sqlj.profile<=true|false>

For example:

sqlj.profile=false

The default value for this option is:

true

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

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

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, consider the following:

Foo_SJProfile0.ser

This is converted to:

Foo_SJProfile0.class

The command-line syntax for this option is as follows:

-ser2class<=true|false>

For example:

-ser2class

The syntax for a properties file entry for this option is as follows:

sqlj.ser2class<=true|false>

For example

sqlj.ser2class

The default value for this option is:

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:

• If a class file cannot be found for a required class, but a source file can be found

• If a source file has a more recent modification date than its corresponding class file

The command-line syntax for this option is as follows:

-checksource<=true|false>

For example:

-checksource=false

The syntax for a properties file entry for this option is as follows:

sqlj.checksource=<=true|false>

For example:

sqlj.checksource=false

The default value for this option is:

true

Binding Host Expressions by Identifier (-bind-by-identifier)

In keeping with the SQLJ standard, the Oracle implementation by default creates a unique name for each host-variable bind reference in a statement, even if there are multiple occurrences of the same host variable. The SQLJ standard is based on JDBC, and JDBC does not make provisions for binding the same variable into different positions. Instead, each bind position (identified by ?) is bound to an individual value.

In some situations this causes errors, such as in the following example:

#sql emps = { SELECT substr(ename, 1, :bind_var), sum(sal) FROM emp
              GROUP BY substr(ename, 1, :bind_var) };

Because separate bind reference names are created for the two occurrences of bind_var, this results in a SQL exception at run time. When the differing bind names are detected, the SQL engine concludes that the GROUP BY clause is not part of the SELECT-list.

To avoid such problems, Oracle extends standard functionality with the -bind-by-identifier flag. A setting of true results in all bind occurrences of the same identifier in a given SQLJ statement or PL/SQL block being treated as a single bind occurrence. A SQLJ statement with four bind operations, :x, :x, :y, :x, would be bound as :1, :1, :2, :1 instead of :1, :2, :3, :4.

In the preceding example, both bindings would be as substr(ename, 1, :1) instead of as substr(ename, 1, :1) and substr(ename, 1, :2).

The command-line syntax for this option is as follows:

-bind-by-identifier<=true|false>

For example:

-bind-by-identifier

The syntax for a properties file entry for this option is as follows:

sqlj.bind-by-identifier=<=true|false>

For example:

sqlj.bind-by-identifier

The default value for this option is:

false

8.3.3 Semantics-Checking and Offline-Parsing Options

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

• -offline

• -online

• -cache

• -parse

Description of these options is preceded by two introductory discussions:

• A discussion of OracleChecker (the default front-end class for semantics-checking) and an introduction to the Oracle semantics-checkers

• A comparison of online semantics-checking versus offline parsing

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

Oracle supplies Oracle-specific offline checkers, a generic offline checker, Oracle-specific online checkers, and a generic online checker. The generic checkers assume you use only standard SQL92 and standard JDBC features. Oracle recommends that you use the Oracle-specific checkers when using an Oracle database.

The default checker, which is satisfactory in the great majority of circumstances, 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 is the Oracle8 checker for Oracle 10g, Oracle9i, and Oracle8i types, for both online and offline checking (as used in the corresponding JDBC implementations).

Online Checking with Oracle Database and JDBC Driver

If you are using an Oracle database 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-4 summarizes the choices for the possible combinations of database version and driver version, and also notes any other Oracle checkers that would be legal.

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-5 summarizes the possible choices. (Note that there is an Oracle8To7OfflineChecker, but it can be used only by selecting it manually.)

Online Semantics-Checking Versus Offline Parsing

The Oracle SQLJ implementation supports a feature known as offline parsing that offers a limited alternative to online semantics-checking. Offline parsing does not use a database connection, so cannot perform verification of operations against the database schema, but does offer syntax-checking of all SQL and PL/SQL statements. (Prior to Oracle9i, syntax-checking was not possible without a database connection.)

Table 8-6 provides a comparative summary of what offline parsing and online semantics-checking offer.

Online checking offers the primary advantage of verifying SQL and PL/SQL operations against the database schema. This includes verifying that column types match SQL operations and verifying the existence of called stored procedures. It requires a database connection during translation, however, which may be problematic in some circumstances. It also performs no verification of DDL operations.

Offline parsing offers the advantage of SQL syntax-checking without a database connection during translation, and also includes DDL operations in its syntax verifications.

Note that neither mode performs DDL semantics-checking against the database schema.

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. 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, will serve your needs unless you want to specify a particular checker that would not be chosen by OracleChecker.

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

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

This results in SQLJ using oracle.sqlj.checker.Oracle8OfflineChecker 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.Oracle8OfflineChecker
-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.Oracle8OfflineChecker

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.

The command-line syntax for this option is as follow:

-offline<@conn_context_class>=checker_class

For example:

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

The syntax for a properties file entry for this option is as follows:

sqlj.offline<@conn_context_class>=checker_class

For example:

sqlj.offline=oracle.sqlj.checker.Oracle8OfflineChecker
sqlj.offline@CtxClass=oracle.sqlj.checker.Oracle8OfflineChecker

The default value for this option is:

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

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, will serve your needs unless you want to specify a particular checker that would not be chosen by OracleChecker.

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

-online=oracle.sqlj.checker.Oracle8JdbcChecker

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.Oracle8JdbcChecker,sqlj.semantics.JdbcChecker

With this specification, if connection is made to an Oracle database, then SQLJ uses the oracle.sqlj.checker.Oracle8JdbcChecker 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.

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

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

This results in the use of oracle.sqlj.checker.Oracle8JdbcChecker 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.

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.Oracle8JdbcChecker
-online@CtxClass3=sqlj.semantics.JdbcChecker

Any connection context without an online checker setting uses the online checker setting of the default connection context.

The command-line syntax for this option is as follows:

-online<@conn_context_class>=checker_class(list)

For example:

-online=oracle.sqlj.checker.Oracle8JdbcChecker
-online=oracle.sqlj.checker.Oracle8JdbcChecker,sqlj.semantics.JdbcChecker
-online@CtxClass=oracle.sqlj.checker.Oracle8JdbcChecker

The syntax for a properties file entry for this option is as follows:

sqlj.online<@conn_context_class>=checker_class(list)

For example:

sqlj.online=oracle.sqlj.checker.Oracle8JdbcChecker
sqlj.online=oracle.sqlj.checker.Oracle8JdbcChecker,sqlj.semantics.JdbcChecker
sqlj.online@CtxClass=oracle.sqlj.checker.Oracle8JdbcChecker

The default value for this option is:

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.

The command-line syntax for this option is as follows:

-cache<=true|false>

For example:

-cache

The syntax for a properties file entry for this option is as follows:

sqlj.cache<=true|false>

For example:

sqlj.cache

The default value for this option is:

false

Offline Parser (-parse)

Use the -parse option to enable offline parsing. This feature is a complement to online semantics-checking, offering SQL and PL/SQL syntax-checking (but not verification against the schema) without a database connection during translation. Offline parsing also checks syntax for DDL statements, which online checking does not.

Also be aware that the setting of the -parse option can override the enabling of online checking by the -user option. Possible -parse settings are as follows:

• both (default): Enable the offline parser and allow online checking. In this case, online checking is determined by the -user option.

• online-only: Disable the offline parser and allow online checking. Again, online checking is determined by the -user option.

• offline-only: Enable the offline parser and disallow online checking. This overrides any -user option setting that would otherwise enable online checking.

• none: Disable the offline parser and disallow online checking, Again, this overrides any -user option setting that would otherwise enable online checking.

• parserclassname: Specify the name of a Java class that implements an alternative SQL parser. The class must implement the sqlj.framework.checker.SimpleChecker interface. This setting enables the specified parser, and only that parser is used for SQL-checking. The standard offline parser and online checking are both disabled.

The offline-only and none settings are offered for completeness, but are not typical modes of operation. It is best to let the -user option determine online checking. It is also not typical to specify your own parser.

The command-line syntax for this option is as follows:

-parse=both|online-only|offline-only|none|parserclassname

For example:

-parse=online-only

The syntax for a properties file entry for this option is as follows:

sqlj.parse=both|online-only|offline-only|none|parserclassname

For example:

sqlj.parse=online-only

The default value for this option is:

both

8.4.1 Java and Compiler Options

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

• -vm (to specify the JVM, on the command line only)

• -compiler-executable (to specify the Java compiler)

• -compiler-encoding-flag

• -compiler-output-file

• -compiler-pipe-output-flag

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. However, you can use the -checkfilename option to instruct SQLJ not to verify this.

For some JVM and compiler configurations, there may be problems with the way SQLJ normally invokes the compiler. You can use the -passes 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.

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.

The command-line syntax for this option is as follows:

-vm=JVM_path+name 

For example:

-vm=/myjavadir/myjavavm

The default value is:

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:

• It can write error and status information to the standard output device (for example, STDOUT on a UNIX system) or to a file, as directed by the -compiler-output-file option.

• It will understand the SQLJ -d option, which determines the root directory for class files.

• It must return a nonzero exit code to the operating system whenever a compilation error occurs.

• The line information that it provides in any errors or messages must be in one of the following formats (items in <> brackets being optional):

  • Sun Microsystems javac format

    filename.java:line<.column><-line<.column>>
    
    

    Example: myfile.java:15: Illegal character: '\u01234'

  • Microsoft jvc format

    filename.java(line,column)
    
    

    Example: myfile.java(15,7) Illegal character: '\u01234'

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.

The command-line syntax for this option is as follows:

-compiler-executable=Java_compiler_path+name

For example:

-compiler-executable=/myjavadir/myjavac

The syntax for a properties file entry for this option is as follows:

sqlj.compiler-executable=Java_compiler_path+name

For example:

sqlj.compiler-executable=myjavac

The default value is:

javac

Compiler Encoding Support (-compiler-encoding-flag)

When you use 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. For example, if you are using a compiler other than javac and it does not support an -encoding option by that name.

The command-line syntax for this option is as follows:

-compiler-encoding-flag<=true|false>

For example:

-compiler-encoding-flag=false

The syntax for a properties file entry for this option is as follows:

sqlj.compiler-encoding-flag<=true|false>

For example:

sqlj.compiler-encoding-flag=false

The default value is:

true

Compiler Output File (-compiler-output-file)

If you have instructed the Java compiler to write 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 writes 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.

The command-line syntax for this option is as follows:

-compiler-output-file=output_file_path+name

For example:

-compiler-output-file=/myjavadir/mycmploutput

The syntax for a properties file entry for this option is as follows:

sqlj.compiler-output-file=output_file_path+name

For example:

sqlj.compiler-output-file=/myjavadir/mycmploutput

This option does not have a default value.

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. However, SQLJ expects such compiler output to be written to STDOUT, so that it can be captured reliably.

If SQLJ sets the javac.pipe.output system property to true, which is the SQLJ default behavior when it invokes the Java compiler, then compiler error and message output will be sent to STDOUT. However, you can specify -compiler-pipe-output-flag=false 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.

The command-line syntax for this option is as follows:

-compiler-pipe-output-flag<=true|false>

For example:

-compiler-pipe-output-flag=false

The syntax for a properties file entry for this option is as follows:

sqlj.compiler-pipe-output-flag<=true|false>

For example:

sqlj.compiler-pipe-output-flag=false

The default value is:

true

Source File Name Check (-checkfilename)

It is generally 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.

The -checkfilename 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, while others do not.

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

The command-line syntax for this option is as follows:

-checkfilename<=true|false>

For example:

-checkfilename=false

The syntax for a properties file entry for this option is as follows:

sqlj.checkfilename<=true|false>

For example:

sqlj.checkfilename=false

The default value is:

true

SQLJ Two-Pass Execution (-passes)

By default, the following 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, then the translator invokes a profile customizer to customize them.

For some JVM and compiler configurations, however, the compiler invocation in Step 3 might not return, in which case 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.

With -passes enabled, the following 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.

The command-line syntax for this option is as follows:

-passes

For example:

-passes

The default value is:

off

8.4.2 Customization Options

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

• -default-customizer

• Options passed directly to the customizer

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.

The command-line syntax for this option is as follows:

-default-customizer=customizer_classname

For example:

-default-customizer=sqlj.myutil.MyCustomizer

The syntax for a properties file entry for this option is as follows:

sqlj.default-customizer=customizer_classname

For example:

sqlj.default-customizer=sqlj.myutil.MyCustomizer

The default value for this option is:

oracle.sqlj.runtime.util.OraCustomizer

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.

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