Oracle8i SQLJ Developer's Guide and Reference Release 3 (8.1.7) Part Number A83723-01 |
Library | Service | Contents | Index

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

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index