Translator Support and Options for Alternative Environments

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

• the name of the Java VM to use (-vm option)

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

• any settings that the compiler requires

There is a set of SQLJ options that allow 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". More basic flags and options are discussed in "Basic Translator Options".

Note: With any operating system and environment you use, be aware of the limitations of the operating system and environment. 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.

Required Compiler Behavior

If you use a Java compiler other than javac, then the following is required:

• The compiler must return a non-zero exit code to the operating system whenever a compilation error occurs.

• The line information that the compiler provides in any errors or messages must be in one of the following two formats (items in <> brackets are optional):
  • Sun 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.

Java and Compiler Options

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

• -vm (specify the Java VM; command-line only)

• -compiler-executable (specify the Java compiler)

• -compiler-encoding-flag

• -compiler-output-file

• -compiler-pipe-output-flag

For some VM and compiler configurations, there may be problems with the way SQLJ normally invokes the compiler. The following option can be used to alleviate this:

• -passes

You can also pass options directly to the particular VM 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 Java VM (-vm)

Use the -vm option if you want to specify a particular Java VM 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 VM is invoked.

If you do not specify a directory path along with the name of the VM 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 and instructs 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 "Echo Command Line without Execution (-n)".

Command-line syntax

-vm=Java_VM_name 

Command-line example

-vm=/myjavadir/myjavavm

Properties file syntax

n/a

Properties file example

n/a

Default value

java

Name of 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 assumed 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.

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_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 aware of the file name. Otherwise SQLJ assumes that the compiler outputs to the standard output device (such as STDOUT on a UNIX system).

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

Run SQLJ in Two Passes (-passes)

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

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

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

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

4. The translator processes the compiler output.

5. The translator invokes your profile customizer, which customizes your profiles.

For some VM 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). Also, 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 Java VM, which runs the SQLJ translator for its first pass.

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

3. The VM is terminated.

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

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

6. The translator processes compiler output.

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

With this sequence, you circumvent any problems the Java VM may 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 Java class name as its argument.

Note: This option can be overridden using the -P-customizer option in your SQLJ command line (or properties file). For more information, see "Options to Pass to 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 VM 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 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".

---