Unicode Programming Reference

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

The Unicode Programming Reference documents the:

• Universal language support functions. See Universal Language Support Functions.
• Functions that convert between UCS and non-UCS encodings. See Conversion Functions.
• Universal language support keyboard functions. See Universal Language Support Keyboard Functions.
• Data types associated with the functions described in this book. See Data Types.

Universal Language Support Functions

You need internationalized applications to operate in a variety of environments based on some territory, language, and cultural definition. You identify these environments by a locale. A locale object encapsulates the following culturally-specific information:

• Culture
• Language
• Script
• Territory

Universal Language Support Functions

Conversion Functions

It is expected that most of the processing by applications using the ULS will be done using UniChar strings. Yet, many applications will need to export data to and import data from non-UCS encodings (for example, ASCII or EBCDIC). For this purpose, a set of functions are defined to perform conversions between UCS and non-UCS encodings. The Uconv name is used to indicate these functions. The Uconv functions are capable of doing only UCS conversions, such as converting to/from UCS.

In addition, the iconv functions defined by the X/Open Portability Guide, Issue 4 are provided for converting between any encodings, for example, between PC code and ISO codes. In addition, any of the UCS conversions may be invoked using the iconv functions by specifying UCS-2 as the to/from code set.

• UniCreateUconvObject - Creates and utilzes a Uconv object
• UniFreeUconvObject - Frees a conversion object
• UniMapCpToUcsCp - Converts a code page number represented as a UniChar string that is acceptable as input to the UniCreateUconvObject
• UniQueryUconvObject - Queries the attributes of a conversion object
• UniSetUconvObject - Sets the attributes of a conversion object
• UniUconvFromUcs - Converts UCS characters to code page characters
• UniUconvToUcs - Converts a code page string to a UCS string

Universal Language Support Keyboard Functions

When a user presses a key on the keyboard, the device driver maps to the appropriate scan code. To process the translation of the scan code to a Unicode character or virtual function key, a set of ULS keyboard functions are provided.

The keyboard functions maintain a state that includes information about:

• Shift state
• Lock state
• Virtual and dead key

The keyboard functions include:

1. Translation table manipulation functions:
   • UniCreateKeyboard - Load a keyboard layout
   • UniDestroyKeyboard - Unload a keyboard layout
   • UniQueryKeyboard - Query information from the header in the keyboard table layout
2. Translation and state maintenance functions:
   • UniResetShiftState - Reset the shift state and LED status
   • UniTranslateDeadKey - Translate a dead key code with a Unicode to a composite character
   • UniTranslateKey - Translate a scan code plus shift state to a Unicode and virtual or dead key
   • UniUntranslateKey - Translate a Unicode to a scan code plus shift state
   • UniUpdateShiftState - Maintain shift state and LED status

Data Types

The following data types are used by the Unicode functions.

• APIRET
• AttrObject
• BYTE
• CHAR
• conv_endian_t
• KBDNAME
• KEYBOARDINFO
• KHAND
• LocaleItem
• LocaleObject
• LocaleToken
• LONG
• SHORT
• size_t
• tm
• UCHAR
• uconv_attribute_t
• UconvObject
• udcrange_t
• ULONG
• ulsBool
• UniChar
• UniLconv
• USHIFTSTATE
• USHORT
• VDKEY
• VOID
• VSCAN
• XformObject

Error Codes

Unicode Errors

Notices

August 1996

The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.

It is possible that this publication may contain reference to, or information about, IBM products machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.

Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing representative.

Copyright Notices

COPYRIGHT LICENSE: This publication contains printed sample application programs in source language, which illustrate OS/2 programming techniques. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the OS/2 application programming interface.

Each copy of any portion of these sample programs or any derivative work, which is distributed to others, must include a copyright notice as follows: "(C) (your company name) (year). All rights reserved."

(c) Copyright International Business Machines Corp. 1996. All Rights Reserved. Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Disclaimers

References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, are the responsibility of the user.

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation

500 Columbus Avenue

Thornwood, NY 10594

U.S.A.

Asia-Pacific users can inquire, in writing, to the IBM Director of Intellectual Property and Licensing, IBM World Trade Asia Corporation, 2-31 Roppongi 3-chome, Minato-ku, Tokyo 106, Japan.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact IBM Corporation, Department LZKS, 11400 Burnet Road, Austin, TX 78758 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

Trademarks

The following terms are trademarks of the IBM Corporation in the United States or other countries or both:

• AIX
• AS/400
• AT
• Common User Access
• CUA
• FFST
• First Failure Support Technology
• GDDM
• IBM
• IMS
• Operating System/2
• OS/2
• Personal System/2
• PowerPC
• Presentation Manager
• Proprinter
• PS/2
• Quietwriter
• RETAIN
• RT
• SAA
• Systems Application Architecture
• WIN-OS/2
• Workplace Shell
• XGA
• XT

The following terms are trademarks of other companies:

• C++ (American Telephone and Telegraph Company)
• HP (Hewlett-Packard Company)
• Intel (Intel Corporation)
• LaserJet (Hewlett-Packard Company)
• Microsoft (Microsoft Corporation)
• PCMCIA (Personal Computer Memory Card International Association)
• PostScript (Adobe Systems Incorporated)
• Times New Roman (Monotype Corporation, Limited)
• Windows (Microsoft Corporation)

Links

• HTM - Second Edition (October 1997)