Oracle8i SQLJ Developer's Guide and Reference Release 8.1.5 A64684-01 |
|
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.
There are two main areas of SQLJ NLS support:
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.
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.
Notes:
|
The character encoding setting for source files tells Oracle SQLJ two things:
.sqlj
and .java
input files that the SQLJ translator must read
.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
.
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).
Oracle SQLJ provides syntax that allows you to set the following:
Use the SQLJ -encoding
option.
Use the SQLJ -J
prefix to set the Java file.encoding
property.
Use the SQLJ -J
prefix to set the Java user.language
property.
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)".
Note:
If your |
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
Note: 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):
-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.
Note:
|
For additional information about the SQLJ -J
prefix, see "Command-Line Syntax and Operations" and "Options to Pass to Java VM (-J)".
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.
This section discusses ways to manipulate your NLS configuration outside of SQLJ.
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.
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
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