Oracle9i Globalization Support Guide
Release 1 (9.0.1)

Part Number A90236-02
Go To Documentation Library
Go To Product List
Book List
Go To Table Of Contents
Go To Index

Master Index


Go to previous page Go to next page

Customizing Locale Data

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:

Customizing Character Sets

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.

Character Set Customization Example

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:

Step 1. Back up the NLS binary boot files

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:

% cd $ORA_NLS33
% cp lx0boot.nlb lx0boot.nlb.orig
% cp lx1boot.nlb lx1boot.nlb.orig

Step 2. Generate and install the NLB files

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.

Use the lxinst utility or the Locale Builder to create both the binary character definition files (lx2dddd.nlb) and update the NLS boot file (lx*boot.nlb).

Example 12-1 lxinst Example

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

% cp lx1boot.nlb /tmp

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

% cp lx2033e.nlt /tmp


% cp lx*033e.nlb /tmp

Use the 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 ORANLS, SYSDIR, and DESTDIR all to be /tmp. Enter the following command:

% $ORACLE_HOME/bin/lxinst oranls=/tmp sysdir=/tmp destdir=/tmp

Install the newly generated binary boot file (lx1boot.nlb) into the ORA_NLS33 directory:

% cp /tmp/lx1boot.nlb $ORA_NLS33/lx1boot.nlb

Finally, install the new character set definition file (lx2*.nlb) into the ORA_NLS33 directory. If there are files with names similar to lx5*.nlb or lx6*.nlb, then install them, too:

% cp /tmp/lx22710.nlb $ORA_NLS33
% cp /tmp/lx52710.nlb $ORA_NLS33
% cp /tmp/lx62710.nlb $ORA_NLS33

Step 3. Repeat for Each Platform

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.

Step 4. Create the Database Using New Character Set

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.

Using User-Defined Character Sets and Java

Creating Character Set Definition 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 ( into your Oracle Home directory. The installation steps are as follows:


$ORACLE_HOME/JRE/bin/jre -classpath $ORACLE_HOME/jlib/$ORACLE_
HOME/jlib/ Ginstall <lx22710>.nlt

On Windows:

%JREHOME%\bin\jre.exe -classpath %ORACLE_HOME%/jlib/;%ORACLE_
HOME%/jlib/  Ginstall <lx22710>.nlt

where %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 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 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/
               $ORACLE_HOME/jlib/ Ginstall <lx22710>.nlt

$ORACLE_HOME/JRE/bin/jre -classpath $ORACLE_HOME/jlib/
               $ORACLE_HOME/jlib/ Ginstall <lx22711>.nlt

$ORACLE_HOME/JRE/bin/jre -classpath $ORACLE_HOME/jlib/
               $ORACLE_HOME/jlib/ Ginstall <lx22712>.nlt

lx22710.nlt, lx22711.nlt and lx22712.nlt will all be contained in

After has been created, store it in the
$ORACLE_HOME/ocommon/nls/admin/data directory. For example:

% cp $ORACLE_HOME/ocommon/nls/admin/data

Enabling Java and User-Defined Character Sets

There are three Java components where you may want to add the file:

Customizing Time Zone Data

The time zone files contain the valid time zone names. The following information is included for each zone:

To enable the use of the larger time zone data file, you must:

  1. Shut down the database.

  2. Set the ORA_TZFILE environment variable to the full pathname of the location for the timezlrg.dat file.

  3. Restart the database.

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:


Customizing Calendars

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.

NLS Calendar Utility


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.


The location of files is platform-dependent. See your platform-specific Oracle documentation for information about the location of files on your system. 

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

NLS Data Installation Utility

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. 

HELP=[yes | no] 

If "yes", a help message describing the syntax for the NLS Installation Utility will be displayed. 

[0 | 1 | 2 | 3]]

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.  

Return Codes

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.  


Use lxinst to install customized character sets by completing the following tasks:

Object Types

Only character set object types are currently supported for customizing.

Object IDs

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.

Object Names

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

Data Object File Names

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



Text-format character set definition, ID=10001 


Text-format installation boot file 


Binary system boot file 


Binary character set definition, ID=10001 

Go to previous page Go to next page
Copyright © 1996-2001, Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Go To Product List
Book List
Go To Table Of Contents
Go To Index

Master Index