|Oracle9i Globalization Support Guide
Release 1 (9.0.1)
Part Number A90236-02
A set of NLS data objects is included with every Oracle distribution set, some of which is customizable. This chapter illustrates how to customize these data objects. It contains the following topics:
After a locale definition file is created using the Locale Builder, it must be compiled into platform-specific binary files that can be dynamically loaded into memory at runtime. The NLS Data Installation Utility (
lxinst) described in this chapter allows you to convert and install locale definition text files into binary format, and merge it into an NLS data object set.
This section uses an example to introduce the steps required to create a new character set. For this example, we will create a new character set based on Oracle's JA16EUC character set and add a few user-defined characters.
Be aware of the following limitations:
Oracle recommends that you backup the NLS installation boot file (
lx0boot.nlb) and the NLS system boot file (
lx1boot.nlb) in the
ORA_NLS33 directory before generating and installing NLB files. Enter the following commands:
Now you are ready to generate and install the new NLB files. The NLB files are platform-dependent, so regenerate them on each platform and also install these files on both the server and clients.
lxinst utility or the Locale Builder to create both the binary character definition files (
.nlb) and update the NLS boot file (
lxinst utility uses the existing system boot file. Therefore, copy the existing binary system boot file into the directory specified by
SYSDIR. For this example, define
SYSDIR to be the working directory (
/tmp). Enter the following command:
The new character set definition file (
lx22710.nlt) and the text boot file containing the new character set entry (
lx0boot.nlt) that was created in Steps 2 and 3 should reside in the directory specified by
ORANLS. For this example, specify it to be
/tmp. Also, since we define B
ASE_CHAR_SET (the base definition file) to be JA16EUC (Id 830 in hex value 033e), its NLT file (
lx2033e.nlt) or NLB file (
lx*033e.nlb) should also be in the directory specified by
ORANLS, so that the new character set can inherit all definitions from it.Enter one of the following commands:
lxinst utility to generate an NLB file (
lx22710.nlb) for the character set in the directory specified by the
ORANLS and an updated binary boot file (
lx1boot.nlb) in the directory specified by
DESTDIR. For this example, define
DESTDIR all to be
/tmp. Enter the following command:
Install the newly generated binary boot file (
lx1boot.nlb) into the
Finally, install the new character set definition file (
lx2*.nlb) into the
ORA_NLS33 directory. If there are files with names similar to
lx6*.nlb, then install them, too:
You must repeat Step 2 on each hardware platform because the NLB file is a platform-specific binary. It must also be repeated for every system that must recognize the new character set. Therefore, you should compile and install the new NLB files on both server and client machines.
After installing the NLB files, shut down and restart the database server in order to initialize NLS data loading.
After bringing the database server back up, create the new database using the newly created character set.
To use the new character set on the client side, simply exit the client (such as Enterprise Manager or SQL*Plus) and re-invoke it after installing the NLB files.
If you have any Java products (for example, JDBC or SQLJ) in your applications and want them to support user-defined characters, you must generate and install a special Java zip file (
gss_custom.zip) into your Oracle Home directory. The installation steps are as follows:
$ORACLE_HOME/JRE/bin/jre -classpath $ORACLE_HOME/jlib/gss-1_1.zip:$ORACLE_ HOME/jlib/gss_charset-1_2.zip Ginstall <lx22710>.nlt
%JREHOME%\bin\jre.exe -classpath %ORACLE_HOME%/jlib/gss-1_1.zip;%ORACLE_ HOME%/jlib/gss_charset-1_2.zip Ginstall <lx22710>.nlt
%JREHOME% is the
C:\Program Files\Oracle\jre\version_num directory.
lx22710.nlt is an example of an user-defined character set created using the Oracle Locale Builder.
The above commands generate a
gss_custom.zip file in the current directory. If you need to add support for more than one user-defined character set, you can append their definitions to the same
gss_custom.zip file by re-issuing the above command for each of the additional user-defined character sets. For example:
$ORACLE_HOME/JRE/bin/jre -classpath $ORACLE_HOME/jlib/gss-1_1.zip: $ORACLE_HOME/jlib/gss_charset-1_2.zip Ginstall <lx22710>.nlt
$ORACLE_HOME/JRE/bin/jre -classpath $ORACLE_HOME/jlib/gss-1_1.zip: $ORACLE_HOME/jlib/gss_charset-1_2.zip Ginstall <lx22711>.nlt $ORACLE_HOME/JRE/bin/jre -classpath $ORACLE_HOME/jlib/gss-1_1.zip: $ORACLE_HOME/jlib/gss_charset-1_2.zip Ginstall <lx22712>.nlt
lx22712.nlt will all be contained in
gss_custom.zip has been created, store it in the
$ORACLE_HOME/ocommon/nls/admin/data directory. For example:
There are three Java components where you may want to add the
This loads it into the database. Note that
> needs to be replaced by the password for
Edit the file
jserv.properties as follows:
On UNIX, add the line:
On Windows, add the line:
Add the path
%ORACLE_HOME%\ocommon\nls\admin\data\gss_custom.zip to your existing
Chapter 11, "Oracle Locale Builder Utility" for more information about user-defined character sets
The time zone files contain the valid time zone names. The following information is included for each zone:
Abbreviations are only used in conjunction with the zone names. There are 2 timezone files under the Oracle installation directory (
This is the default. It contains the most commonly used time zones and is smaller for better database performance.
This file contains the larger set of defined time zones and should be used by customers who require time zones that are not defined in the default
timezone.dat file. This larger set of time zone information might affect performance.
To enable the use of the larger time zone data file, you must:
ORA_TZFILEenvironment variable to the full pathname of the location for the
After the larger
timezlrg.dat is used, it must continue to be used unless the user is sure that none of the non-default zones are used for data that is stored in the database. Also, all databases that share information must use the same timezone data file.
To view the timezone names, issue the following query:
A number of calendars besides Gregorian are supported. Although all of them are defined with data linked directly into NLS, some of them may require the addition of ruler eras (in the case of imperial calendars) or deviation days (in the case of lunar calendars) in the future. In order to do this without waiting for a new release, you can define the additional eras or deviation days in an external file, which is then automatically loaded when executing the calendar functions.
The calendar data is first defined in a text-format definition file. This file must be converted into binary format before it can be used. The Calendar Utility described here allows you to do this.
The Calendar Utility takes as input a text-format definition file. The name of the file and its location are hard-coded as a platform-dependent value. On UNIX platforms, the file name is
lxecal.nlb, and its location is
$ORACLE_HOME/ocommon/nls. A sample calendar definition file is included in the distribution.
lxegen executable produces as output a binary file containing the calendar data in the appropriate format. The name of the output file is also hard-coded as a platform-dependent value. On UNIX, the name is
lxecal.nlb The file will be generated in the same directory as the text-format file, and an already-existing file will be overwritten.
Once the binary file has been generated, it will automatically be loaded during system initialization. Do not move or rename the file, as it is expected to be found in the same hard-coded name and location.
The Calendar Utility is invoked directly from the command line:
There are no parameters.
When you order an Oracle distribution set, a default set of NLS data objects is included. Some NLS data objects are customizable. For example, in Oracle9i, you can extend Oracle's character set definition files to add user-defined characters. These NLS definition files must be converted into binary format and merged into the existing NLS object set. The NLS Data Installation Utility allows you to do this.
Along with the binary object files, a boot file is generated by the NLS Data Installation Utility. This boot file is used by the modules to identify and locate all the NLS objects which it needs to load.
To facilitate boot file distribution and user configuration, three types of boot files are defined:
Installation Boot File
The boot file included as part of the distribution set.
System Boot File
The boot file generated by the NLS Data Installation Utility which loads the NLS objects. If the user already has an installed system boot file, its contents can be merged with the new system boot file during object generation.
User Boot File
A boot file that contains a subset of the system boot file information.
The NLS Data Installation Utility is invoked from the command line with the following syntax:
LXINST [ORANLS=pathname] [SYSDIR=pathname] [DESTDIR=pathname] [HELP=[yes | no]] [WARNING=[0 | 1 | 2 | 3]]
Specifies where to find the text-format boot and object files and where to store the new binary-format boot and object files. If not specified, NLS Installation Utility uses the value in the environment variable ORA_NLS33 (or the equivalent for your operating system). If both are specified, the command line parameter overrides the environment variable. If neither is specified, the NLS Installation Utility will exit with an error.
Specifies where to find the existing system boot file. If not specified, the NLS Installation Utility uses the directory specified in the initialization file parameter ORANLS. If there is no existing system boot file or the NLS Installation Utility is unable to find the file, it will create a new file and copy it to the appropriate directory.
Specifies where to put the new (merged) system boot file. If not specified, the NLS Installation Utility uses the directory specified in the initialization file parameter ORANLS. Any system boot file that exists in this directory will be overwritten, so make a backup first.
If "yes", a help message describing the syntax for the NLS Installation Utility will be displayed.
If you specify "0", no warning messages are displayed. If you specify "1", all messages for level 1 will be displayed. If you specify "2", all messages for levels 2 and 1 will be displayed. If you specify "3", all messages for levels 3, 2, and 1 will be displayed.
You may receive the following return codes upon executing lxinst:
The generation of the binary boot and object files, and merge of the installation and system boot files completed successfully.
Installation failed: the NLS Installation Utility will exit with an error message that describes the problem.
lxinst to install customized character sets by completing the following tasks:
lx0boot.nlt) containing references to new data objects.
lxinstas described above (using the appropriate parameters) to generate new binary data object files. These files will be generated in the directory you specified in
lxinstalso generates both a new installation boot file and system boot file. If you have a previous NLS installation and want to merge the existing information with the new in the system boot file, copy the existing system boot file into the directory you specified in
SYSDIR. A new system boot file containing the merged information is generated in the directory specified in
Only character set object types are currently supported for customizing.
NLS data objects are uniquely identified by a numeric object ID. The ID may never have a zero or negative value.
In general, you can define new objects as long as you specify the object ID within the range 10000-20000.
Only a very restricted set of characters can be used in object names:
Object names must start with an alphabetic character. Language, territory, and character set names cannot contain an underscore character, but linguistic definition names can. There is no case distinction in object names, and the maximum size of an object name is 30 bytes (excluding terminating null).
The system-independent object file name is constructed from the generic boot file entry information:
1 digit object type (hex)
4 digit object ID (hex)
The installation boot file name is
lx0BOOT; the system boot file name is
lx1BOOT; user boot files are named
lx2BOOT. The file extension for text format files is
.nlt. The file extension for binary files is
Text-format character set definition, ID=10001
Text-format installation boot file
Binary system boot file
Binary character set definition, ID=10001