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.

NLS functionality at runtime is transparent to the user, presuming your SQLJ source code and SQL character data use only characters that are within the database character set. SQL character data is transparently mapped into and out of Unicode.

Note that for multi-language applications, it is advisable to use a database that understands Unicode.

Notes: The SQLJ translator fully supports Unicode 2.0 and Java Unicode escape sequences. The SQLJ command-line utility, however, does not support Unicode escape sequences--you can use only native characters supported by the operating system. Command-line options requiring Unicode escape sequences can be entered in a SQLJ properties file instead, because properties files do support Unicode escape sequences. Encoding and conversion of characters in your embedded SQL operations, and characters read from or written to the database, are handled by JDBC directly; SQLJ does not play a role in this. If online semantics-checking is enabled during translation, however, you will be warned if there are characters within the text of your SQL DML operations that might not be convertible to the database character set. For information about JDBC NLS functionality, see the Oracle8i JDBC Developer's Guide and Reference.

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 JVM file.encoding property. If your source files use other encodings, then 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).

Note: Do not alter the file.encoding property to specify encodings for source files. This might impact other aspects of your Java operation and might offer only a limited number of encodings, depending on platform or operating system considerations.

The character encoding setting also determines how SQLJ error and status 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 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.

Notes: A character that is not representable in the encoding used, for either messages or source files, can always be represented as a Java Unicode escape sequence (of the form \uHHHH where each H is a hexadecimal digit). As a .sqlj source file is read and processed during translation, error messages quote source locations based on character position (not byte position) in the input encoding. Encoding settings, either set through the SQLJ -encoding option or the Java file.encoding setting, do 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 determine escape sequences--see "Using native2ascii for Source File Encoding".)

Overview of Language Support

SQLJ error and status reporting, either during translation or during runtime, uses the Java locale setting in the JVM 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).

Note: Java locale settings can support country and variant extensions in addition to language extensions. For example, consider ErrorMessages_de_CH_var1, where CH is the Swiss country extension of German, and var1 is an additional variant. SQLJ, however, currently supports only language extensions (de in this example), ignoring country and variant extensions.

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 generated 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 JVM 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)".

Note: If your -encoding is to be set routinely to the same value, then it is most convenient to specify it in a properties file, as in the second example above. For more information, see "Properties Files for Option Settings".

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 JVM properties in the SQLJ command line by using the SQLJ -J prefix. Options marked by this prefix are passed to the JVM.

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

-J-Dfile.encoding=SJIS

Note: Only a limited number of encodings might be available, depending on platform or operating system considerations.

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 JVM is invoked.

Notes: If your file.encoding, user.language, or any other Java property is to be set routinely to the same value, it is most convenient to specify -J settings in the SQLJ_OPTIONS environment variable. This way, you do not have to repeatedly specify them on the command line. The syntax is essentially the same as on the command line. For more information, refer to "SQLJ_OPTIONS Environment Variable for Option Settings". Remember that if you do not set the SQLJ -encoding option, then setting file.encoding will affect encoding for source files as well as error and status messages. Be aware that altering the file.encoding property might have unforeseen consequences on other aspects of your Java operations; furthermore, any new setting must be compatible with your operating system.

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

SQLJ Command-Line Example: Setting Encoding and Locale

Following is a complete SQLJ command line, including JVM 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, those running your SQLJ application can specify JVM properties such as file.encoding and user.language directly, as they invoke the JVM 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.getProperty() method, specifying the appropriate property. For 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.

There is also a getProperties() method that returns the values of all properties, but this will raise a security exception if you try to use it in code that runs in the server.

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

Note: To use SQLJ to translate source created by native2ascii, ensure that the JVM that invokes SQLJ has a file.encoding setting that supports some superset of 7-bit ASCII. This is not the case with settings for EBCDIC or Unicode encoding.

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

---