NLS Support in the Translator and Runtime

Oracle SQLJ uses Java's built-in NLS capabilities. This section discusses the basics of SQLJ support for NLS and native character encoding, starting with background information covering some of the implementation details of character encoding and language support in Oracle SQLJ. This is followed by discussion of options available through the Oracle SQLJ command line that allow you to adjust your NLS configuration.

Some prior knowledge of Oracle NLS is assumed, particularly regarding character encoding and locales. For information, see the Oracle8i National Language Support Guide.

Character Encoding and Language Support

There are two main areas of SQLJ NLS support:

• character encoding

  There are three parts to this: 1) character encoding for reading and generating source files during SQLJ translation; 2) character encoding for generating error and status messages during SQLJ translation; and 3) character encoding for generating error and status messages when your application runs.

• language support

  This determines which translations of error and status message lists are used when SQLJ outputs messages to the user, either during SQLJ translation or SQLJ runtime.

Overview of Character Encoding

The character encoding setting for source files tells Oracle SQLJ two things:

• how source code is represented in .sqlj and .java input files that the SQLJ translator must read

• how SQLJ should represent source code in .java output files that it generates

By default, SQLJ uses the encoding indicated by the Java VM file.encoding property. If your source files use other encodings, you must indicate this to SQLJ so that appropriate conversion can be performed.

Use the SQLJ -encoding option to accomplish this. SQLJ also passes the -encoding setting to the compiler for it to use in reading .java files (unless the SQLJ -compiler-encoding-flag is off).

The character encoding setting for error and status messages determines how SQLJ messages are represented when output to the user, either during translation or during runtime when the end-user is running the application. This is set according to the file.encoding property and is unaffected by the SQLJ -encoding option.

For source file encoding, you can use the -encoding option to specify any character encoding that is supported by your Java environment. If you are using the Sun Microsystems JDK, these are listed in the native2ascii documentation, which you can find at the following Web site:

http://www.javasoft.com/products/jdk/1.1/docs/tooldocs/solaris/native2ascii.html

Dozens of encodings are supported by the Sun Microsystems JDK. These include 8859_1 through 8859_9 (ISO Latin-1 through ISO Latin-9), JIS (Japanese), SJIS (shift-JIS, Japanese), and UTF8.

Overview of Language Support

SQLJ error and status reporting, either during translation or during runtime, uses the Java locale setting in the VM user.language property. Users typically do not have to alter this setting.

Language support is implemented through message resources that use key/value pairs. For example, where an English-language resource has a key/value pair of "OkKey", "Okay", a German-language resource has a key/value pair of "OkKey", "Gut". The locale setting determines which message resources are used.

SQLJ supports locale settings of en (English), de (German), fr (French), and ja (Japanese).

SQLJ and Java Settings for Character Encoding and Language Support

Oracle SQLJ provides syntax that allows you to set the following:

• the character encoding used by the SQLJ translator and Java compiler in representing source code

  Use the SQLJ -encoding option.

• the character encoding used by the SQLJ translator and runtime in representing error and status messages

  Use the SQLJ -J prefix to set the Java file.encoding property.

• the locale used by the SQLJ translator and runtime for error and status messages

  Use the SQLJ -J prefix to set the Java user.language property.

Setting Character Encoding for Source Code

Use the SQLJ -encoding option to determine the character encoding used in representing .sqlj files read by the translator, .java files output by the translator, and .java files read by the compiler (the option setting is passed by SQLJ to the compiler, unless the SQLJ -compiler-encoding-flag is off).

This option can be set on the command line or SQLJ_OPTIONS environment variable as in the following example:

-encoding=SJIS

Or it can be set in a SQLJ properties file as follows:

sqlj.encoding=SJIS

If the encoding option is not set, then both the translator and compiler will use the encoding specified in the Java VM file.encoding property. This can also be set through the SQLJ command line, as discussed in "Setting Character Encoding and Locale for SQLJ Messages".

For more information, see "Encoding for Input and Output Source Files (-encoding)" and "Compiler Encoding Support (-compiler-encoding-flag)".

Setting Character Encoding and Locale for SQLJ Messages

Character encoding and locale for SQLJ error and status messages output to the user, during both translation and runtime, are determined by the Java file.encoding and user.language properties. Although it is typically not necessary, you can set these and other VM properties in the SQLJ command line by using the SQLJ -J prefix. Options marked by this prefix are passed to the VM.

Set the character encoding as in the following example (which specifies shift-JIS Japanese character encoding):

-J-Dfile.encoding=SJIS

Set the locale as in the following example (which specifies Japanese locale):

-J-Duser.language=ja

The -J prefix can be used on the command line or SQLJ_OPTIONS environment variable only. It cannot be used in a properties file because properties files are read after the VM is invoked.

For additional information about the SQLJ -J prefix, see "Command-Line Syntax and Operations" and "Options to Pass to Java VM (-J)".

SQLJ Command Line Example: Setting Encoding and Locale

Following is a complete SQLJ command line, including VM file.encoding and user.language settings:

sqlj -encoding=8859_1 -J-Dfile.encoding=SJIS -J-Duser.language=ja Foo.sqlj

This example uses the SQLJ -encoding option to specify 8859_1 (Latin-1) encoding for source code representation during SQLJ translation. This encoding is used by the translator in reading the .sqlj input file and in generating the .java output file. The encoding is then passed to the Java compiler to be used in reading the generated .java file. (The -encoding option, when specified, is always passed to the Java compiler unless the SQLJ -compiler-encoding-flag is disabled.)

For error and status messages output during translation of Foo.sqlj, the SQLJ translator uses the SJIS encoding and the ja locale.

NLS Manipulation Outside of SQLJ

This section discusses ways to manipulate your NLS configuration outside of SQLJ.

Setting Encoding and Locale at Application Runtime

As with any end user running any Java application, end users running your SQLJ application can specify VM properties such as file.encoding and user.language directly as they invoke the VM to run your application. This determines the encoding and locale used for message output as your application executes.

They can accomplish this as in the following example:

java -Dfile.encoding=SJIS -Duser.language=ja Foo

This will use SJIS encoding and Japanese locale.

Using API to Determine Java Properties

In Java code, you can determine values of Java properties by using the java.lang.System.getProperties() method (or the getProperty() method, if you specify a particular property).

The following is an example:

public class Settings
{
   public static void main (String[] args)
   {
      System.out.println("Encoding: " + System.getProperty("file.encoding")
                       + ", Language: " + System.getProperty("user.language"));
   }
}

You can compile this and run it as a standalone utility.

You can get information about java.lang.System at the following Web site:

http://www.javasoft.com/products/jdk/1.1/docs/api/java.lang.System.html

Using native2ascii for Source File Encoding

If you are using the Sun JDK, there is an alternative to having SQLJ do the character encoding for your source files. You can use the utility native2ascii to convert sources with native encoding to sources in 7-bit ASCII with Unicode escape sequences.

Run native2ascii as follows:

% native2ascii <options> <inputfile> <outputfile>

Standard input or standard output are used if you omit the input file or output file. Two options are supported:

• -reverse (reverse the conversion; convert from Latin-1 or Unicode to native encoding)

• -encoding <encoding>

For example:

% native2ascii -encoding SJIS Foo.sqlj Temp.sqlj

For more information see the following Web site:

http://www.javasoft.com/products/jdk/1.1/docs/tooldocs/solaris/native2ascii.html

---