Jump to content

PMBIDI.LIB

From EDM2

PMBIDI.LIB is the import library for the OS/2 Presentation Manager Bidirectional (BiDi) text subsystem, distributed with the IBM OS/2 Developer's Toolkit. It provides the linker stubs for APIs that add right-to-left (RTL) script support — primarily Arabic and Hebrew — to OS/2 Presentation Manager applications.

File size in the OS/2 Warp 4.52 Toolkit 4.5: 5,632 bytes (2000-10-16). Source DLL: PMBIDI.DLL. All functions are exported by ordinal.

Concepts

Term Meaning
BiDi Bidirectional text: text that mixes left-to-right (LTR) scripts (Latin, digits) with right-to-left (RTL) scripts (Arabic, Hebrew). OS/2 BiDi support predates the Unicode Bidirectional Algorithm (UBA); it uses its own codepage-based approach.
Logical order Text stored in the order it was typed (keyboard input order). For Hebrew/Arabic this is right-to-left in meaning but may be stored LTR in memory, depending on the codepage convention.
Visual order Text reordered so that the first character in the string is the leftmost character on screen. Required for display and printing on non-BiDi-aware output devices.
Text shaping Arabic letters have up to four contextual forms (isolated, initial, medial, final) depending on their neighbors. Shaping selects the correct glyph form before display.
Numerals conversion Conversion between Western (European) digits (0–9) and Arabic-Indic digits (٠–٩). Both sets are valid in Arabic text; OS/2 BiDi allows apps to control which is displayed.
Keyboard layer The current keyboard mapping for an RTL window — Latin or native script. Toggled by the user; applications query and set this to synchronize their UI state.
Layout context The embedding direction and nesting depth of a BiDi segment within a paragraph. The ISO Layout Services API manages this explicitly via layout objects.
BiDi attribute A ULONG bitmask encoding the directionality properties (base direction, shaping, numerals type, symmetric swapping) for a GPI presentation space or text run.

API Families

PMBIDI.LIB exports 74 symbols across seven API families:

Prefix 32-bit form 16-bit form Role
Gpi !! Gpi32* !! GPI16* !! GPI presentation space BiDi attribute get/set
Nls !! Nls32* !! NLS16* !! NLS string conversion, shaping, numeral conversion
Bidi !! Bidi_* !! BIDI_16* !! Core BiDi string operations and layout
PMBIDI !! PMBIDI_* !! PMBIDI_16* !! PM-level initialization and utility functions
Win !! Win32* !! WIN16* !! Window/process language and keyboard layer
layout_object !! layout_object_* !! (none) !! ISO/IEC layout services (POSIX portable BiDi API)

The 32-bit forms use the _System calling convention. The 16-bit forms (NLS16*, GPI16*, WIN16*, BIDI_16*) are provided for 16-bit segments and are equivalent in behavior.

GPI BiDi Attributes

BiDi attributes on a GPI presentation space control how GpiCharString and related calls render Arabic or Hebrew text.

Gpi32SetBidiAttr(hps, ulBidiAttr) / GPI16SETBIDIATTR
Sets the BiDi attribute bitmask for presentation space hps. Attribute bits include:
  • BIDI_ATTR_RTLREADING — render text right-to-left
  • BIDI_ATTR_ARABIC / BIDI_ATTR_HEBREW — script-specific shaping enable
  • BIDI_ATTR_NUMERALS_NATIONAL — use Arabic-Indic digit forms
  • BIDI_ATTR_SYMMETRICSWAP — mirror bracket and punctuation characters in RTL mode
Gpi32QueryBidiAttr(hps, pulBidiAttr) / GPI16QUERYBIDIATTR
Returns the current BiDi attribute bitmask for presentation space hps into *pulBidiAttr.

NLS String Operations

The Nls32* / NLS16* family operates on strings in OS/2 DBCS/SBCS codepages (CP862 Hebrew, CP864 Arabic, CP1255, CP1256).

Nls32ConvertBidiString(pSrc, pDst, ulLen, ulFlags) / NLS16CONVERTBIDISTRING
Converts a string between logical and visual order. ulFlags specifies the conversion direction (BIDI_LOG2VIS or BIDI_VIS2LOG) and the codepage.
Nls32EditShape(pSrc, pDst, ulLen, ulFlags) / NLS16EDITSHAPE
Applies Arabic letter shaping to a string in logical order. Each Arabic character is replaced by its contextually correct glyph form (isolated, initial, medial, or final). Used when rendering Arabic on GPI without automatic shaping.
Nls32InverseString(pSrc, pDst, ulLen) / NLS16INVERSESTRING
Reverses the string pSrc into pDst. A simple byte-by-byte reversal; for visual-to-logical round-tripping use Nls32ConvertBidiString instead.
Nls32ShapeBidiString(pSrc, pDst, ulLen, ulFlags) / NLS16SHAPEBIDISTRING
Performs combined logical-to-visual reordering and Arabic shaping in a single call. Equivalent to calling Nls32ConvertBidiString followed by Nls32EditShape.
Nls32ConvertBidiNumerics(pSrc, pDst, ulLen, ulFlags) / NLS16CONVERTBIDINUMERICS
Converts numeral characters in the string between Western (0–9) and Arabic-Indic (٠–٩) forms. ulFlags selects the conversion direction and codepage.

Core Bidi Operations

Bidi_QueryCp() / BIDI_16QUERYCP
Returns the active BiDi codepage as a ULONG codepage identifier (e.g. 862 for Hebrew, 864 for Arabic). Returns 0 if no BiDi codepage is active.
Bidi_ClassifyCodepage(ulCp)
Returns a classification code indicating whether codepage ulCp is a BiDi codepage, and if so, which script (Arabic or Hebrew). Applications use this to decide whether to call the BiDi APIs at all.
Bidi_IsStringBidi(pStr, ulLen, ulCp)
Returns TRUE if the string contains any characters from the BiDi codepage (i.e., any RTL characters). Useful as a fast pre-check before a full conversion.
Bidi_IsStringAllBidi(pStr, ulLen, ulCp)
Returns TRUE if the string consists entirely of BiDi (RTL script) characters with no LTR mixing. A pure-RTL string can be reversed as a whole without per-character analysis.
Bidi_LayoutConvert(pSrc, pDst, ulSrcLen, pulDstLen, ulFlags)
Converts between logical and visual layout orders, returning the result in pDst. More general than Nls32ConvertBidiString: handles mixed scripts, symmetric swapping of brackets, and can process runs longer than a single line.
Bidi_LayoutEdit(pStr, ulLen, ulPos, ulChar, ulOp, ulFlags)
Performs an edit operation (insert or delete a character) inside a BiDi string while maintaining correct logical order. Returns the new string length.
Bidi_MapSrcToTrg(pSrcMap, pTrgMap, ulLen)
After a BiDi conversion, maps a character position in the source string to its corresponding position in the converted string. Used by text editors to maintain cursor position after layout reordering.
Bidi_ReverseString(pStr, ulLen)
Reverses the string in place. Lower-level than Nls32InverseString; operates on raw bytes.

PMBIDI Utilities

PMBIDI_Initialize()
Initializes the PM BiDi subsystem for the calling process. Should be called once before any other PMBIDI function if the application requires PM-level BiDi integration (status window, dialog language). Applications that use only the lower-level Nls32/Bidi_ functions do not need to call this.
PMBIDI_Get_StdDlgLang_Setting() / PMBIDI_16GET_STDDLGLANG_SETTING
Returns the standard dialog language setting for the current session: a ULONG indicating whether PM dialogs should be presented in a left-to-right or right-to-left layout. Applications use this to decide whether to mirror their dialog layout on RTL systems.
PMBIDI_CpTranslateString(pSrc, pDst, ulSrcLen, pulDstLen, ulSrcCp, ulDstCp, ulFlags) / PMBIDI_16CP_TRANSLATE_STRING
Translates a string between two BiDi codepages (e.g. CP862 to CP1255 for Hebrew, or CP864 to CP1256 for Arabic) with proper BiDi attribute preservation. Unlike DosMapCase, this function is BiDi-aware and preserves logical ordering.
PMBIDI_BinVal_To_String(ulBidiAttr, pszBuffer, ulBufLen)
Converts a BiDi attribute bitmask to a human-readable string representation. Used for debugging and logging.
PMBIDI_String_To_BinVal(pszAttrStr, pulBidiAttr)
Parses a string representation of a BiDi attribute back into a ULONG bitmask. Inverse of PMBIDI_BinVal_To_String.
PMBIDI_Keyword_To_BinVal(pszKeyword, pulBidiAttr)
Converts a single keyword token (e.g. "RTLREADING", "ARABIC", "NUMERALS_NATIONAL") into the corresponding BiDi attribute bit, which the caller can OR into a bitmask.

Window and Process Language Settings

These functions manage the language direction state of PM windows, threads, and the whole process.

Keyboard layer

Win32QueryKbdLayer(hab, hwnd) / WIN16QUERYKBDLAYER
Returns the current keyboard layer for hwnd: BIDI_KBD_LATIN or BIDI_KBD_NATIVE (Arabic/Hebrew). The keyboard layer determines which character set the keyboard produces.
Win32SetKbdLayer(hab, hwnd, ulLayer) / WIN16SETKBDLAYER
Sets the keyboard layer for hwnd programmatically. Applications call this when the user clicks a language toggle button rather than pressing the OS toggle key.

Language info

Win32QueryLangInfo(hab, hwnd, pLangInfo) / WIN16QUERYLANGINFO
Returns the language information record (LANGINFO) for hwnd: the active language ID, keyboard layer, text direction, and text type (visual/logical). This is the primary per-window BiDi state query.
Win32SetLangInfo(hab, hwnd, pLangInfo) / WIN16SETLANGINFO
Sets the LANGINFO record for hwnd. Used during window initialization to establish the initial BiDi state based on the application's language or user preference.

Language viewer

Win32QueryLangViewer(hab, pszDllName, pszProcName) / WIN16QUERYLANGVIEWER
Returns the name of the registered language viewer DLL and entry point. The language viewer is an optional plug-in that provides the on-screen language indicator (a small flag or script label displayed in the window border or status bar).
Win32SetLangViewer(hab, pszDllName, pszProcName) / WIN16SETLANGVIEWER
Registers a language viewer DLL for the calling application.

Process language

Win32QueryProcessLangInfo(hab, pProcLangInfo) / WIN16QUERYPROCESSLANGINFO
Returns the process-wide language information: the default text direction, default keyboard layer, and BiDi attributes applied to all new windows. Applications that want consistent BiDi behavior for all their windows query this during startup.
Win32SetProcessLangInfo(hab, pProcLangInfo) / WIN16SETPROCESSLANGINFO
Sets the process-wide language information. Called once at application startup (after WinInitialize) to configure the BiDi mode for the whole application.

ISO Layout Services (layout_object_*)

The layout_object_* functions implement the ISO/IEC 9241-compatible POSIX Layout Services API, the same interface provided on AIX and HP-UX for portable BiDi text processing. This API is oriented toward text layout engines and word processors that need precise control over the BiDi algorithm.

layout_object_create(locale, pLayoutValues)
Creates a layout object — a handle encapsulating a BiDi layout context with a specific locale, text direction, shaping options, and numerals mode. Returns a LayoutObject_t handle or NULL on failure. pLayoutValues is an array of LayoutValueRec structures setting initial parameters.
layout_object_destroy(lobj)
Destroys a layout object and releases its resources.
layout_object_getvalues(lobj, pLayoutValues) / layout_object_getvaluesS
Queries current parameter values from a layout object. Each LayoutValueRec in pLayoutValues names a parameter to retrieve and receives its current value. Common parameters:
  • QueryTextDirection — base paragraph direction (LTR or RTL)
  • QueryShapeCharset — whether Arabic shaping is applied
  • QueryNumerals — numeral digit style (Western, National, Contextual)
  • QueryActiveDirectional — the directional override state
layout_object_setvalues(lobj, pLayoutValues)
Sets parameter values on a layout object.
layout_object_transform(lobj, pSrc, ulInpType, ulSrcLen, pDst, ulOutType, pulDstLen, pBidiLevels, pSrcToTrg, pTrgToSrc) / layout_object_transforml
The core layout transform operation. Converts pSrc (in logical order) to pDst (in visual order) applying the reordering, shaping, and numerals conversion configured in the layout object. Also fills optional per-character BiDi level array pBidiLevels and source↔target position maps pSrcToTrg / pTrgToSrc. The _l variant operates on long (multibyte) characters.
layout_object_editshape(lobj, pStr, ulLen, pDst, pulDstLen) / layout_object_editshapeN
Applies shaping to a string in the context of the layout object's current parameters. The N variant handles null-terminated input.

Usage

IBM VisualAge C++ / ILINK

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

OpenWatcom (wlink)

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

EMX/GCC

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

Include files

Header Contents
pmbidi.h Main BiDi header: Gpi32*, Nls32*, Bidi_*, PMBIDI_*, Win32* prototypes; BIDI_ATTR_*, BIDI_KBD_*, BIDI_LOG2VIS, BIDI_VIS2LOG constants; LANGINFO structure.
layout.h ISO layout services header: layout_object_* prototypes, LayoutObject_t, LayoutValueRec, QueryTextDirection and other parameter names.

Typical RTL window setup

/* Initialize BiDi for the process */
PMBIDI_Initialize();

PROCLANGINFO pli;
Win32QueryProcessLangInfo(hab, &pli);
pli.ulTextDirection = BIDI_TEXT_DIRECTION_RTL;
Win32SetProcessLangInfo(hab, &pli);

/* In WM_CREATE for a window that shows Arabic text */
LANGINFO li;
Win32QueryLangInfo(hab, hwnd, &li);
li.ulTextType = BIDI_TEXT_TYPE_VISUAL;
li.ulKeyboardLayer = BIDI_KBD_NATIVE;
Win32SetLangInfo(hab, hwnd, &li);

/* Prepare string for display */
CHAR szLogical[256];  /* text as stored / typed */
CHAR szVisual[256];   /* text for GpiCharString */
ULONG ulLen = strlen(szLogical);
Nls32ShapeBidiString(szLogical, szVisual, ulLen,
                     BIDI_CP864 | BIDI_LOG2VIS);
/* now GpiCharString(hps, ulLen, szVisual) */

GPI attribute example

/* Enable RTL text rendering on a PS */
ULONG ulAttr = 0;
Gpi32QueryBidiAttr(hps, &ulAttr);
ulAttr |= BIDI_ATTR_RTLREADING | BIDI_ATTR_ARABIC;
Gpi32SetBidiAttr(hps, ulAttr);

/* Now GpiCharString renders RTL with Arabic shaping */
GpiCharStringAt(hps, &ptl, strlen(szArabic), szArabic);

Codepage Support

Codepage Script Notes
CP862 Hebrew IBM PC Hebrew; used in Israel edition of OS/2
CP864 Arabic IBM PC Arabic; used in Arabic edition of OS/2
CP1255 Hebrew Windows Hebrew; fuller Unicode compatibility
CP1256 Arabic Windows Arabic; fuller Unicode compatibility

Version History

Version OS/2 release Date Notes
1.0 OS/2 Warp 3 (Hebrew and Arabic editions) 1994–1995 Initial release. Core Bidi_* and NLS16* / Nls32* functions. GPI BiDi attributes. Published separately as the OS/2 BiDi Developer's Toolkit supplement.
2.0 OS/2 Warp 4 1996 Added Win32* process and window language API, PMBIDI_* utility functions, layout_object_* ISO layout services.
2.x OS/2 Warp 4.52 Developer's Toolkit 4.5 2000 Final IBM release. File size: 5,632 bytes (2000-10-16). All functions exported by ordinal from PMBIDI.DLL.

Note: PMBIDI.DLL is present only on the Arabic and Hebrew national-language editions of OS/2 Warp. Standard Western (SBCS/DBCS CJK) editions do not include the BiDi subsystem. To test BiDi applications on a Western OS/2 install, the developer must install the BiDi run-time package from the separate IBM Language Supplement.

See Also

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