12
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

• Customizing Time Zone Data

• Customizing Calendars

• NLS Data Installation Utility

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:

• Input of user-defined characters must still be managed by the system, either through an input method or a virtual keyboard.

• Display of user-defined characters must still be managed by the system or the application. In the case of display, a new font specification may be needed. Many vendors provide support of a font editor. After a new font is created, it must be installed onto your system and made accessible to application programs.

  See Also: Chapter 11, "Oracle Locale Builder Utility" for more information about how to customize a character set definition file

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

or

% 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 (gss_custom.zip) into your Oracle Home directory. The installation steps are as follows:

On UNIX:

$ORACLE_HOME/JRE/bin/jre -classpath $ORACLE_HOME/jlib/gss-1_1.zip:$ORACLE_
HOME/jlib/gss_charset-1_2.zip Ginstall <lx22710>.nlt

On Windows:

%JREHOME%\bin\jre.exe -classpath %ORACLE_HOME%/jlib/gss-1_1.zip;%ORACLE_
HOME%/jlib/gss_charset-1_2.zip  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 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

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

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

% cp gss_custom.zip $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 gss_custom.zip file:

• Java Virtual Machine (for Java in the database)

  On UNIX:

  %loadjava -u sys/<passwd> -grant EXECUTE -synonym -r -r -v gss_custom.zip
  
  

  On Windows:

  loadjava -u sys/<passwd> -grant EXECUTE -synonym -r -r -v gss_custom.zip
  
  

  This loads it into the database. Note that <password> needs to be replaced by the password for SYS.

• Apache (for using servlets)

  Edit the file jserv.properties as follows:

  On UNIX, add the line:

  wrapper.classpath = $ORACLE_HOME/ocommon/nls/admin/data/gss_custom.zip
  
  

  On Windows, add the line:

  wrapper.classpath = %ORA_HOME%\ocommon\nls\admin\data\gss_custom.zip
  
  

• Client environment (for JDBC on the client)

  On UNIX:

  %set CLASSPATH $ORACLE_HOME/ocommon/nls/admin/data/gss_custom.zip
  
  

  On Windows:

  Add the path %ORACLE_HOME%\ocommon\nls\admin\data\gss_custom.zip to your existing CLASSPATH.

  See Also: Chapter 11, "Oracle Locale Builder Utility" for more information about user-defined character sets

Customizing Time Zone Data

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

• Offset from UTC (Coordinated Universal Time)

• Transition times for daylight savings

• Abbreviations for standard time and daylight savings time

  Abbreviations are only used in conjunction with the zone names. There are 2 timezone files under the Oracle installation directory (ORACLE_HOME):

• oracore/zoneinfo/timezone.dat

  This is the default. It contains the most commonly used time zones and is smaller for better database performance.

• oracore/zoneinfo/timezlrg.dat

  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:

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:

SELECT * FROM V$TIMEZONE_NAMES;

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

Usage

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.

Note: 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.

Syntax

The Calendar Utility is invoked directly from the command line:

LXEGEN

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.

Syntax

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

where

ORANLS=pathname	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.
SYSDIR=pathname	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.
DESTDIR=pathname	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.
[WARNING= [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:

0	The generation of the binary boot and object files, and merge of the installation and system boot files completed successfully.
1	Installation failed: the NLS Installation Utility will exit with an error message that describes the problem.

Usage

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

• Create a text-format boot file (lx0boot.nlt) containing references to new data objects.
  • Data objects can be generated only if they are referenced in the boot file.

  • You can generate only character set object types.

• Create your new text-format data object files.

  See Also: "Data Object File Names" for naming conventions

  Note: Your distribution set contains a character set definition demonstration file that you can use as a reference or as a template. On UNIX-based systems, this file is located in $ORACLE_HOME/demo/*.nlt

• Invoke lxinst as described above (using the appropriate parameters) to generate new binary data object files. These files will be generated in the directory you specified in ORANLS.
  • lxinst also 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 DESTDIR.

    Note: As always, you should have backups of any existing files you do not want overwritten.

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:

ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_- and <space>

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:

lxtdddd

where:

t	1 digit object type (hex)
dddd	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.

Examples:

lx22711.nlt	Text-format character set definition, ID=10001
lx0boot.nlt	Text-format installation boot file
lx1boot.nlb	Binary system boot file
lx22711.nlb	Binary character set definition, ID=10001