Jump to content

PMNLS286.LIB

From EDM2

PMNLS286.LIB is an import library for the OS/2 Presentation Manager National Language Support (PMNLS) subsystem, targeting 16-bit-compatible 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.

A companion library, PMNLS386.LIB, provides the same seven functions under the same naming conventions but targets 32-bit calling conventions for native 32-bit PM applications.

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

Platform Scope

The PMNLS API functions operate only on DBCS versions of OS/2. They are not available on SBCS (Single Byte Character Set) Western editions. Attempting to call them on a non-DBCS system will result in an error. The supported DBCS code pages and their languages are:

Code page Language Region
CP932 Japanese (Shift-JIS) Japan
CP934 Korean (EUC-KR) Korea
CP936 Simplified Chinese (GBK) PRC
CP938 Traditional Chinese (Big5) Taiwan

Include Files

Header Condition Notes
os2nls.h #define INCL_NLS Primary DBCS PM header; automatically included by pmwin.h when INCL_NLS is defined
pmwin.h (includes os2nls.h) Master PM window manager header; define INCL_NLS before including
os2.h (includes both) Full OS/2 API umbrella header with INCL_NLS defined

Example: 

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

Naming Conventions

Each of the seven functions is exported under three different name styles to support application migration from different platforms:

Prefix Example Purpose
WinDBCS* WinDBCSLoadFontDriver Native OS/2 PM API name. Used in new OS/2 DBCS applications. Prototypes in os2nls.h.
WIN16DBCS* WIN16DBCSLoadFontDriver Win16 compatibility name. Used when porting 16-bit Windows DBCS applications to OS/2.
Win32DBCS* Win32DBCSLoadFontDriver Win32 compatibility name. Used when porting 32-bit Windows DBCS applications to OS/2.

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)
Queries or sets the Input Method Editor (IME) state for a frame window. The IME is the input subsystem that converts keystrokes into DBCS characters (e.g., kanji, hangul).
Parameter Type Description
hab HAB Anchor block handle for the calling thread
hwndFrame HWND Handle to the PM frame window whose IME state is being controlled
ulType ULONG Operation type: DBE_IMCTL_QUERY (0x0001) to read current state, DBE_IMCTL_SET (0x0002) to change it
pIMEMode PIMEMODE Pointer to an IMEMODE structure (see below). For QUERY, receives the current state; for SET, provides the desired state.

Returns a ULONG result code (0 = success).

IMEMODE structure

typedef struct _IMEMODE {      /* imemode */
    ULONG  lenIMEMODE;         /* size of this structure */
    ULONG  fIMEMode;           /* IME mode flags (DBE_IMCTL_*) */
    ULONG  hIME;               /* query only: handle of active IME */
    ULONG  hModIME;            /* query only: module handle of active IME */
} IMEMODE;
typedef IMEMODE *PIMEMODE;

fIMEMode flags

Flag 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 the IME conversion mode
DBE_IMCTL_NOTIMEMODE 0x0008 Clear the IME conversion mode
DBE_IMCTL_INHERIT_PFRAME 0x0100 Inherit IME state from the parent frame window
DBE_IMCTL_INTERIMREQUEST 0x8000 Interim conversion request mode

Input Mode Control

WinDBCSModeControl(hab, hwndFrame, ulType, ulArg, pparm)
Queries or sets the DBCS keyboard input mode for a frame window. Controls whether input is in alphanumeric, hiragana, katakana, 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. Currently: DBE_MCTL_INPUTMODEREQUEST (0x0001) for input mode control.
pparm PULONG Pointer to mode parameter ULONG. On QUERY, receives current mode bits. On SET, provides desired mode bits.

Mode bits (pparm value) by code page

CP932 Japanese:

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

CP934 Korean:

Bit Value Mode
DBE_MCTL_ALPHANUMERIC 0x0001 Alphanumeric input
DBE_MCTL_JAMO 0x0002 Jamo (Korean phonetic) input
DBE_MCTL_HANGEUL 0x0004 Hangeul input
DBE_MCTL_INTERIMREQUEST 0x0080 Interim conversion request

CP936 Simplified Chinese (PRC):

Bit Value Mode
DBE_MCTL_ALPHANUMERIC 0x0001 Alphanumeric input
DBE_MCTL_HANZI 0x0002 Hanzi (simplified) input

CP938 Traditional Chinese (Taiwan):

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

Font Driver Management

PMNLS.DLL provides three categories of font driver functions. A DBCS font driver is a DLL that provides glyphs for DBCS characters (kanji, hangul, etc.) to the GPI subsystem. Font drivers can be loaded per-process (private) or system-wide (public).

FD_DESC structure

typedef struct _FD_DESC {      /* fd_desc */
    ULONG  flType;             /* font driver type flags (DBE_FD_DESC_*) */
    CHAR   str64Desc[64];      /* description string (null-terminated) */
} FD_DESC;
typedef FD_DESC *PFD_DESC;
flType flag Value Meaning
DBE_FD_DESC_SYSTEM 0x0001 System (kernel-level) font driver
DBE_FD_DESC_PUBLIC 0x0002 Public (shared, all-process) font driver
DBE_FD_DESC_PRIVATE 0x0004 Private (per-process) font driver

Private font driver functions

Private font drivers are loaded into the calling process only.

WinDBCSLoadFontDriver(hab, psz)
Loads a DBCS font driver DLL into the calling process. psz is the fully-qualified path to the font driver DLL (e.g., "C:\\OS2\\DLL\\JPNFONT.DLL"). Returns TRUE on success, FALSE on failure.
WinDBCSUnloadFontDriver(hab, psz)
Unloads a previously-loaded private DBCS font driver from the calling process. psz must be the same path string used to load it. Returns TRUE on success.
WinDBCSQueryFDDescription(hab, psz, pfd_desc)
Retrieves the description and type of an installed font driver. psz is the font driver DLL path; pfd_desc points to an FD_DESC structure to receive the information. Returns TRUE on success.

Public font driver functions

Public font drivers are loaded into the shared GPI subsystem and are available to all processes.

WinDBCSLoadPublicFD(hab, psz)
Loads a DBCS font driver DLL system-wide as a public font driver. Requires appropriate privilege. psz is the path to the font driver DLL. Returns TRUE on success.
WinDBCSUnloadPublicFD(hab, psz)
Unloads a public DBCS font driver from the system. psz must match the path used in the corresponding WinDBCSLoadPublicFD call. Returns TRUE on success.

286 vs. 386 Libraries

The Toolkit provides two variants of the PMNLS import library:

Library Size Target
PMNLS286.LIB 3,584 bytes 16-bit compatible interface (Win16 DBCS migration path; 16-bit OS/2 subsystem applications)
PMNLS386.LIB 4,096 bytes 32-bit native interface (standard 32-bit PM applications)

Both libraries export the same seven functions under the same three naming tiers (WinDBCS*, WIN16DBCS*, Win32DBCS*) and link against PMNLS.DLL. Use PMNLS386.LIB for new 32-bit PM applications; use PMNLS286.LIB only when building for the 16-bit OS/2 application compatibility subsystem.

Usage

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

Enabling the IME for a PM Frame Window

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

/* Enable IME for a newly created frame window */
VOID EnableIME(HAB hab, HWND hwndFrame)
{
    IMEMODE imeMode;

    imeMode.lenIMEMODE = sizeof(IMEMODE);
    imeMode.fIMEMode   = DBE_IMCTL_IMEENABLE;
    imeMode.hIME       = 0;
    imeMode.hModIME    = 0;

    WinDBCSIMEControl(hab, hwndFrame, DBE_IMCTL_SET, &imeMode);
}

/* Query current IME status */
VOID QueryIME(HAB hab, HWND hwndFrame)
{
    IMEMODE imeMode;

    imeMode.lenIMEMODE = sizeof(IMEMODE);

    if (WinDBCSIMEControl(hab, hwndFrame, DBE_IMCTL_QUERY, &imeMode) == 0) {
        /* imeMode.fIMEMode now reflects current state */
        /* imeMode.hIME contains the active IME handle */
    }
}

Setting Japanese Input Mode

#define INCL_NLS
#include <os2.h>

/* Switch to hiragana input mode for a frame window */
VOID SetHiraganaMode(HAB hab, HWND hwndFrame)
{
    ULONG ulMode = DBE_MCTL_HIRAGANA | DBE_MCTL_DBCSCHAR;

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

Loading a DBCS Font Driver

#define INCL_NLS
#include <os2.h>

BOOL LoadDBCSFont(HAB hab)
{
    FD_DESC desc;

    /* Load a private (per-process) DBCS font driver */
    if (!WinDBCSLoadFontDriver(hab, "C:\\OS2\\DLL\\JPNFONT.DLL"))
        return FALSE;

    /* Query its description */
    if (WinDBCSQueryFDDescription(hab, "C:\\OS2\\DLL\\JPNFONT.DLL", &desc)) {
        /* desc.flType will be DBE_FD_DESC_PRIVATE */
        /* desc.str64Desc contains the driver's description string */
    }

    return TRUE;
}

VOID UnloadDBCSFont(HAB hab)
{
    WinDBCSUnloadFontDriver(hab, "C:\\OS2\\DLL\\JPNFONT.DLL");
}

DBCS Virtual Key Constants

os2nls.h defines an extended set of virtual key constants for DBCS keyboards, supplementing the standard VK_* constants defined in pmwin.h:

Constant Value Key
VK_DBE_FIRST 0x80 First DBCS virtual key
VK_DBE_LAST 0xFF Last DBCS virtual key
VK_DBE_ALPHANUMERIC 0x80 Alphanumeric mode key (CP932)
VK_DBE_KATAKANA 0x81 Katakana key (CP932)
VK_DBE_HIRAGANA 0x82 Hiragana key (CP932)
VK_DBE_SBCSCHAR 0x83 Half-width character key (CP932)
VK_DBE_DBCSCHAR 0x84 Full-width character key (CP932)
VK_DBE_SBCSDBCSCHAR 0x85 SBCS/DBCS toggle key (CP932)
VK_DBE_ROMAN 0x86 Roman (romaji) key (CP932)
VK_DBE_HANJA 0x87 Hanja key (CP934)
VK_DBE_HANGEUL 0x88 Hangeul key (CP934)
VK_DBE_JAMO 0x89 Jamo key (CP934)
VK_DBE_HANZI 0x8A Hanzi key (CP936)
VK_DBE_TSANGJYE 0x8C Tsang-Jye key (CP938)
VK_DBE_PHONETIC 0x8D Phonetic (Bopomofo) key (CP938)
VK_DBE_KANJI / VK_DBE_IMEACTIVATE 0xA0 Kanji/IME activate key
VK_DBE_CONV 0xA1 Conversion key
VK_DBE_NOCONV 0xA2 Non-conversion key

DBCS Status Area Window Classes

os2nls.h defines pre-allocated PM window class IDs for the DBCS keyboard status indicator area (the floating status window that shows the current input mode):

Constant Value Purpose
WC_DBE_APPSTAT 0xFFFF0010 Application status area window
WC_DBE_KBDSTAT 0xFFFF0011 Keyboard status indicator window
WC_DBE_PECIC 0xFFFF0012 Pre-edit conversion-in-context (PECIC) window

Frame windows on DBCS OS/2 editions include a keyboard status indicator automatically when FCF_DBE_STATAREA (0x80000000L) is specified in the frame creation flags.

See Also

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