1.7 Unicode Table Concepts

We recommend using the new Unicode Converter API functions in for new development efforts. For more information see Section 1.6, Unicode Converter and Tasks.

1.7.1 Unicode Tables

At the workstation, conversions between Unicode and the local code page are supported by a set of conversion tables. The Unicode Filenames table shows the conventions for assigning file names to the tables.

Filename

Comment

UNI_<CP>.CTY

Unicode to code page conversion table

<CP>_UNI.CTY

Code page to Unicode conversion table

UNI_COL.CTY

Unicode collation table for country

UNI_MON.CTY

Unicode monocasing table for country

The filenames reflect both a code page (CP) and a country code (CTY). The code page can be 3 or 4 digits. The country code is the country’s 3-digit code for long distance telephone numbers. For example, to represent the English character set (CP=437) using U.S. conventions (CTY=001) the following files are required:

Section 1.4, Supported Code Pages shows the code pages supported by Novell.

1.7.2 Unicode Operations

Unicode operations fall into two groups: those specific to managing Unicode tables and conversions, and those that perform operations on Unicode strings. This latter group is the Unicode equivalent of standard string.h functions.

A client application must load Unicode tables for the client agent to perform the conversions. Loading the Unicode tables is typically one of the first steps an application takes in accessing Directory Services. Two functions load and unload the tables:

  • NWInitUnicodeTables
  • NWFreeUnicodeTables

As input, NWInitUnicodeTables requires a specific code page and country code. You can use Internationalization services to read these parameters from the locale. When you no longer need the tables, call NWFreeUnicodeTables.

For many applications, NWInitUnicodeTables and NWFreeUnicodeTables are the only Unicode functions needed. Other Unicode table requests include the following:

  • Return a handle to any of the Unicode table files
  • Load and unload one of the Unicode tables
  • Compare Unicode characters
  • Convert between Unicode and the local code page
  • Collate or monocase a Unicode buffer

For more details about specific functions, see the specific function reference.

1.7.3 Unicode Table Search Precedence

NWInitUnicodeTables searches for the tables in the following directories in the order they are listed.

  1. The current working directory.
  2. The directory the application was loaded from.
  3. A directory named \nls immediately subordinate to the directory the application was loaded from. (An nls directory is created by the NetWare installation process under sys:system.)
  4. A directory named \nls (which is a sibling of the directory from which the application was loaded).
  5. A directory in the local search path.

Note that the search path is the last place searched. Consequently, storing the tables in a search path could noticeably increase the amount of time it takes for the tables to load.

1.7.4 Unicode Table Functions

These functions manipulate Unicode tables.

Function

Header

Comment

NWInitUnicodeTables

unicode.h

Initializes Unicode tables.

NWLoadRuleTable

unicode.h

Loads the specified Unicode table.

NWFreeUnicodeTables

unicode.h

Frees Unicode tables after they have been initialized with NWInitUnicodeTables.

NWGetUnicodeToLocalHandle

unicode.h

Returns a handle to the current Unicode to Code Page conversion table.

NWGetLocalToUnicodeHandle

unicode.h

Returns a handle to the current Code Page to Unicode conversion table.

NWGetMonocaseHandle

unicode.h

Returns a handle to the current Unicode Monocasing table.

NWGetCollationHandle

unicode.h

Returns a handle to the current Unicode Collation table.

NWUnloadRuleTable

unicode.h

Deallocates memory for a rule table set up and allocated by NWLoadRuleTable.

1.7.5 Unicode Buffer and Character Functions

These functions perform conversion and comparison operations.

Function

Header

Comment

NWUnicodeCompare

unicode.h

Compares a pair of unicode characters.

NWLocalToUnicode

unicode.h

Converts data in the local code page to Unicode.

NWUnicodeToLocal

unicode.h

Converts Unicode data to the local code page.

NWUnicodeToCollation

unicode.h

Converts Unicode to collation.

NWUnicodeToMonocase

unicode.h

Converts Unicode to monocase.