Oracle8(TM) Server Utilities
Release 8.0

A54652-01

Library

Product

Contents

Index

Prev Next

9
National Language Support Utilities

This chapter describes three utilities:

For platform-specific details on the use of these utilities, please see your operating system-specific Oracle documentation.

NLS Data Installation Utility

Overview

When you order an Oracle distribution set, a default set of NLS objects is included. In future you may receive updates to the data in the form of text files, or you may create your own text-format object files. These 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  

This is the boot file which is included as part of the distribution set.  

System Boot File  

This is the boot file which is generated by the NLS Data Installation Utility and which loads the NLS objects. If the user already has an installed installation boot file, its contents can be merged with the new system boot file during object generation.  

User Boot File  

This boot file only contains a subset of the System boot file. For a description on how this file is generated, please refer to "NLS Configuration Utility" on page 9-8.  

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

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 value in the environment variable ORA_NLS (or the equivalent on your operating system will be used. If both are specified, the command line parameter will override the environment variable. If neither is specified, the NLS Data Installation Utility will exit with an error message.  

SYSDIR=pathname  

Specifies where to find the existing system boot file. If not specified, the directory specified in the ORANLS parameter will be used. If no existing system boot file can be found (possibly a first-time installation), the installation boot file which has just been created will be moved or copied to the new system boot file without any changes.  

DESTDIR=
pathname

 

Specifies where to put the new (merged) system boot file. If not specified, the directory specified in the ORANLS parameter will be used. Any system boot file already existing in this directory will be overwritten.  

HELP=[yes | no]  

If "yes", a help message describing the syntax is printed.  

Return Codes

You may receive the following return codes upon executing LXINST:

0  

Generation of binary boot and object files and merge of the installation and system boot files successfully completed.  

1  

Installation has failed, reason of the failure has been indicated by means of an error message.  

Note: The actual file names of the boot and object files are strictly imposed by Oracle Server release 7.2. Thus you can only specify the directory path name(s) where boot and object files are read from and written to.

Usage

The first step is to create or obtain your new text-format data object files. The distribution includes several example data files that you can use for reference. The next step is to create a text-format system boot file containing references to your new data objects; only those objects referenced in the boot file will be generated. An example system boot file is also included in the distribution. The names to be used for the text-format files are listed in the next section.

Once you have your new text-format files, call LXINST to generate the new binary_ object files. This will generate, in addition to the data object files, both an installation boot file and a system boot file. If you already have an NLS installation, you can set SYSDIR to point to the directory that contains your current data files, and the entries in the system Boot File there will merged into the new system boot file that is generated.

The binary object files will be generated in the directory specified by DESTDIR. If this is not your normal data directory, you must then move the new binary files into that directory. Be careful if DESTDIR is set to your normal data directory, as the current system boot file will be overwritten.

NLS Data Object Files

Read this section if you will be creating your own NLS data objects. It details the formats, contents, and restrictions expected by the NLS Data Installation Utility.

Text-Format Files

NLS data object files are specified in a system-independent, portable text format. In order to accommodate ASCII to EBCDIC conversions, only the following characters are allowed in the data file:

!"#$%&()*+,-./0123456789:;<=>?@
ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_'
abcdefghiklmnopqrstuvwxyz {|}~
<space> character

All other characters, including 8-bit ASCII single-byte characters, multi-byte characters, and control/shift characters, must be specified as octal or hexadecimal escape sequences as defined in the ANSI C standard 6000 for octal numbers, \xhh for hexadecimal numbers). The backslash (\) and double quote (") may be escaped by \\ and \" respectively where necessary.

Some of the data in the object files will be tagged with a specific character set (for example, day/month names); this data should not be subject to ASCII/EBCDIC conversions when transported across hardware platforms (otherwise, a string such as "abc\123" will have its first three characters converted to EBCDIC but the last character will remain as "\123"). In order to ensure this, all of the characters in such strings should be specified in octal format when it is known that a data object file will be moved between platforms. If the file will be generated for only one specific platform, then this restriction is not necessary.

Note that the NLS Data Installation Utility does not convert any characters into octal or hexadecimal format. It is assumed that any characters outside of those listed above will already be in octal or hexadecimal format, and that any backslashes and double quotes are already properly escaped.

It is assumed that the character set used for the data object files will be US7ASCII for ASCII platforms or WE8EBCDIC500 for EBCDIC platforms. This is allowed because NLS data must always include US7ASCII or WE8EBCDIC500.

Object Types

The following object types are currently supported:

Type   Name  

0  

Language  

1  

Territory  

2  

Character Set  

3  

Linguistic definition  

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 9000-9999.

Warning: Character set IDs are an exception. When you want to create a new character set, you must report its ID to the Oracle National Language Support Group at Oracle Corporation in order to ensure that the ID is unique; otherwise, its functioning cannot be guaranteed.

Object Names

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

Data Object File Names

The system-independent object file name is constructed from the generic boot file entry information:

pptdddd

where

pp  

NW for the system-independent text files or LX for the system-dependent binary files (files to be loaded by LX)  

t  

1 digit object type (hex)  

dddd  

4 digit object ID (hex)  

The installation boot file name is pp0BOOT; the system boot file name is pp1BOOT; user boot files are named pp2BOOT, where pp is as stated above. The file extension for all files is D.

Examples:

Filename   Description  

NW00001.D  

Text-format language definition, ID = 1  

NW203C2.D  

Text-format character set definition, ID = 962  

NW1BOOT.D  

Text-format system boot file  

1x00001.D  

Binary language definition, ID = 1  

1x30032.D  

Binary linguistic definition, ID = 50  

1x2BOOT.D  

Binary user boot file  

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

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 system boot file. If not specified, the value in the environment variable ORA_NLS (or the equivalent on your operating system) will be used. If both are specified, the command name parameter will override the environment variable. If neither is specified, the NLS Configuration Utility will exit with an error message.  

SYSDIR= pathname  

Specifies where to find an existing user boot file. If not specified, the directory specified in the ORANLS parameter will be used.  

DESTDIR= pathname  

Specifies where to put the new user boot file. If not specified, the directory specified in the ORANLS parameter will be used.  

HELP=[yes|no]  

If "yes", a help message describing the syntax is printed.  

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 9-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 "grayed 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 "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:

LANGUAGE  

AMERICAN  

TERRITORY  

AMERICA  

CHARACTER SET  

US7ASCII on an ASCII platform or WE8EBCDIC500 on an EBCDIC platform  

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 and/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 the user to retrieve various levels of help about the NLS Configuration Utility.

About  

Shows version information of the NLS Configuration Utility.  

Help System  

Not implemented in this release.  

NLS Calendar Utility

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.

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 is hard-coded as a platform-dependent value. On UNIX platforms, the file name is lxecal.dat, and its location is $ORACLE_HOME/ocommon/nls. An example calendar definition file is included in the distribution.

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 lxecalhl.o. 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 the next time an LX calendar function is called. Do not move or rename the file, as it is expected to be found in the same hard-coded name and location.




Prev

Next
Oracle
Copyright © 1997 Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index