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

---