Basic Translator Options

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

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

Basic Options for Command Line Only

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

• -props

• -classpath

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

• -version, -version-long

• -n

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

supported: sqlj -version-long ...

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

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

Input Properties File (-props)

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

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

Command-line syntax

-props=filename

Command-line example

-props=myprops.properties

Properties file syntax

n/a

Properties file example

n/a

Default value

none

CLASSPATH for Java Virtual Machine and Compiler (-classpath)

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

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

or:

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

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

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

Command-line syntax

sqlj -classpath=<class_path>

Command-line example

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

Properties file syntax

n/a

Properties file example

n/a

Default value

none

SQLJ Option Information (-help)

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

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

or:

sqlj -help-long

or:

sqlj -help-alias

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

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

sqlj -P-help

sqlj -C-help

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

Notes: For compatibility with the loadjava utility, -h is recognized as equivalent to -help when specified on the command line. See "Options for loadjava Compatibility". You can use multiple -help flag settings on the same command line, including -P-help and -C-help. Although -P and -C settings can generally be set in properties files, -P-help and -C-help are command-line-only. Help is also provided if you run SQLJ without specifying any files to process. This is equivalent to using the -help setting.

The -help Setting

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

• a synopsis of the most frequently used SQLJ options

• a listing of the additional -help flag settings available

The -help-long Setting

This 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 command line, from properties file, or by default)

  Note: It is often useful to include other option settings on the command line with a -help-long option, especially with complex options (such as -warn) or combinations of options, so that you can see what option settings resulted from your actions. (The -help-long mode displays current settings of all options.)

The -help-alias Setting

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

Command-line syntax

sqlj help_flag_settings

Command-line examples

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

         

Properties file syntax

n/a

Properties file example

n/a

Default value

none

SQLJ Version Number (-version)

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

• -version

• -version-long

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

sqlj -version

or:

sqlj -version-long

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

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

The -version Setting

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

The -version-long Setting

The -version-long setting displays SQLJ release and build version information and the JDBC driver release number if one can be found. For example, if an Oracle JDBC driver is used, this option would display something such as "Oracle JDBC version 8.1 (8.1.6.0.0)".

Command-line syntax

sqlj version_flag_settings

Command-line example

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

         

Properties file syntax

n/a

Properties file example

n/a

Default value

none

Command Line Echo without Execution (-n)

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

This is useful in showing you the following:

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

Consider the following 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

(This is all one wrap-around line.)

Note: As an alternative to -n, you can use the -vm=echo setting. Another effective way to check option settings is to use the -help-long flag. This displays current settings for all options, including other options you set on the command line as well as settings in properties files and in SQLJ_OPTIONS. See "SQLJ Option Information (-help)".

Command-line syntax

-n

Command-line example

-n

Properties file syntax

n/a

Properties file example

n/a

Default value

false

Options for Output Files and Directories

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

• -encoding

These options specify where SQLJ output files are placed:

• -d

• -dir

Encoding for Input and Output Source Files (-encoding)

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

-encoding=SJIS

-encoding SJIS

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

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

Notes: As with the -classpath and -d options described below, 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. See "Options for loadjava Compatibility". The -encoding option does not apply to Java properties files--sqlj.properties and connect.properties, for example. Properties files always use the encoding 8859_1. This is a feature of Java in general, not SQLJ in particular. You can, however, use Unicode escape sequences in a properties file. (You can use the native2ascii utility to create escape sequences for a natively encoded file--see "Using native2ascii for Source File Encoding".)

Command-line syntax

-encoding=Java_character_encoding

Command-line example

-encoding=SJIS

Properties file syntax

sqlj.encoding=Java_character_encoding

Properties file example

sqlj.encoding=SJIS

Default value

setting in JVM system property file.encoding

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

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

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

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

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

-d=/root

-d /root

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

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

-d=mysubdir/myothersubdir

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

-d=.

-d=../paralleldir

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

• A .class file corresponding to a .java file that was generated by the translator is placed in the same directory as the generated .java file, which is according to the -dir option.

• A .class file corresponding to a .java file that you specified on the command line will be placed in the same directory as the .java file.

• A .ser file is placed in the same directory as the .sqlj source file from which it resulted.

  Notes: You can specifically set -d to be empty (to override settings in a properties file, for example) as follows: -d= Throughout this discussion, the forward-slash (/) was used as the file separator. It is important to note, however, that in specifying this or similar options, you must actually use the file separator of your operating system, as specified in the file.separator system property of your JVM. As with the -classpath and -encoding options described above, if you do use an "=" in setting the -d option, then it is stripped out when the option string is passed to the JVM and compiler. This is because JVMs and compilers do not support the "=" syntax in their option settings.

Command-line syntax

-d=directory_path

Command-line example

-d=/topleveldir/mydir

Properties file syntax

sqlj.d=directory_path

Properties file example

sqlj.d=/topleveldir/mydir

Default value

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

Output Directory for Generated .java Files (-dir)

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

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

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

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

-dir=/root

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

-dir=mysubdir/myothersubdir

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

-dir=.

-dir=../paralleldir

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

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

-dir=

Notes: If you specify the -dir option but not the -d option, then generated .class files will also be placed in the directory specified by -dir, but generated .ser files will be placed in the directory of the .sqlj file. Throughout this discussion, the forward-slash (/) was used as the file separator. Be aware, however, that in specifying this or similar options, you must use the file separator of your operating system, as specified in the file.separator system property of your JVM.

Command-line syntax

-dir=directory_path

Command-line example

-dir=/topleveldir/mydir

Properties file syntax

sqlj.dir=directory_path

Properties file example

sqlj.dir=/topleveldir/mydir

Default value

none (use directory of .sqlj source file)

Connection Options

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

• -user

• -password

• -url

• -default-url-prefix

• -driver

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

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

Online Semantics-Checking and User Name (-user)

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

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

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

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

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

Notes: For compatibility with the loadjava utility, -u is recognized as equivalent to -user when specified on the command line. See "Options for loadjava Compatibility". User names cannot contain the characters "/" or "@". You are allowed to use a space instead of "=" in a user name setting on the command line, as in the following examples: -user scott/tiger -user@CtxClass scott/tiger -u scott/tiger -u@CtxClass scott/tiger If a password contains the character "@", then you cannot set the password through the -user option. You must use separate -user and -password settings.

Effect of -user When Using Default Connection Context Class Only

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

-user=scott

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

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

-user=scott/tiger

or:

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

or:

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

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

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

-user=

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

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

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

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

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

-user@CtxClass=scott

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

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

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

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

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

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

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

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

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

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

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

-user@CtxClass2=

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

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

-user=

Command-line syntax

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

Command-line examples

     
-user=scott
-user=scott/tiger
-user=scott@jdbc:oracle:oci8:@
-user=scott/tiger@jdbc:oracle:oci8:@
-user=
-user=URL.CONNECT
-user@Context=scott/tiger
-user@Context=

         

Properties file syntax

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

Properties file examples

     
sqlj.user=scott
sqlj.user=scott/tiger
sqlj.user=scott@jdbc:oracle:oci8:@
sqlj.user=scott/tiger@jdbc:oracle:oci8:@
sqlj.user=
sqlj.user=URL.CONNECT
sqlj.user@CtxClass=scott/tiger
sqlj.user@CtxClass=

         

Default value

none (no online semantics-checking)

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

User Password for Online Semantics-Checking (-password)

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

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

For the most part, functionality of the -password option parallels that of the -user option. That is, if your application uses only the default connection or other instances of DefaultContext, the 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 employ the -user option to specify additional exemplar schemas to use in testing statements that use those connection context classes. Similarly, use the -password option to specify passwords for those schemas, as in the following example:

-password@CtxClass1=tiger

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

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

-password=

or:

-password@CtxClass1=

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

-password=EMPTY.PASSWORD

or:

-password@CtxClass2=EMPTY.PASSWORD

Oracle, however, does not permit an empty password.

Notes: -p is recognized as equivalent to -password when specified on the command line. You are allowed to use a space instead of "=" in a password setting on the command line, as in the following examples: -password tiger -password@CtxClass tiger -p tiger -p@CtxClass tiger

Command-line syntax

-password<@conn_context_class>=user_password

Command-line examples

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

         

Properties file syntax

sqlj.password<@conn_context_class>=user_password

Properties file examples

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

         

Default value

none

Connection URL for Online Semantics-Checking (-url)

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

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

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

-url=jdbc:oracle:oci8:@

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

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

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

jdbc:oracle:thin:@

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

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

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

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

-url=jdbc:oracle:oci8: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:oci8:@

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

Notes: Remember that any connection context class with a URL setting must also have a user name setting for online checking to occur. You are allowed to use a space instead of "=" in a URL setting on the command line, as in the following examples: -url jdbc:oracle:oci8:@ -url@CtxClass jdbc:oracle:oci8:@

Command-line syntax

-url<@conn_context_class>=URL

Command-line examples

     
-url=jdbc:oracle:oci8:@
-url=jdbc:oracle:thin:@hostname:1521:orcl
-url=jdbc:oracle:oci8:scott/tiger@
-url=hostname:1521:orcl
-url@CtxClass=jdbc:oracle:oci8:@

         

Properties file syntax

sqlj.url<@conn_context_class>=URL

Properties file examples

     
sqlj.url=jdbc:oracle:oci8:@
sqlj.url=jdbc:oracle:thin:@hostname:1521:orcl
sqlj.url=jdbc:oracle:oci8:scott/tiger@
sqlj.url=hostname:1521:orcl
sqlj.url@CtxClass=jdbc:oracle:oci8:@

         

Default value

jdbc:oracle:oci8:@

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

Default URL Prefix (-default-url-prefix)

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

jdbc:oracle:thin:@

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

-url=myhost:1521:orcl

or:

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

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

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

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

-url=jdbc:oracle:oci8:@orcl

Use the -default-url-prefix option to alter or remove the default prefix. For example, if you want your URL settings to default to the OCI8 driver, instead of the Thin driver, then set the default prefix as follows:

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

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

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

-default-url-prefix=

Command-line syntax

-default-url-prefix=url_prefix

Command-line examples

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

         

Properties file syntax

sqlj.default-url-prefix=url_prefix

Properties file examples

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

         

Default value

jdbc:oracle:thin:@

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

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

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

Command-line syntax

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

Command-line examples

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

         

Properties file syntax

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

Properties file examples

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

         

Default value

oracle.jdbc.driver.OracleDriver

Reporting and Line-Mapping Options

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

• -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 runtime errors back to the appropriate location in your original source code. Use -jdblinemap in conjunction with the Sun Microsystems jdb debugger; otherwise use -linemap.

• -linemap

• -jdblinemap

Translator Warnings (-warn)

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

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

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

Table 8-2 Tests and Flags for SQLJ Warnings

Tests and Flag Functions	TRUE/FALSE Values
Data precision test--Enabling precision warns if there was a possible loss of precision when moving values from database columns to Java host variables.	precision (default) noprecision
Conversion loss test for nullable data--Enabling nulls warns if there was possible conversion loss when moving nullable columns or nullable Java types from database columns to Java host variables.	nulls (default) nonulls
Portability test--Enabling portable checks SQLJ clauses for portability and warns if there are non-portable clauses. (Where non-portable refers to the use of extensions to the SQLJ standard, such as vendor-specific types or features.)	portable noportable (default)
Strict matching test for named iterators--Enabling strict instructs SQLJ to require that the number of columns selected from the database must equal the number of columns in the named iterator being populated. A warning is issued for any column in the database cursor for which there is no corresponding column in the iterator. The nostrict setting allows more (but not fewer) columns in the database cursor. Unmatched columns are ignored.	strict (default) nostrict
Translation-time informational messages--Enabling verbose provides additional informational messages about the translation process (such as what database connections were made for online checking).	verbose noverbose (default)
Enable or disable all warnings.	all none

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

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

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

The all setting is equivalent to the following:

precision,nulls,portable,strict,verbose

And the none setting is equivalent to the following:

noprecision,nonulls,noportable,nostrict,noverbose

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

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

-warn=none,nulls

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

-warn=verbose,none,nulls

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

-warn=all,noportable

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

-warn=nonulls,all,noportable

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

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

-warn=portable -warn=nonulls

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

Command-line syntax

-warn=comma-separated_list_of_flags

Command-line example

-warn=none,nulls,precision

Properties file syntax

sqlj.warn=comma-separated_list_of_flags

Properties file example

sqlj.warn=none,nulls,precision

Default values

precision,nulls,noportable,strict,noverbose

Real-Time Status Messages (-status)

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

Notes: Do not confuse -warn=verbose with the -status flag. The -status flag provides real-time informational messages about all aspects of SQLJ translation. The -warn=verbose flag results in additional reporting after the translation and about the translation phase only. For compatibility with the loadjava utility, -v is recognized as equivalent to -status when specified on the command line. See "Options for loadjava Compatibility".

Command-line syntax

-status=true/false

Command-line example

-status=true

Properties file syntax

sqlj.status=true/false

Properties file example

sqlj.status=false

Default value

false

Cause and Action for Translator Errors (-explain)

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

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

Command-line syntax

-explain=true/false

Command-line example

-explain=true

Properties file syntax

sqlj.explain=true/false

Properties file example

sqlj.explain=false

Default value

false

Line-Mapping to SQLJ Source File (-linemap)

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

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

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

In performing this, SQLJ takes the following into account:

• 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

  Notes: If you are processing a .sqlj file and the compilation step is skipped due to error, then no line-mapping can be performed either, because no .class file is available for mapping. When the Java compiler is invoked from SQLJ (as is typical), it always reports compilation errors using line numbers of the original .sqlj source file, not the generated .java file. No option needs to be set for this mapping. Anonymous classes in a .sqlj file will not be instrumented. If you are using the Sun Microsystems jdb debugger, then use the -jdblinemap option (discussed next), instead of the -linemap option.

Command-line syntax

-linemap=true/false

Command-line example

-linemap=true

Properties file syntax

sqlj.linemap=true/false

Properties file example

sqlj.linemap=false

Default value

false

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

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

This is because jdb can access only source files with a .java file name extension. What -jdblinemap performs is 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.

Command-line syntax

-jdblinemap=true/false

Command-line example

-jdblinemap=true

Properties file syntax

sqlj.jdblinemap=true/false

Properties file example

sqlj.jdblinemap=false

Default value

false

---