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

## Translator Support and Options for Alternative Environments

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

- the name of the JVM to use (`-vm` option)

- the name of the Java compiler to use (`-compiler-executable` option)

- any settings the compiler requires

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

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

Other SQLJ advanced flags and options are discussed in "Advanced Translator Options". "Basic Translator Options" describes more basic flags and options.

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

### Java and Compiler Options

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

- `-vm` (specify the JVM; command-line only)

- `-compiler-executable` (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. You can use the following option, however, to instruct SQLJ not to verify this:

- `-checkfilename`

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

- `-passes`

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

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

#### Name of the Java Virtual Machine (-vm)

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

You must specify this command on the command line; you cannot specify it 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 `PATH` setting of your operating system.

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

##### Command-line syntax

    -vm=JVM_path+name

##### Command-line example

    -vm=/myjavadir/myjavavm

##### Properties file syntax

n/a

##### Properties file example

n/a

##### Default value

    java

#### Name of the Java Compiler (-compiler-executable)

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

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

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

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

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

- It must return a non-zero 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 two formats (items in <> brackets are 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.

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

##### Command-line syntax

    -compiler-executable=Java_compiler_path+name

##### Command-line example

    -compiler-executable=/myjavadir/myjavac

##### Properties file syntax

    sqlj.compiler-executable=Java_compiler_path+name

##### Properties file example

    sqlj.compiler-executable=myjavac

##### Default value

    javac

#### Compiler Encoding Support (-compiler-encoding-flag)

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

##### Command-line syntax

    -compiler-encoding-flag=true/false

##### Command-line example

    -compiler-encoding-flag=false

##### Properties file syntax

    sqlj.compiler-encoding-flag=true/false

##### Properties file example

    sqlj.compiler-encoding-flag=false

##### Default value

    true

#### Compiler Output File (-compiler-output-file)

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

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

##### Command-line syntax

    -compiler-output-file=output_file_path+name

##### Command-line example

    -compiler-output-file=/myjavadir/mycmploutput

##### Properties file syntax

    sqlj.compiler-output-file=output_file_path+name

##### Properties file example

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

##### Default value

none (standard output)

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

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

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

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

##### Command-line syntax

    -compiler-pipe-output-flag=true/false

##### Command-line example

    -compiler-pipe-output-flag=false

##### Properties file syntax

    sqlj.compiler-pipe-output-flag=true/false

##### Properties file example

    sqlj.compiler-pipe-output-flag=false

##### Default value

    true

#### Source File Name Check (-checkfilename)

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

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

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

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

##### Command-line syntax

    -checkfilename=true/false

##### Command-line example

    -checkfilename=false

##### Properties file syntax

    sqlj.checkfilename=true/false

##### Properties file example

    sqlj.checkfilename=false

##### Default value

    true

#### SQLJ Two-Pass Execution (-passes)

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

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

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

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

4. The translator processes the compiler output.

5. The translator invokes a profile customizer to customize your profiles.

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

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

    -passes

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

Notes: If you enable `-passes`, then compiler output must go to `STDOUT`, so leave `-compiler-pipe-output-flag` enabled (which is its default). In addition, you cannot use the `-compiler-output-file` option, which would result in output to a file instead of to `STDOUT`. Like other command-line-only flags (`-help`, `-version`, `-n`), the `-passes` flag does not support `=true` syntax.

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

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

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

3. The JVM is terminated.

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

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

6. The translator processes compiler output.

7. The JVM runs your profile customizer, which customizes your profiles.

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

##### Command-line syntax

    -passes

##### Command-line example

    -passes

##### Properties file syntax

n/a

##### Properties file example

n/a

##### Default value

    off

### Customization Options

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

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

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

##### Command-line syntax

    -default-customizer=customizer_classname

##### Command-line example

    -default-customizer=sqlj.myutil.MyCustomizer

##### Properties file syntax

    sqlj.default-customizer=customizer_classname

##### Properties file example

    sqlj.default-customizer=sqlj.myutil.MyCustomizer

##### Default value

    oracle.sqlj.runtime.util.OraCustomizer

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

#### Options Passed Directly to the Customizer

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

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

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