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

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

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