Oracle8i National Language Support Guide
Release 8.1.5

A67789-01

Library

Product

Contents

Index

Prev Next

B
Customizing Locale Data

A set of NLS data objects is included with every Oracle distribution set, some of which is customizable.

This appendix contains:

Customized Character Sets

It is possible to extend Oracle's character set definition files by adding user-defined characters to an existing Oracle character set.

Character set information and encoding are defined in text files. These character set definition text files contain descriptions of a character set and are specified so that a database administrator can modify or create a new character set easily. All characters are defined in terms of Unicode 2.0 code points. That is, each character is defined as a Unicode 2.0 character code value. Conversion between character sets is done by using Unicode as the intermediate form.

Once a character set definition file is created, 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 appendix allows you to convert and install character set definition text files into binary format, and merge it into an NLS data object set.

Be aware that this procedure does not ensure any of the following:

Character Set Definition Files

Character set information and encoding are defined in text files (with the suffix ".nlt"). Character set definition text files (*.nlt files) contain descriptions of a character set and are specified in a user-friendly format so that a database administrator can modify or create a new character set easily. All characters are defined in terms of Unicode 2.0 code points. That is, each character is defined as a Unicode 2.0 character code value.

Conversion between character sets is done by using Unicode as the intermediate form. The following file is a sample customized character set template character set definition file format:

Customized Character Set Definition File Format Template

# The following is a template of a customized character set definition file. 
# You may use this template to create a user-defined character set or copy 
# and modify an existing one. The convention used for naming character 
# set definition (.nlt) files is in the format: lx2dddd.nlt, where
#                    dddd = 4 digit character set ID in hex
# All letters in the definition file are case-insensitive. 

# Version number: specify the current loadable data version.
VERSION = <x.x.x.x.x>

# The following is the body of the definition file
DEFINE character_set

# Oracle supports a feature called 'base_char_set'. It allows you
# to extend an existing character set based on an existing Oracle supported 
# standard character set. Generally, you may only need to edit the
# following fields:

# Name and ID of the character set are required for any character sets.

# Character set name must be specified in a double quoted string.
# Rules for choosing a character set name: 
#          - Cannot use a character set name that is already in use. (Each
#                        character set must be assigned a unique character set name).
#          - Must consist of single-byte ASCII or EBCDIC characters only
#                        (single-byte compiler character set). 
#          - Cannot contain multibyte characters.
#          - Maximum length of 30 characters.
#          - Must start with an alphabetic character.
#          - Composed of alphanumeric characters only (e.g. no periods,
#                        dashes, underscore characters allowed)
#          - The name is case-insensitive.
# To register a unique character set name, send mail to
#  nlsreg@us.oracle.com.
   name = <text_string>

# Character set ID is specified as an integer value.
# Rules for choosing a character set ID:
#         - Cannot use a character set ID that is already in use. (Each
#                      character set must be assigned a unique character set ID.)
#         - Must be in the decimal range of 10000-20000
#         - Character set IDs must be registered with Oracle to receive a 
#           uniquely assigned character set ID number.
# To register a unique character set ID, send mail to nlsreg@us.oracle.com.
   id   = <integer>

# The "base_char_set" feature allows users to define the base character set in   
# a new character set definition file.
# The new character set will inherit all definitions from the base 
# character set, therefore, the user only needs to add the customized data 
# into the new character set definition file.

# The syntax of the base character set is:
#       base_char_set = <id> | <name>

#        - <id> or <name> should be a valid Oracle NLS character set id or name.
# Example is: base_char_set = "JA16EUC" or base_char_set = 830
base_char_set = <id> | <name>

# If you use base_char_set feature, remember you need to copy your base 
# character set definition file (text or binary format) from $ORA_NLS33 
# into the working directory specified by $ORANLS so that the new character 
# set can inherit the definition from the base character set.
# Example:
#  %cp $ORA_NLS33/lx2033e.nlt $ORANLS 
# or
#  %cp $ORA_NLS33/lx*33e.nlb $ORANLS  


# Character data is defined as a list of  <char_value>:<unicode_value> 
# pairs. <char_value> is a hex number specifying the complete character 
# value in this character set (e.g. 0xa1b1), while <unicode_value> is a 
# 16-bit hex number specifying its corresponding Unicode 2.0 character 
# value. 
# Alternatively, a range of characters can be specified with a corresponding 
# range of Unicode values. Each successive character in the 
# <start_char>-<end_char> range will be assigned to each successive 
# character in the <start_unicode>-<end_unicode> range. There must be 
# an equal number of characters in each range.
# User-defined characters must be assigned to characters in Unicode's 
# private use area, and in particular the range 0xe000 to 0xf4ff. The 
# remaining 1024 characters in the private use area are reserved for Oracle 
# private use.
# If you already defined "base_char_set", you only need to add the 
# customized character set mappings.
   character_data = {
<char_value>:<unicode_value>,
<start_char>-<end_char>:<start_unicode>-<end_unicode>,
...
   }

# A character classification list is used to specify the type of characters. 
# Valid values:
# UPPER LOWER DIGIT SPACE PUNCTUATION CONTROL 
#            HEX_DIGIT LETTER PRINTABLE 
# You only need to add customized characters' classification if you defined
# base_char_set.  
classification = {
<char_value> = { UPPER, LOWER, DIGIT, 
       SPACE, PUNCTUATION, CONTROL, 
       HEX_DIGIT, LETTER, PRINTABLE },
...
   }

# Lower-to-Upper case character relationships are defined as pairs, where 
# the first specifies the value of a character in this character set and the
# second specifies its uppercase value in this character set.  You may add 
# the customized case mapping only if needed.
   uppercase = {
<char_value>:<upper_char_value>,
<start_char>-<end_char>:<start_upper>-<end_upper>,
...
   }

# Upper-to-Lower case character relationships are defined as pairs, where 
# the first specifies the value of a character in this character set and the
# second specifies its lowercase value in this character set. You may add 
# the customized case mapping only if needed.
   lowercase = {
<char_value>:<lower_char_value>,
<start_char>-<end_char>:<start_lower>-<end_lower>,
...
   }

# There are a lot of other fields in an Oracle character set definition file.
# Presumably, you will only need the above fields, at most.

ENDDEFINE character_set	

Example of Character Set Customization

This section uses an example to introduce the steps required to create a new character set with an example. For this example, we will create a new character set based on Oracle's JA16EUC character set and add a few user defined characters.

Step 1. Register a New Character Set Name and ID

In order to maintain unique character set names and IDs, you must register the character name with Oracle to receive a uniquely assigned character set ID. Requests for character set name and ID registration can be sent to:

nlsreg@us.oracle.com

Attention: If the character set name and ID are not unique, you could experience incompatibilities between character sets and potential loss of data.

Note the following restrictions on character set names:

Rules for choosing a character set ID:

If a character set is derived from an existing Oracle character set, we recommend using the following character set naming convention:

<Oracle_character_set_name><organization_name>EXT<version>

Example:

If a company such as Sun Microsystems were adding user-defined characters to the JA16EUC character set, the following character set name might be appropriate:

 JA16EUCSUNWEXT1

where:

JA16EUC   is the character set name defined by Oracle  
SUNW   represents the organization name (company stock trading abbreviation for Sun Microsystems)  
EXT   specifies that this is an extension to the JA16EUC character set  
1   specifies the version  

For this example and all further steps, we will use the character set ID 10000 (hex value 0x2710).

Step 2. Create an NLS Text Boot File

The NLS binary boot files indicate which NLS data objects will be loaded into the database. Therefore, the binary boot file must be updated whenever a new character set is created. To update the binary boot file, you must create an entry for your new character set in a text boot file lx0boot.nlt first.

NLS Boot File Format

# The following is a template for an Oracle NLS boot file.

# Version number specifies the current loadable data version.
VERSION=<x.x.x.x.x>

# List the character set names and IDs that will be merged into the existing
# system boot file using the $ORACLE_HOME/bin/lxinst utility.
#
CHARACTER_SET
<name> <id>
<name> <id>
...	

Example:

Create a text boot file (lx0boot.nlt) in the working directory.

% vi /tmp/lx0boot.nlt

To add JA16EUCSUNWEXT1, set:

VERSION=2.1.0.0.0

CHARACTER_SET
"JA16EUCSUNWEXT1"  10000	

where the version number is based on the Oracle release. Refer to the version number listed in the existing lx2*.nlt files for the latest version number.

Note that it is possible to list multiple user defined character sets in a single lx0boot.nlt file. For example:

VERSION=2.1.0.0.0

CHARACTER_SET
"JA16EUCSUNWEXT1"  10000
"ZH16EUCSUNWEXT1"  10001	
Step 3. Create a Character Set Definition File (lx2dddd.nlt)

The convention used for naming character set definition (.nlt) files is in the format: lx2dddd.nlt, where dddd = 4 digit Character Set ID in hex.

A few things to note when editing a character set definition file:

There is a feature, 'BASE_CHAR_SET', that can make customized character set support easier. Since you are extending an existing Oracle character set, you can use the 'BASE_CHAR_SET' feature which causes the new character set to inherit all definitions from the base character set and the user only need add user-specific customized character set data.

Example:

Assume you are extending the JA16EUC character set and have added some new customized character set data to it.

Based on the character set ID of 10000 you specified in Step 1, name the new character set definition file lx22710.nlt (based on the character set id hex value of 0x2710).

This example uses /tmp as the working directory. Edit the new character definition file with an editor.

% vi /tmp/lx22710.nlt
VERSION = 2.1.0.0.0

DEFINE character_set
  name = "JA16EUCSUNWEXT1"
  id = 10000
  base_char_set = 830
  character_data = {
     0x9a41 : 0xe001,
     0x9a42 : 0xe002,
  }
  classification = {
     0x9a41 = { LETTER, LOWER },
     0x9a42 = { LETTER, UPPER },
  }
  uppercase = {
     0x9a41 : 0x9a42,
  }
  lowercase = { 
     0x9a42 : 0x9a41,
  }
ENDDEFINE character_set

Refer to "Customized Character Set Definition File Format Template" for more information about the format of the character set definition files. Minimally, you will need to set the character set name, character set ID and, base character set, add customized character data and classification fields.

Step 4. 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 prior to generating and installing .nlb files.

% cd $ORA_NLS33
% cp lx0boot.nlb lx0boot.nlb.orig
% cp lx1boot.nlb lx1boot.nlb.orig
Step 5. 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 you must make sure to regenerate them on each platform and also install these files on both the server and clients.

You use the lxinst utility to create both the binary character definition files (lx2dddd.nlb) and update the NLS boot file (lx*boot.nlb).

Example:

The lxinst utility will make use of the existing system boot file. Therefore, copy the existing binary system boot file into the directory specified by SYSDIR. For this example, specify SYSDIR to the working directory (/tmp).

% 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 Step 2 & 3 should reside in the directory specified by ORANLS, for this example, specify it to be /tmp. Also, since we define JA16EUC (Id 830 in hex value 033e) as "BASE_CHAR_SET", the base definition file, text-format (lx2033e.nlt) or binary format (lx*033e.nlb), should be in the directory ORANLS too, so that the new character set can inherit all definitions from it.

% cp lx2033e.nlt /tmp

or

% cp lx*033e.nlb /tmp

Use the lxinst utility to generate a binary character set definition file (lx22710.nlb) in the directory specified by 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.

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

Then, 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 is lx5*.nlb or lx6*.nlb or both, install them too:

% cp /tmp/lx22710.nlb $ORA_NLS33
% cp /tmp/lx52710.nlb $ORA_NLS33
% cp /tmp/lx62710.nlb $ORA_NLS33
Step 6. Repeat for Each Platform

You must repeat Step 5 on each hardware platform since 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 7. Create the Database Using New Character Set

After installing the .nlb files, you must shutdown 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.

Customized Calendars

Overview

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

Syntax

The Calendar Utility is invoked directly from the command line:

LXEGEN

There are no parameters.

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. Please see the 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 would be lxecal.nlb were you to define deviation days for the Arabic Hijrah calendar. 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.

Utilities

The Oracle server includes the following three utilities to assist you in maintaining NLS data:

NLS Data Installation Utility
(lxinst)  

Generate binary-format data objects from their text-format versions. Use this when you receive NLS data updates or if you create your own data objects.  

NLS Calendar Utility
(lxegen)  

Generate a binary file with the appropriate format for the calendar data.  

NLS Configuration Utility
(lxbcnf)  

Create and edit user boot files.  

NLS Data Installation Utility

Overview

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 Oracle8i, 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 described here will allow 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. For information about how this file is generated, see "NLS Configuration Utility".  

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:

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

Warning: When you want to create a new character set, you must register with Oracle Corporation by sending email to nlsreg@us.oracle.com, which will ensure that your character set has a unique name and ID.

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, for binary files, .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  

NLS Configuration Utility

Overview

At installation, all available NLS objects are stored and referenced in the system boot file. This file is used to load the available NLS data.

The NLS Configuration Utility allows you to configure your boot files such that only the NLS objects that you require will be loaded. It does this by creating a user boot file, which contains a subset of the system boot file. Data loading by the kernel will then be performed according to the contents of this user boot file.

The NLS Configuration Utility allows you to configure a user boot file, either by selecting NLS objects from the installed system boot file which will then be included in a new user boot file, or by reading entries from an existing user boot file and possibly removing one or more of them and saving the remaining entries into a new user boot file. Note that you will not be allowed to actually "edit" an existing boot file as it may be in use by either the RDBMS or some other Oracle tool (that is, saving of boot file entries is never done to an existing one).

You may also use the NLS Data Installation Utility to check the integrity of an existing user boot file. This is necessary since the contents of existing NLS objects may change over time, and the installation of a new system boot file may cause user boot files to become out of date. Thus, a comparison function will notify you when it finds that the file is out of date and will allow you to create a new user boot file.

Syntax

The NLS Configuration Utility is invoked from the command line with the following syntax:

LXBCNF [ORANLS=pathname] [userbootdir=pathname] [DESTDIR=pathname]
[HELP=[yes | no]]

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, the NLS Installation Utility uses the value in the environment variable ORA_NLS (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 or move 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.  

Menus

When the NLS Configuration Utility is started you are presented with the following top-level menu:

File Menu

The file menu contains choices pertaining to file operations. Options are:

Table B-1 File Menu Options
Menu Item   Options   Description  

System Boot File  

Open  

This will open the current system boot file. Note that the Open menu item will be "greyed out" as soon as a system Boot File has been successfully read. Also note that you cannot perform any other functions until you have opened a system boot file.  

User Boot File  

New  

Open a new user boot file.  

 

Read  

Read the contents of an existing user boot file.  

 

Save  

Save changes to the new user boot file.  

 

Revert  

Undo the changes to the currently open user boot file made since the last "Save".  

Choose Printer  

 

Not implemented in this release.  

Page Setup  

 

Not implemented in this release.  

Print  

 

Not implemented in this release.  

Quit  

 

Exit from the file.  

Note: As long as the system boot file has not been opened and read, all these menu items will remain "greyed out". That is, you cannot build a user boot file as long as there is no system boot file information available.

As soon as you select New to create a new user boot file, the following NLS objects will be created in the new file by default:

If you choose to read the contents of an existing user boot file, the entries read will be checked against the entries of the system boot file. If an entry is found which does not exist in the system boot file, you will receive a warning, and the entry will not be included.

Edit Menu

The Edit Menu contains choices for editing information that you enter in any of the dialogs or windows of the NLS Configuration Utility.

Action Menu

The Action Menu contains choices for performing operations on the user boot file. Note that this menu is available only in the character mode NLS Configuration Utility.

Copy Item  

Copies the selected item from the system boot file to the user boot file.  

Delete Item  

Deletes the selected item from the user boot file.  

Windows Menu

The Windows Menu allows you to either activate certain windows or set the focus to an already open window (the latter is meant for character-mode platforms). Whenever a new window is opened, its name will be added to the Windows Menu automatically.

NLS Defaults  

Not implemented in this release.  

Help Menu

This menu provides functions which allow you to retrieve various levels of help about the NLS Configuration Utility.

About  

Shows version information for the NLS Configuration Utility.  

Help System  

Not implemented in this release.  




Prev

Next
Oracle
Copyright © 1999 Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index