Oracle8i SQLJ Developer's Guide and Reference
Release 8.1.5






Prev  Chap Top Next

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:


  • SQLJ fully supports Unicode 2.0 and Java Unicode escape sequences.

  • Encoding and conversion of characters in your embedded SQL operations and characters read from or written to the database is 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 your SQL DML operations that may 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:

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


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

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:

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.


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


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


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:

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:


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


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


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 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):



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

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


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.


  • 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 may 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 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:

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.


Before using native2ascii, you must ensure that the Java VM 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:

For example:

% native2ascii -encoding SJIS Foo.sqlj Temp.sqlj

For more information see the following Web site:



Copyright © 1999 Oracle Corporation.

All Rights Reserved.