Jump to content

UCONV.LIB

From EDM2

LIBCONV.LIB (also referred to as UCONV.LIB in documentation) is the import library for the OS/2 Unicode Conversion (UCONV) API, distributed with the IBM OS/2 Developer's Toolkit. It provides linker stubs for converting text between OS/2 codepages and Unicode (UCS-2/UTF-16LE), and between different codepages via Unicode as an intermediate representation.

File size in the OS/2 Warp 4.52 Toolkit 4.5: 2,048 bytes (2001-10-02). Source DLL: UCONV.DLL. Library filename on disk: libconv.lib.

UCONV is a companion to LIBULS.LIB: LIBULS provides locale-aware Unicode string operations, while UCONV provides the codepage conversion objects used to move text between the codepage world and the Unicode world. Together they form the complete OS/2 Unicode infrastructure.

Concepts

Term Meaning
UconvObject An opaque handle encapsulating a conversion table between one specific codepage and UCS-2. Created once and reused for multiple conversions.
UCS-2 The 16-bit fixed-width Unicode encoding used throughout OS/2 ULS. Each UniChar is one UCS-2 code unit (2 bytes). OS/2 Warp 4 uses UCS-2LE (little-endian).
Codepage An IBM/OS/2 character set identifier, e.g. 437 (US), 850 (Latin-1), 932 (Japanese DBCS), 1252 (Windows Latin-1), 1208 (UTF-8).
Non-identical conversion A character that exists in the source encoding but has no exact equivalent in the target. The conversion object's substitution policy determines the output: replace with a substitution character, skip, or return an error.
Streaming conversion UniUconvToUcs and UniUconvFromUcs update input/output buffer pointers in place. Calling them repeatedly on successive chunks processes arbitrarily large text without loading it all at once, and correctly handles multi-byte characters that span chunk boundaries.

API

UCONV.DLL exports 11 public functions (the two internal _UniMalloc / _UniFree symbols are private allocator helpers and not part of the public API).

Object lifecycle

UniCreateUconvObject(cpszCpName, puconvObj)
Creates a conversion object for the codepage named by cpszCpName (a UniChar string) and stores the handle in *puconvObj. Returns ULS_SUCCESS (0) on success. The codepage name follows IANA/IBM naming conventions:
Name Codepage Notes
L"IBM-437" CP437 US OEM (original IBM PC)
L"IBM-850" CP850 Latin-1 multilingual (most common Western OS/2)
L"IBM-852" CP852 Latin-2 Central European
L"IBM-862" CP862 Hebrew
L"IBM-864" CP864 Arabic
L"IBM-932" CP932 Japanese Shift-JIS (DBCS)
L"IBM-949" CP949 Korean (DBCS)
L"IBM-950" CP950 Traditional Chinese Big5 (DBCS)
L"IBM-1381" CP1381 Simplified Chinese (DBCS)
L"IBM-1252" CP1252 Windows Latin-1
L"IBM-1208" CP1208 UTF-8
L"IBM-1200" CP1200 UCS-2LE (identity conversion)
L"IBM-1201" CP1201 UCS-2BE (big-endian Unicode)

The name may also be passed as a multibyte string if the caller uses the appropriate flag variant; consult the Toolkit documentation for the exact parameter type of the implementation.

UniFreeUconvObject(uconvObj)
Releases all resources associated with a conversion object. After this call, uconvObj is invalid.

Conversion object properties

UniQueryUconvObject(uconvObj, pAttr, pSubChar, pSubUniChar, pDefChar, pDefUniChar)
Returns the current conversion attributes and substitution characters for uconvObj. pAttr points to a uconv_attribute_t structure:
Field Type Meaning
iVersion ULONG Structure version (must be 0)
discard_ilseq BYTE If TRUE, silently skip characters that cannot be mapped (no substitution, no error)
sub_char BYTE[4] Multibyte substitution character used when a UCS-2 character cannot be represented in the target codepage. Padded with nulls.
sub_char_len ULONG Length of sub_char in bytes (1 for SBCS, 2 for DBCS)
sub_uni_char UniChar UCS-2 substitution character used when a codepage byte sequence cannot be mapped to Unicode. Typically U+FFFD (REPLACEMENT CHARACTER).
endian BYTE Byte order for UTF-16/UCS-2 output: ENDIAN_SYSTEM (little-endian on OS/2 x86), ENDIAN_BIG, ENDIAN_LITTLE
srcfmt BYTE Source format hint for mixed-width encodings: CVTTYPE_PATH, CVTTYPE_CDRA, CVTTYPE_UNICODE
UniSetUconvObject(uconvObj, pAttr)
Applies a modified uconv_attribute_t structure to uconvObj. Use this to change the substitution character, discard policy, or endianness after creation. The iVersion field must be set to 0 before calling.

Codepage information

UniQueryUconvCp(uconvObj, pulCp)
Returns the OS/2 numeric codepage identifier (e.g. 850, 932) for the conversion object in *pulCp. Useful when the conversion object was created from a name string and the numeric CP is needed for legacy APIs.
UniMapCpToUcsCp(ulCp, puniCpName, ulBufLen)
Maps a numeric OS/2 codepage number ulCp to its IANA/IBM name string (e.g. 850 → L"IBM-850"), written into the UniChar buffer puniCpName of size ulBufLen characters. Used to bridge legacy codepage numbers to the UniCreateUconvObject name parameter.

Streaming conversion

These are the primary conversion functions. They update their buffer pointer arguments in place, making them suitable for streaming large files or network buffers without copying.

UniUconvToUcs(uconvObj, ppInBuf, pulInBytesLeft, ppOutBuf, pulOutCharsLeft, pulNonIdent)
Converts multibyte or single-byte codepage text to UCS-2. Parameters:
  • ppInBuf — pointer to a char* input pointer; advanced past consumed bytes on return
  • pulInBytesLeft — pointer to input byte count; decremented by bytes consumed
  • ppOutBuf — pointer to a UniChar* output pointer; advanced past written characters
  • pulOutCharsLeft — pointer to output buffer capacity in UniChar units; decremented by characters written
  • pulNonIdent — incremented by the count of characters that required substitution
Returns ULS_SUCCESS when all input was converted. Returns ULS_BUFFERFULL if the output buffer was exhausted before all input was consumed — refill the output buffer and resume by calling again with the updated pointers.
UniUconvFromUcs(uconvObj, ppInBuf, pulInCharsLeft, ppOutBuf, pulOutBytesLeft, pulNonIdent)
Converts UCS-2 Unicode text to the codepage encoding. Parameters are symmetric with UniUconvToUcs, with roles of bytes and characters swapped:
  • ppInBuf — pointer to a UniChar* input pointer
  • pulInCharsLeft — input character count (in UniChar units)
  • ppOutBuf — pointer to a char* output pointer
  • pulOutBytesLeft — output buffer capacity in bytes

Simple string conversion

Convenience wrappers for the common case of converting a complete null-terminated string without streaming.

UniStrToUcs(uconvObj, puniDst, pszSrc, iMaxChars)
Converts the null-terminated multibyte string pszSrc to a null-terminated UCS-2 string in puniDst. Writes at most iMaxChars UniChar units including the null terminator. Returns ULS_SUCCESS or an error code.
UniStrFromUcs(uconvObj, pszDst, puniSrc, iMaxBytes)
Converts the null-terminated UCS-2 string puniSrc to a null-terminated multibyte string in pszDst. Writes at most iMaxBytes bytes including the null terminator. Returns ULS_SUCCESS or an error code.

Error Codes

Constant Value Meaning
ULS_SUCCESS 0 Conversion completed successfully
ULS_BUFFERFULL 0x0001 Output buffer exhausted before input was fully converted; resume from updated pointers
ULS_ILLEGALSEQUENCE 0x0002 Input contained an invalid byte sequence for the source encoding
ULS_INVALID 0x0003 Invalid parameter (NULL pointer, bad handle)
ULS_NOMEMORY 0x0004 Memory allocation failed during object creation
ULS_NOTIMPLEMENTED 0x0005 Requested codepage is not installed
ULS_OTHER 0x0006 Unspecified error
ULS_NOTOKEN 0x0100 Locale token not found (from LIBULS shared error space)

Usage

IBM VisualAge C++ / ILINK

icc -O2 -Gm -c myapp.c
ilink /PM:PM myapp.obj os2386.lib libuls.lib libconv.lib

OpenWatcom (wlink)

wcl386 -bt=os2 -mf -c myapp.c
wlink system os2_pm file myapp.obj library os2386.lib library libuls.lib library libconv.lib

EMX/GCC

gcc -Zomf -c myapp.c
gcc -Zomf -o myapp.exe myapp.o os2386.lib libuls.lib libconv.lib

Include files

Header Contents
uni.h UniCreateUconvObject and all Uni* prototypes; UconvObject handle type; ULS_* error codes. (Shared with LIBULS.)
unidef.h uconv_attribute_t structure; ENDIAN_* and CVTTYPE_* constants.

Simple codepage → Unicode conversion

#include <uni.h>

/* Convert a CP850 string to UCS-2 */
UconvObject uobj;
UniCreateUconvObject(L"IBM-850", &uobj);

UniChar ucsStr[256];
UniStrToUcs(uobj, ucsStr, "Hello Wörld", 256);
/* ucsStr now contains UCS-2 encoding of the CP850 text */

UniFreeUconvObject(uobj);

Streaming conversion of a large buffer

#include <uni.h>
#include <string.h>

/* Convert a large CP932 (Japanese Shift-JIS) file buffer to UCS-2 */
UconvObject uobj;
UniCreateUconvObject(L"IBM-932", &uobj);

char   *pIn  = srcBuf;
ULONG   cbIn = srcLen;          /* bytes remaining in input */
UniChar outBuf[1024];
ULONG   cNonIdent = 0;

while (cbIn > 0) {
    UniChar *pOut  = outBuf;
    ULONG    cwOut = 1024;      /* UniChars available */

    ULONG rc = UniUconvToUcs(uobj, (PPVOID)&pIn, &cbIn,
                              &pOut, &cwOut, &cNonIdent);

    ULONG cwWritten = 1024 - cwOut;
    /* process cwWritten UniChars in outBuf here */

    if (rc != ULS_SUCCESS && rc != ULS_BUFFERFULL)
        break;  /* error */
}

UniFreeUconvObject(uobj);

Custom substitution character

#include <uni.h>
#include <unidef.h>

UconvObject uobj;
UniCreateUconvObject(L"IBM-850", &uobj);

/* Change the substitution character for unmappable UCS-2 → CP850 */
uconv_attribute_t attr;
memset(&attr, 0, sizeof(attr));
attr.iVersion    = 0;
attr.sub_char[0] = '?';   /* use '?' for unmappable characters */
attr.sub_char_len = 1;
UniSetUconvObject(uobj, &attr);

Codepage number → name → object

#include <uni.h>

/* Get the current OS/2 codepage number */
ULONG cp[2] = {0, 0};
DosQueryCp(sizeof(cp), cp, NULL);  /* from OS2386.LIB */

/* Map numeric CP to IANA name, then create a conversion object */
UniChar cpName[32];
UniMapCpToUcsCp(cp[0], cpName, 32);

UconvObject uobj;
UniCreateUconvObject(cpName, &uobj);

Relationship to Other APIs

API Library Role
UCONV (this library) LIBCONV.LIB / UCONV.DLL Codepage ↔ UCS-2 conversion objects
ULS LIBULS.LIB / LIBUNI.DLL Locale objects, Unicode string ops, character classification, formatting
NLS (legacy) OS2386.LIB DosQueryCp, DosMapCase, DosQueryDBCSEnv — codepage number queries and DBCS lead-byte tables
ICONV (third-party) — GNU iconv port for OS/2; broader encoding support including UTF-32, ISO-2022 variants; not part of the IBM Toolkit

Typical usage pattern

The common pattern for an OS/2 application handling user text is:

  1. Call DosQueryCp to learn the current process codepage.
  2. Call UniMapCpToUcsCp to get the codepage name.
  3. Call UniCreateUconvObject to create a conversion object.
  4. Call UniStrToUcs or UniUconvToUcs to bring text into Unicode for processing with LIBULS functions (UniStrcoll, UniStrftime, etc.).
  5. Call UniStrFromUcs or UniUconvFromUcs to convert the result back to the codepage for display or file output.
  6. Call UniFreeUconvObject at shutdown.

Version History

Version OS/2 release Date Notes
1.0 OS/2 Warp 4 1996 Initial release. All ten public functions present. SBCS and DBCS codepage conversion; UTF-8 support via CP1208.
1.x OS/2 Warp 4.52 Developer's Toolkit 4.5 2001 Final IBM release. Added UniMapCpToUcsCp for numeric CP → name bridging. File size: 2,048 bytes (2001-10-02). Library filename: libconv.lib. Source DLL: UCONV.DLL.

See Also

Retrieved from "https://www.edm2.com/index.php?title=UCONV.LIB&oldid=92145"