Jump to content

PMNLS386.LIB

From EDM2

PMNLS386.LIB is an import library for the OS/2 Presentation Manager National Language Support (PMNLS) subsystem, targeting 32-bit calling conventions. It provides linker stubs for the DBCS (Double Byte Character Set) PM API used in OS/2 Far East editions — the Japanese (CP932), Korean (CP934), Simplified Chinese (CP936), and Traditional Chinese (CP938) system variants. The API covers IME (Input Method Editor) control, input mode control, and DBCS font driver management.

This is the library to use for new 32-bit PM applications. A companion library, PMNLS286.LIB, provides the same seven functions targeting 16-bit-compatible calling conventions for the OS/2 Win16 compatibility subsystem.

File size in the OS/2 Warp 4.52 Toolkit 4.5: 4,096 bytes. Source DLL: PMNLS.DLL. Copyright: IBM Corporation 1981, 1988–1992. Activated by including os2nls.h (automatically included from pmwin.h when INCL_NLS is defined).

Platform Scope

The PMNLS API operates only on DBCS versions of OS/2 and is absent on SBCS (Single Byte Character Set) Western editions. Supported DBCS code pages:

Code page Language Character set
CP932 Japanese Shift-JIS (kanji, hiragana, katakana)
CP934 Korean EUC-KR (hangul, hanja)
CP936 Simplified Chinese GBK (hanzi)
CP938 Traditional Chinese Big5 (traditional hanzi, bopomofo)

Include Files

Header Activation macro Notes
os2nls.h INCL_NLS Primary DBCS PM API header; included automatically by pmwin.h
pmwin.h (transitively includes os2nls.h) PM window manager master header
os2.h (includes all PM headers) Full OS/2 API umbrella; define INCL_NLS before inclusion 
#define INCL_NLS
#define INCL_WINFRAMEMGR
#include <os2.h>

Naming Conventions

Each of the seven functions is exported under three name styles for migration support:

Prefix Example Source platform
WinDBCS* WinDBCSLoadFontDriver Native OS/2 PM — canonical name; use for new code
WIN16DBCS* WIN16DBCSLoadFontDriver Win16 migration — porting 16-bit Windows DBCS applications
Win32DBCS* Win32DBCSLoadFontDriver Win32 migration — porting 32-bit Windows DBCS applications

All three names for a given operation resolve to the same PMNLS.DLL export. New OS/2 applications should use the WinDBCS* names.

API Reference

IME Control

WinDBCSIMEControl(hab, hwndFrame, ulType, pIMEMode) → ULONG
Queries or sets the Input Method Editor (IME) state for a PM frame window. The IME manages the conversion of keystroke sequences into DBCS characters (kanji, hangul, etc.).
Parameter Type Description
hab HAB Anchor block handle for the calling thread
hwndFrame HWND Handle of the PM frame window to control
ulType ULONG DBE_IMCTL_QUERY (0x0001) to read state; DBE_IMCTL_SET (0x0002) to change it
pIMEMode PIMEMODE Pointer to an IMEMODE structure; receives current state on QUERY, provides desired state on SET

Returns 0 on success.

IMEMODE structure

typedef struct _IMEMODE {      /* imemode */
    ULONG  lenIMEMODE;         /* sizeof(IMEMODE) — must be initialized */
    ULONG  fIMEMode;           /* IME mode flags (DBE_IMCTL_*) */
    ULONG  hIME;               /* QUERY only: handle of active IME module */
    ULONG  hModIME;            /* QUERY only: DLL module handle of active IME */
} IMEMODE;
typedef IMEMODE *PIMEMODE;

fIMEMode flags

Constant Value Meaning
DBE_IMCTL_IMEENABLE 0x0001 Enable the IME for this frame window
DBE_IMCTL_IMEDISABLE 0x0002 Disable the IME for this frame window
DBE_IMCTL_IMEMODE 0x0004 Set IME conversion mode
DBE_IMCTL_NOTIMEMODE 0x0008 Clear IME conversion mode
DBE_IMCTL_INHERIT_PFRAME 0x0100 Inherit IME state from the parent frame window
DBE_IMCTL_INTERIMREQUEST 0x8000 Interim (on-the-spot) conversion request mode

Input Mode Control

WinDBCSModeControl(hab, hwndFrame, ulType, ulArg, pparm) → ULONG
Queries or sets the DBCS keyboard input conversion mode for a frame window. Controls whether the keyboard produces alphanumeric characters, phonetic kana, kanji, hangul, etc.
Parameter Type Description
hab HAB Anchor block handle
hwndFrame HWND Frame window handle
ulType ULONG DBE_MCTL_QUERY (0x0001) or DBE_MCTL_SET (0x0002)
ulArg ULONG Argument selector; use DBE_MCTL_INPUTMODEREQUEST (0x0001) for input mode
pparm PULONG Pointer to mode bits; on QUERY receives current mode, on SET provides new mode

Returns 0 on success.

Mode bits by code page

CP932 — Japanese:

Constant Value Mode
DBE_MCTL_ALPHANUMERIC 0x0001 ASCII/alphanumeric
DBE_MCTL_KATAKANA 0x0002 Katakana
DBE_MCTL_HIRAGANA 0x0004 Hiragana
DBE_MCTL_SBCSCHAR / DBE_MCTL_HANKAKU 0x0008 Half-width (SBCS) characters
DBE_MCTL_DBCSCHAR / DBE_MCTL_ZENKAKU 0x0010 Full-width (DBCS) characters
DBE_MCTL_ROMAN 0x0020 Roman (romaji) input
DBE_MCTL_NOROMAN 0x0040 Disable romaji
DBE_MCTL_INHERIT_PFRAME 0x0100 Inherit from parent frame
DBE_MCTL_KKCENABLE 0x1000 Enable kana-kanji conversion (KKC)
DBE_MCTL_KKCDISABLE 0x2000 Disable kana-kanji conversion

CP934 — Korean:

Constant Value Mode
DBE_MCTL_ALPHANUMERIC 0x0001 Alphanumeric
DBE_MCTL_JAMO 0x0002 Jamo (phonetic components)
DBE_MCTL_HANGEUL 0x0004 Hangeul syllables
DBE_MCTL_INTERIMREQUEST 0x0080 Interim conversion

CP936 — Simplified Chinese (PRC):

Constant Value Mode
DBE_MCTL_ALPHANUMERIC 0x0001 Alphanumeric
DBE_MCTL_HANZI 0x0002 Hanzi (simplified Chinese characters)

CP938 — Traditional Chinese (Taiwan):

Constant Value Mode
DBE_MCTL_ALPHANUMERIC 0x0001 Alphanumeric
DBE_MCTL_PHONETIC / DBE_MCTL_TWNIME 0x0002 Phonetic (Bopomofo) / Taiwan IME
DBE_MCTL_TSANGJYE 0x0004 Cang Jie (Tsang-Jye) input method

Font Driver Management

DBCS font drivers are DLLs that supply glyph data for DBCS characters to the GPI subsystem. They can be scoped per-process (private) or system-wide (public).

FD_DESC structure

typedef struct _FD_DESC {      /* fd_desc */
    ULONG  flType;             /* type flags: DBE_FD_DESC_* */
    CHAR   str64Desc[64];      /* human-readable description (null-terminated) */
} FD_DESC;
typedef FD_DESC *PFD_DESC;
flType constant Value Scope
DBE_FD_DESC_SYSTEM 0x0001 System (kernel-managed) font driver
DBE_FD_DESC_PUBLIC 0x0002 Public font driver — visible to all processes
DBE_FD_DESC_PRIVATE 0x0004 Private font driver — visible only to the loading process

Private font driver functions

WinDBCSLoadFontDriver(hab, psz) → BOOL
Loads a DBCS font driver DLL into the calling process as a private font driver. psz is the fully qualified path to the font driver DLL. Returns TRUE on success, FALSE on failure (check WinGetLastError).
WinDBCSUnloadFontDriver(hab, psz) → BOOL
Unloads a previously loaded private DBCS font driver. psz must be the same path string passed to WinDBCSLoadFontDriver. Returns TRUE on success.
WinDBCSQueryFDDescription(hab, psz, pfd_desc) → BOOL
Retrieves the type and description string of an installed DBCS font driver. psz is the font driver DLL path; pfd_desc receives the FD_DESC result. Returns TRUE on success.

Public font driver functions

WinDBCSLoadPublicFD(hab, psz) → BOOL
Loads a DBCS font driver DLL into the GPI subsystem as a public (system-wide) font driver, making it available to all processes. Requires appropriate system privilege. psz is the DLL path. Returns TRUE on success.
WinDBCSUnloadPublicFD(hab, psz) → BOOL
Unloads a public DBCS font driver from the GPI subsystem. psz must match the path used with WinDBCSLoadPublicFD. Returns TRUE on success.

286 vs. 386 Variants

Library Size Use case
PMNLS286.LIB 3,584 bytes 16-bit-compatible interface; OS/2 Win16 compatibility subsystem applications
PMNLS386.LIB 4,096 bytes 32-bit native interface; use this for all new PM applications

Both variants link against PMNLS.DLL and export the same seven functions under the same three naming tiers (WinDBCS*, WIN16DBCS*, Win32DBCS*). The difference is in the calling convention linkage records embedded in the OMF import stubs.

Build Instructions

IBM VisualAge C++ / ILINK

icc -O2 -Gm -c mydbcsapp.c
ilink /PM:PM mydbcsapp.obj os2386.lib pmnls386.lib

OpenWatcom

wcl386 -bt=os2 -mf -c mydbcsapp.c
wlink system os2v2_pm file mydbcsapp.obj library os2386.lib library pmnls386.lib

EMX/GCC

gcc -Zomf -c mydbcsapp.c
gcc -Zomf -o mydbcsapp.exe mydbcsapp.o -los2386 -lpmnls386

Code Examples

Enable IME on frame window creation

#define INCL_NLS
#define INCL_WINFRAMEMGR
#include <os2.h>

HWND CreateDBCSFrame(HAB hab, HMQ hmq)
{
    ULONG  flStyle = FCF_TITLEBAR | FCF_SYSMENU | FCF_SIZEBORDER
                   | FCF_MINMAX  | FCF_SHELLPOSITION | FCF_TASKLIST
                   | FCF_DBE_STATAREA;  /* include DBCS status area */
    HWND   hwndFrame, hwndClient;
    IMEMODE im;

    hwndFrame = WinCreateStdWindow(HWND_DESKTOP, WS_VISIBLE,
                                   &flStyle, "MyClientClass",
                                   "DBCS Window", 0,
                                   NULLHANDLE, ID_MAINWND, &hwndClient);

    /* Enable the IME for this frame */
    im.lenIMEMODE = sizeof(IMEMODE);
    im.fIMEMode   = DBE_IMCTL_IMEENABLE;
    WinDBCSIMEControl(hab, hwndFrame, DBE_IMCTL_SET, &im);

    return hwndFrame;
}

Toggle between hiragana and alphanumeric mode

#define INCL_NLS
#include <os2.h>

VOID ToggleInputMode(HAB hab, HWND hwndFrame, BOOL bHiragana)
{
    ULONG ulMode = bHiragana
        ? (DBE_MCTL_HIRAGANA | DBE_MCTL_DBCSCHAR)
        : DBE_MCTL_ALPHANUMERIC;

    WinDBCSModeControl(hab, hwndFrame,
                       DBE_MCTL_SET,
                       DBE_MCTL_INPUTMODEREQUEST,
                       &ulMode);
}

Query the active IME

#define INCL_NLS
#include <os2.h>
#include <stdio.h>

VOID ReportIME(HAB hab, HWND hwndFrame)
{
    IMEMODE im;

    im.lenIMEMODE = sizeof(IMEMODE);

    if (WinDBCSIMEControl(hab, hwndFrame, DBE_IMCTL_QUERY, &im) == 0) {
        printf("IME enabled: %s\n",
               (im.fIMEMode & DBE_IMCTL_IMEENABLE) ? "yes" : "no");
        printf("IME handle:  0x%08lX\n", im.hIME);
        printf("IME module:  0x%08lX\n", im.hModIME);
    }
}

Load and inspect a DBCS font driver

#define INCL_NLS
#include <os2.h>
#include <stdio.h>

VOID UseFontDriver(HAB hab, PSZ pszDrvPath)
{
    FD_DESC desc;

    if (!WinDBCSLoadFontDriver(hab, pszDrvPath)) {
        printf("Load failed\n");
        return;
    }

    if (WinDBCSQueryFDDescription(hab, pszDrvPath, &desc)) {
        printf("Type : %s%s%s\n",
               (desc.flType & DBE_FD_DESC_SYSTEM)  ? "SYSTEM "  : "",
               (desc.flType & DBE_FD_DESC_PUBLIC)  ? "PUBLIC "  : "",
               (desc.flType & DBE_FD_DESC_PRIVATE) ? "PRIVATE"  : "");
        printf("Desc : %s\n", desc.str64Desc);
    }

    WinDBCSUnloadFontDriver(hab, pszDrvPath);
}

Related DBCS PM Messages

os2nls.h defines additional PM messages and frame creation flags relevant to DBCS windows:

Symbol Value Purpose
WM_DBE_SETAPPLSTAT 0x00B6 Sent to the DBCS status area window to update displayed status
WM_DBE_KKCPARAMS 0x00BC Sent to query or set kana-kanji conversion parameters (KKCPARAMS structure in mp1)
FCF_DBE_STATAREA 0x80000000 Frame creation flag: include the DBCS keyboard status indicator area in the frame
SC_DBE_IME 0x8018 System menu item ID for the IME control dialog
SC_DBE_IMESEPARATOR 0x8019 System menu separator ID before the IME item

See Also

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