LIBULS.LIB

LIBULS.LIB is the import library for the OS/2 Unicode Locale Services (ULS), distributed with the IBM OS/2 Developer's Toolkit. It provides the linker stubs for a comprehensive Unicode-aware API covering locale objects, character classification, string manipulation, collation, case conversion, date/time/number formatting, and string transforms. The ULS is IBM's system-level Unicode infrastructure for OS/2 national language support.

File size in the OS/2 Warp 4.52 Toolkit 4.5: 7,680 bytes (2001-10-02). Source DLL: LIBUNI.DLL.

Overview

The ULS API models Unicode locale handling through three central object types:

Type	Handle	Role
Locale object	`LocaleObject`	Encapsulates all locale-specific rules: collation, number format, date/time format, currency, text separators. Analogous to POSIX `locale_t`.
Attr object	`AttrObject`	A compiled character attribute table for fast per-character classification queries. Created from a locale object.
Transform object	`TransformObject`	A compiled rule set for string transformation (case folding, normalization, transliteration).

The fundamental character type throughout the ULS API is UniChar (a 16-bit unsigned value, UTF-16LE code unit), and most string functions operate on null-terminated arrays of UniChar.

API Summary

LIBULS.LIB exports 93 symbols grouped into eight functional areas:

Group	Functions	Description
Locale objects	7	Create, free, query locale handles
Locale information	9	Query locale items, values, lists, country/language names
User locale	7	Create, modify, save user-customized locales
Attr objects	4	Compile attribute tables, scan for character attributes
Character classification	14	Unicode equivalents of `<ctype.h>` predicates
Unicode strings	24	Locale-aware equivalents of C runtime string functions
Formatting	3	Date/time, monetary, and numeric string formatting
Transform objects	8	Case conversion, string transforms, collation keys

Locale Objects

UniCreateLocaleObject(ulLocType, cpszLocale, pLocaleObj)

Creates a locale object from the locale specification cpszLocale. ulLocType selects the format:

UNI_MBS_STRING_POINTER — locale name as a multibyte string (e.g. "en_US", "ja_JP")
UNI_UCS_STRING_POINTER — locale name as a UniChar string
UNI_TOKEN_POINTER — locale as a locale token

Returns ULS_SUCCESS and stores the handle in *pLocaleObj.

UniFreeLocaleObject(localeObj): Releases all memory associated with a locale object.

UniQueryLocaleObject(localeObj, ulCategory, ulType, ppvInfo): Returns a pointer to a specific information block within the locale object. ulCategory selects LC_CTYPE, LC_COLLATE, LC_TIME, LC_NUMERIC, LC_MONETARY, or LC_MESSAGES. ulType refines the requested data.

UniLocaleStrToToken(ulType, cpszLocale, pLocToken): Converts a locale name string to a compact locale token.

UniLocaleTokenToStr(locToken, ulType, ppszLocale): Converts a locale token back to a locale name string.

UniQueryLocaleList(ulFlags, puniStr, ulBufLen): Enumerates available locale names into a buffer. ulFlags controls whether system locales, user-defined locales, or both are included.

UniMapCtryToLocale(usCtry, usCP, puniLocale, ulBufLen): Maps an OS/2 country code and codepage pair to a ULS locale name string. Used to bridge the older OS/2 NLS country-code model to ULS locale objects.

Locale Information

UniQueryLocaleInfo(localeObj, ppLocaleInfo): Returns a LOCALEINFOITEMS structure with pointers to the locale's format strings, separators, and symbols: decimal separator, thousands separator, currency symbol, date/time format strings, AM/PM strings, day and month names, collation name, etc.

UniFreeLocaleInfo(pLocaleInfo): Releases a LOCALEINFOITEMS structure returned by UniQueryLocaleInfo.

UniQueryLocaleItem(localeObj, ulItem, ppuniStr)

Retrieves a single locale string item by item ID. Item IDs are LOCI_* constants:

LOCI_sDecimal — decimal separator character
LOCI_sThousand — thousands grouping separator
LOCI_sCurrency — currency symbol
LOCI_sDate — date separator
LOCI_sTime — time separator
LOCI_sAM / LOCI_sPM — AM/PM strings
LOCI_sShortDate — short date format pattern
LOCI_sLongDate — long date format pattern
LOCI_s1159 — morning designator
LOCI_s2359 — evening designator
LOCI_sLanguage — language abbreviation
LOCI_sCountry — country abbreviation

UniQueryLocaleValue(localeObj, ulItem, pulValue)

Retrieves a single numeric locale value by item ID. Numeric items include:

LOCI_iDate — date format order (0=MDY, 1=DMY, 2=YMD)
LOCI_iTime — time format (0=12h, 1=24h)
LOCI_iCurrency — currency position (0=prefix, 1=suffix, 2=prefix with space, 3=suffix with space)
LOCI_iDigits — decimal digits after decimal point
LOCI_iNegNumber — negative number format style

UniQueryCountryName(localeObj, ulType, ppuniStr): Returns the country name in the locale's language.

UniQueryLanguageName(localeObj, ulType, ppuniStr): Returns the language name in the locale's language.

UniQueryNumericValue(localeObj, ulItem, pdblValue): Returns a locale numeric attribute as a double.

User Locale

OS/2 users can customize locale settings. The user locale functions create and manage these customizations.

UniMakeUserLocale(cpszLocaleName, cpszBaseName, pUserLocObj): Creates a user locale object named cpszLocaleName based on existing locale cpszBaseName. Returns the new locale object handle.

UniCreateUserLocale(cpszLocaleName, pUserLocObj): Creates a new empty user locale.

UniDeleteUserLocale(cpszLocaleName): Permanently deletes a user-defined locale from the system.

UniCompleteUserLocale(userLocObj): Finalizes a user locale after all item modifications have been made, building the internal data tables.

UniSetUserLocaleItem(userLocObj, ulItem, ulType, pValue): Sets one item in a user locale object (a string or numeric value by LOCI_* item ID).

UniGetOverride(localeObj, ulItem, ppuniStr): Returns the user-defined override value for a locale item, or NULL if the item uses the system default.

Attr Objects

Attr objects are pre-compiled character attribute tables that allow fast classification of individual Unicode characters without consulting the full locale object on each call.

UniCreateAttrObject(localeObj, puniAttrName, pAttrObj): Compiles a character attribute table from the locale object for attribute class puniAttrName (e.g. L"upper", L"lower", L"alpha", L"digit"). Returns an AttrObject handle.

UniFreeAttrObject(attrObj): Frees an attr object.

UniQueryAttr(attrObj, uc): Returns TRUE if Unicode character uc has the attribute encoded in attrObj. Faster than calling UniQueryAlpha etc. for repeated queries in a loop.

UniScanForAttr(attrObj, puniStr, ulLen, fNotAttr, pulOffset): Scans puniStr (up to ulLen characters) looking for the first character that has (or does not have, if fNotAttr is TRUE) the attribute in attrObj. Returns the offset in *pulOffset.

Character Classification

These functions test a single UniChar against a locale's classification rules. They are locale-aware equivalents of the C standard <ctype.h> predicates.

ULS function	C runtime equivalent	True when
`UniQueryAlpha(locObj, uc)`	`isalpha(c)`	Letter (any script)
`UniQueryDigit(locObj, uc)`	`isdigit(c)`	Decimal digit
`UniQueryAlnum(locObj, uc)`	`isalnum(c)`	Letter or decimal digit
`UniQueryLower(locObj, uc)`	`islower(c)`	Lowercase letter
`UniQueryUpper(locObj, uc)`	`isupper(c)`	Uppercase letter
`UniQueryPunct(locObj, uc)`	`ispunct(c)`	Punctuation character
`UniQuerySpace(locObj, uc)`	`isspace(c)`	Whitespace (space, tab, newline, etc.)
`UniQueryBlank(locObj, uc)`	`isblank(c)`	Space or horizontal tab only
`UniQueryCntrl(locObj, uc)`	`iscntrl(c)`	Control character (C0/C1)
`UniQueryPrint(locObj, uc)`	`isprint(c)`	Printable (including space)
`UniQueryGraph(locObj, uc)`	`isgraph(c)`	Printable and visible (excluding space)
`UniQueryXdigit(locObj, uc)`	`isxdigit(c)`	Hexadecimal digit [0–9 A–F a–f]

Additional character attribute queries:

UniQueryChar(locObj, uc, ulAttr): General character attribute test. ulAttr is a CT_* attribute constant (e.g. CT_UPPER, CT_LOWER, CT_DIGIT, CT_SPACE, CT_PUNCT, CT_CNTRL, CT_BLANK, CT_XDIGIT, CT_ALPHA).

UniQueryCharAttr(locObj, uc, pulAttr): Returns the complete character attribute bitmask for uc in *pulAttr. The bitmask is a combination of CT_* flags.

UniQueryCharType(locObj, uc, pulType): Returns the Unicode general category of uc (e.g. uppercase letter, lowercase letter, decimal digit, currency symbol, etc.) as a UCT_* value.

UniQueryCharTypeTable(locObj, ppTable, pulSize): Returns a pointer to the locale's internal character type table. Used for bulk classification without per-character function call overhead.

UniQueryStringType(locObj, puniStr, ulLen, pulTypes): Classifies each character in puniStr and fills pulTypes[] with the corresponding CT_* bitmasks. More efficient than calling UniQueryCharAttr in a loop.

Unicode String Operations

The UniStr* functions are locale-aware Unicode equivalents of the C runtime string library. They operate on null-terminated UniChar (UTF-16LE) strings.

Copying and concatenation

UniStrcpy(puniDst, puniSrc): Copies null-terminated Unicode string puniSrc to puniDst. Returns puniDst.

UniStrncpy(puniDst, puniSrc, n): Copies at most n characters.

UniStrcat(puniDst, puniSrc): Appends puniSrc to puniDst.

UniStrncat(puniDst, puniSrc, n): Appends at most n characters.

Length and search

UniStrlen(puniStr): Returns the number of UniChar units in the string (not bytes), excluding the null terminator.

UniStrchr(puniStr, uc): Returns a pointer to the first occurrence of UniChar uc in puniStr, or NULL.

UniStrrchr(puniStr, uc): Returns a pointer to the last occurrence.

UniStrstr(puniStr, puniSub): Returns a pointer to the first occurrence of substring puniSub in puniStr.

UniStrcspn(puniStr, puniReject): Returns the length of the initial segment of puniStr that contains no characters from puniReject.

UniStrspn(puniStr, puniAccept): Returns the length of the initial segment containing only characters from puniAccept.

UniStrpbrk(puniStr, puniAccept): Returns a pointer to the first character in puniStr that also appears in puniAccept.

UniStrtok(puniStr, puniDelim): Tokenizes a string — locale-aware equivalent of strtok. Pass NULL for puniStr on subsequent calls.

Comparison and collation

UniStrcmp(puniStr1, puniStr2): Code-point comparison (binary). Returns negative, zero, or positive.

UniStrncmp(puniStr1, puniStr2, n): Code-point comparison of at most n characters.

UniStrcmpi(locObj, puniStr1, puniStr2): Case-insensitive code-point comparison.

UniStrncmpi(locObj, puniStr1, puniStr2, n): Case-insensitive comparison of at most n characters.

UniStrcoll(locObj, puniStr1, puniStr2): Locale-aware collation comparison. Uses the locale's sort rules (handles accents, locale-specific ordering like Spanish "ll" as a digraph). Equivalent to POSIX strcoll.

UniStrxfrm(locObj, puniDst, puniSrc, n): Transforms puniSrc into a sort key string such that a simple UniStrcmp on two transformed strings gives the same result as UniStrcoll on the originals. Equivalent to POSIX strxfrm. Use when comparing the same string against many others.

Case conversion

UniStrlwr(locObj, puniStr): Converts puniStr to lowercase in-place using locale rules. Returns puniStr.

UniStrupr(locObj, puniStr): Converts puniStr to uppercase in-place.

Numeric parsing

UniStrtod(locObj, puniStr, ppuniEnd): Parses a floating-point number from puniStr using the locale's decimal separator. Returns a double. Sets *ppuniEnd to the first character not consumed.

UniStrtol(locObj, puniStr, ppuniEnd, iBase): Parses a signed long integer from puniStr.

UniStrtoul(locObj, puniStr, ppuniEnd, iBase): Parses an unsigned long integer.

String Formatting

UniStrftime(locObj, puniDst, n, puniFormat, ptm): Formats a struct tm date/time into puniDst (a UniChar buffer of at most n characters) using the format string puniFormat. Format codes are the same as ANSI strftime (%Y, %m, %d, %H, %M, %S, %A, %B, etc.) but the output uses locale-specific day names, month names, AM/PM strings, and date/time separators.

UniStrptime(locObj, puniStr, puniFormat, ptm): Parses a date/time string according to the locale's format and fills a struct tm. Locale-aware inverse of UniStrftime.

UniStrfmon(locObj, puniDst, n, puniFormat, ...): Formats monetary values into puniDst using the locale's currency symbol, decimal separator, and grouping rules. Locale-aware equivalent of POSIX strfmon. Format codes include %n (national format) and %i (international format).

Transform Objects and Case Conversion

UniCreateTransformObject(locObj, puniTransName, pTransObj): Compiles a named transformation rule set from the locale. puniTransName identifies the transform (e.g. L"upper", L"lower", L"fold" for case folding, L"compose" for canonical composition). Returns a TransformObject handle.

UniFreeTransformObject(transObj): Frees a transform object.

UniTransformStr(transObj, puniSrc, pulSrcLen, puniDst, pulDstLen): Applies the transformation in transObj to puniSrc (up to *pulSrcLen characters) and writes the result to puniDst. Updates *pulSrcLen and *pulDstLen to the number of characters consumed and produced.

UniTolower(locObj, uc): Converts a single UniChar to lowercase. Returns the lowercase equivalent, or uc unchanged if it has no lowercase form.

UniToupper(locObj, uc): Converts a single UniChar to uppercase.

UniTransLower(locObj, puniStr): Converts an entire UniChar string to lowercase in-place using locale case rules.

UniTransUpper(locObj, puniStr): Converts an entire UniChar string to uppercase in-place.

Collation keys

UniMakeKey(locObj, puniStr, pKey, ulKeyBufLen): Computes a locale-aware sort key for puniStr and stores it in pKey. Sort keys are opaque byte sequences that can be compared with memcmp to give locale-correct ordering, equivalent to the output of UniStrxfrm.

UniGetColval(locObj, uc, pulColval): Returns the primary collation weight for a single character.

Codepage conversion

UniProcessUconv(uconvObj, ppInBuf, pulInLen, ppOutBuf, pulOutLen, pulNonIdent): Applies a codepage conversion object to transform a buffer. The conversion object is created separately via the UCONV API (UCONV.DLL). This function connects the ULS string model to the codepage conversion layer.

Usage

IBM VisualAge C++ / ILINK

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

OpenWatcom (wlink)

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

EMX/GCC

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

Include files

Header	Contents
`uni.h`	Main ULS header: all `Uni` prototypes; `UniChar` type; `LocaleObject`, `AttrObject`, `TransformObject` handle types; `UNI_` locale type constants; `ULS_SUCCESS` and `ULS_*` error codes.
`unidef.h`	ULS type definitions: `CT_` character type flags, `UCT_` Unicode category constants, `LOCI_*` locale item IDs.
`ulsitem.h`	`LOCALEINFOITEMS` structure definition and field names.

Locale-aware string comparison example

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

/* Create German locale */
LocaleObject loc;
UniCreateLocaleObject(UNI_MBS_STRING_POINTER, "de_DE", &loc);

/* Locale-correct sort (handles ä, ö, ü, ß) */
UniChar s1[] = {0x00E4, 0x0000};  /* ä */
UniChar s2[] = {0x0061, 0x0000};  /* a */
int cmp = UniStrcoll(loc, s1, s2);
/* cmp > 0: ä sorts after a in German */

/* Case conversion */
UniChar buf[] = {0x00C4, 0x0000};  /* Ä */
UniTransLower(loc, buf);           /* → ä */

UniFreeLocaleObject(loc);

Date formatting example

#include <uni.h>
#include <time.h>

LocaleObject loc;
UniCreateLocaleObject(UNI_MBS_STRING_POINTER, "fr_FR", &loc);

time_t now = time(NULL);
struct tm *ptm = localtime(&now);

UniChar dateBuf[64];
UniStrftime(loc, dateBuf, 64, L"%A %d %B %Y", ptm);
/* e.g.: "mercredi 15 janvier 2003" in French */

UniFreeLocaleObject(loc);

Relationship to Other OS/2 APIs

API	Library	Role
ULS (this library)	LIBULS.LIB / LIBUNI.DLL	Locale objects, Unicode string ops, classification, formatting
UCONV	UCONV.LIB / UCONV.DLL	Codepage ↔ Unicode conversion objects (`UniCreateUconvObject`)
NLS (legacy)	OS2386.LIB (COUNTRY.SYS)	Country-code/codepage based NLS: `DosQueryCtryInfo`, `DosMapCase`, `DosQueryDBCSEnv`
LIBUNI (internal)	—	LIBUNI.DLL also contains additional internal Unicode tables used by the system

For new OS/2 Unicode-aware applications, LIBULS.LIB (combined with UCONV.LIB for codepage conversion) is the preferred API over the older country-code NLS functions.

Version History

Version	OS/2 release	Date	Notes
1.0	OS/2 Warp 4	1996	Initial release of ULS with OS/2 Warp 4. Core locale object, character classification, `UniStr*` functions, `UniStrftime`.
1.1	OS/2 Warp 4.x	1997–1999	Added transform objects, `UniStrfmon`, `UniStrptime`, user locale management, attr object scan, collation key generation.
1.2	OS/2 Warp 4.52 Developer's Toolkit 4.5	2001	Final IBM release. Added `UniQueryNumericValue`, `UniQueryCharTypeTable`, `UniQueryStringType`. File size: 7,680 bytes (2001-10-02). Source DLL: LIBUNI.DLL.