Release 8.0
A58244-01
 Library |
 Product |
 Contents |
 Index |
| Oracle8 Utilities Release 8.0 A58244-01 |
|
This chapter describes three utilities:
For platform-specific details on the use of these utilities, please see your operating system-specific Oracle documentation.
When you order an Oracle distribution set, a default set of NLS data objects is included. Some NLS data objects are customizable. For example, starting with Oracle8, 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. See "NLS Configuration Utility" on page 9-16 for information about how this file is generated. |
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
You may receive the following return codes upon executing LXINST:
You use LXINST to install your customized character sets by completing the following tasks:
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
Attention: As always, you should have backups of any existing files you do not want overwritten.
This section should be read by those who intend to create their own NLS data objects. It details the formats, contents, and restrictions expected by the NLS Data Installation Utility.
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 customized character set template character set definition file format you can use in Oracle release 8.0.4:
#The following is a template of an Oracle 8.0.4 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 # In 8.0.4, we support a new 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 is in only since version 8.0.4. It 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 Oracle character set definition file. # Presumably, you will only need above fields at most. However, you can # always refer to our UDC8.0.3 white paper to find out all the information # if you want to customization other fields or send email to # nlsinfo@us.oracle.com for information. ENDDEFINE character_set
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.
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..
Only a very restricted set of characters can be used in object names:
ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_- and <space>
Object names can only 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:
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 |
This section introduces you to 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.
In order to maintain unique character set names and ids, you should 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 was 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).
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 8.0.3 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 version number is based on the Oracle 8.0.4 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
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:
Starting with Oracle release 8.0.4, there is a feature, 'BASE_CHAR_SET', that can make customized character set support easier. Since you are extending an existing Oracle character set, the easiest thing to do is to use '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 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 using your favorite 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" on page 9-5 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.
We recommend 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
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 you must also install these files on both 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 you 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 definition 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
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.
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 reinvoke it after installing the .nlb files.
At installation, all available NLS objects are stored and referenced in the system boot file. This file is used to load the available NLS dam.
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.
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:
When the NLS Configuration Utility is started you are presented with the following top-level menu:
The file menu contains choices pertaining to file operations. Options are:
Note: As long as the system boot file has not been opened and read, all these menu items will remain "grayed 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.
The Edit Menu contains choices for editing information that you enter in any of the dialogs and/or windows of the NLS Configuration Utility.
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. |
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. |
This menu provides functions which allow the user 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. |
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 is invoked directly from the command line:
LXEGEN
There are no parameters.
The Calendar Utility takes as input a text-format definition file. The name of the file and its location is hard-coded as a platform-dependent value. On UNIX platforms, the file name is lxecal.nlb, and its location is $ORACLE_HOME/ocommon/nls. An example calendar definition file is included in the distribution.
Note: The location of files is platform dependent. Please 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 would be lxecal.nlt were you to define deviation days for the Arabic Hijirah 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.
