OS2IM.LIB

OS2IM.LIB is the import library for the OS/2 Input Method (IM) subsystem, distributed with the IBM OS/2 Developer's Toolkit. It provides the linker stubs for the API used to integrate Input Method Editor (IME) engines into OS/2 applications and to author new IMEs. The IM subsystem is the OS/2 infrastructure for entering CJK (Chinese, Japanese, Korean) text through multi-keystroke phonetic or stroke-based composition.

File size in the OS/2 Warp 4.52 Toolkit 4.5: 31,744 bytes (2001-10-02). Source DLL: OS2IM.DLL.

Concepts

Understanding the IM API requires familiarity with several OS/2-specific terms:

Term	Meaning
IME	Input Method Editor: a DLL that converts keystrokes into CJK characters. Multiple IMEs can be installed simultaneously (one per language or input style).
IM instance	A handle representing the association between one application window and one active IME. Created per-window; an application can have multiple instances for different windows.
Composition string	The partially-entered keystroke sequence being assembled before a final character is committed (e.g. the romaji being typed before the kanji is chosen).
Candidate list	The list of candidate characters or words the IME offers for the current composition string. The user selects one to commit.
Conversion window	The floating inline window that displays the composition string during input.
Status window	A floating window showing the current IME mode (e.g. Roman / Hiragana / Katakana / Full-width).
IM mode	The current input mode of an IME instance: Roman (pass-through), native script mode, full-width, etc.
IMI part	An IM instance part: a sub-component of an IM instance used to partition the IM session (advanced, used by IME authors).
IM service	The top-level IM subsystem session. Applications open a service handle before creating instances.

API Families

OS2IM.LIB exports 244 symbols across six API families, each present in both a short form and an explicit 32-bit form:

Prefix	Count	Role
`Im*`	~90	Application IM API (short form)
`Im32*`	~90	Application IM API (explicit 32-bit form; equivalent to `Im*`)
`Imem` / `Imem32`	~8	IME Manager: list installed IMEs, set session default
`Dsm` / `Dsm32`	~4	Dynamic Session Manager: register/deregister IM callback functions
`Krm` / `Krm32`	~3	Keyboard Resource Mapper: virtual-key translation for IME
`WinDefIme` / `Win32DefIme`	~4	Default PM window procedures for IME windows

The Im* and Im32* forms are identical in function; Im32* names are provided for explicit 32-bit source code clarity. Each function also carries the standard OS/2 calling-convention dual export (mixed-case _System form and uppercase FUNCTIONNAME form).

Service and Initialization

Process initialization

ImInitialize() / Im32Initialize(): Initializes the IM subsystem for the calling process. Must be called once before any other IM function. Returns 0 on success.

ImTerminate() / Im32Terminate(): Releases all IM resources allocated by the process. Call at application exit.

Service handles

ImOpenService(hab, reserved) / Im32OpenService(hab, reserved): Opens a handle to the IM service for the calling application. hab is the Presentation Manager anchor block handle returned by WinInitialize. Returns an HIMI service handle, or NULL on failure.

ImCloseService(himi) / Im32CloseService(himi): Closes an IM service handle and releases its resources.

IM Instance Management

An IM instance binds one application window to the active IME. Most IM operations take an instance handle (HIMC).

ImCreateInstance(himi, hwnd, pCreateStruct) / Im32CreateInstance(...): Creates an IM instance for hwnd. pCreateStruct is an IMCREATESTRUCT specifying the initial IME and mode. Returns an HIMC instance handle.

ImDestroyInstance(himi, himc) / Im32DestroyInstance(...): Destroys an IM instance and releases its resources.

ImAssociateInstance(himi, hwnd, himc, pOptions) / Im32AssociateInstance(...): Associates an existing IM instance with a (different) window. Used when a window's input focus moves between child controls that share one IM instance.

ImGetInstance(himi, hwnd) / Im32GetInstance(...): Returns the HIMC currently associated with hwnd.

ImGetInstanceMQ(himi, hmq) / Im32GetInstanceMQ(...): Returns the HIMC associated with a message queue handle rather than a window.

ImReleaseInstance(himi, himc) / Im32ReleaseInstance(...): Releases an instance handle obtained from ImGetInstance.

ImReleaseInstanceMQ(himi, hmq) / Im32ReleaseInstanceMQ(...): Releases an instance handle obtained from ImGetInstanceMQ.

ImQuerySessionDefInstance(himi) / Im32QuerySessionDefInstance(...): Returns the default HIMC for the current PM session.

ImQueryIMInstanceReqCount(himi, himc) / Im32QueryIMInstanceReqCount(...): Returns the reference count of an IM instance.

IME Selection and Configuration

Querying available IMEs

ImQueryIMEList(himi, pIMEList, pulCount) / Im32QueryIMEList(...): Enumerates all IMEs installed in the system. Fills pIMEList with an array of IMEID values and sets pulCount to the count.

ImQueryIMEID(himi, himc, pIMEID) / Im32QueryIMEID(...): Returns the IMEID of the IME currently active in himc.

ImQueryIMEInfo(himi, imeID, pIMEInfo) / Im32QueryIMEInfo(...): Returns an IMEINFO structure for a given IME: DLL name, description string, language code, capabilities flags.

ImQueryIMEProperty(himi, imeID, ulProperty) / Im32QueryIMEProperty(...): Queries a single IME capability or property flag (e.g. whether the IME supports candidate lists, full-width mode, or sentence conversion).

Current and default IME

ImQueryCurrentIME(himi, himc, pIMEID) / Im32QueryCurrentIME(...): Returns the IMEID of the IME currently active for an instance.

ImSetCurrentIME(himi, himc, imeID) / Im32SetCurrentIME(...): Switches the active IME for an instance. The new IME takes effect from the next keystroke.

ImQueryDefaultIME(himi, pIMEID) / Im32QueryDefaultIME(...): Returns the system-default IME for the current session.

ImSetDefaultIME(himi, imeID) / Im32SetDefaultIME(...): Sets the system-default IME.

Im32QueryDefaultIMWindow(himi, pHwnd): Returns the window handle of the default IME window for the session.

ImSetIMEListOrder(himi, pIMEList, ulCount) / Im32SetIMEListOrder(...): Reorders the installed IME list (e.g. to place the most-used IME first).

ImShowIMEDlg(himi, himc, ulFlags) / Im32ShowIMEDlg(...): Displays the IME's own configuration dialog (keyboard layout, dictionary, options).

IME registration (IME authors)

ImRegisterIME(himi, pIMEInfo) / Im32RegisterIME(...): Registers a new IME DLL with the IM subsystem. Called by an IME's installation program, not by applications.

ImDeregisterIME(himi, imeID) / Im32DeregisterIME(...): Removes an IME registration.

ImRequestIME(himi, imeID, ulRequest, pParam) / Im32RequestIME(...): Sends a control request directly to a registered IME DLL. Used by the system and IME configuration tools.

Input Mode

ImQueryIMMode(himi, himc, pulMode) / Im32QueryIMMode(...)

Returns the current input mode of an instance as a bitmask. Mode bits include:

IMMODE_ROMAN — pass-through (Latin) mode; keystrokes go directly to the application
IMMODE_NATIVE — native script mode; keystrokes feed the IME composition engine
IMMODE_FULLSHAPE — full-width ASCII mode
IMMODE_SYMBOL — symbol input mode

ImSetIMMode(himi, himc, ulMode) / Im32SetIMMode(...): Sets the input mode. Equivalent to the user pressing the IME mode toggle key.

Composition and Conversion

Composition string

ImGetConversionString(himi, himc, ulIndex, pBuffer, ulBufLen) / Im32GetConversionString(...)

Retrieves the current composition string, result string, or reading string. ulIndex selects which string:

GCS_COMPSTR — the partially-composed string currently being typed
GCS_RESULTSTR — the committed result string (after the user confirms a candidate)
GCS_COMPREADSTR — the reading (phonetic) string for the composition
GCS_RESULTREADSTR — the reading string for the committed result

ImSetConversionString(himi, himc, ulIndex, pString, ulLen) / Im32SetConversionString(...): Sets the composition or reading string programmatically. Used by applications that manage their own composition display.

ImConvertString(himi, himc, pSrc, pDst, pAlt) / Im32ConvertString(...): Requests the IME to perform a string conversion (e.g. convert hiragana to kanji). The result is returned asynchronously via an IM event.

ImGetResultString(himi, himc, ulIndex, pBuffer, ulBufLen) / Im32GetResultString(...): Retrieves the most recently committed result string.

ImGetStatusString(himi, himc, ulIndex, pBuffer, ulBufLen) / Im32GetStatusString(...): Retrieves the IME status string (mode description text for display in the status window).

Candidate list

ImQueryCandidateList(himi, himc, ulIndex, pCandList, ulBufLen) / Im32QueryCandidateList(...): Retrieves the candidate list for the current composition. pCandList points to an IMCANDIDATELIST structure containing an array of candidate strings and the current selection index.

Word registration

ImRegisterWord(himi, imeID, pReading, ulStyle, pWord) / Im32RegisterWord(...): Registers a custom word in the IME's user dictionary. pReading is the phonetic reading string; pWord is the target character(s); ulStyle identifies the word category.

ImDeregisterWord(himi, imeID, pReading, ulStyle, pWord) / Im32DeregisterWord(...): Removes a word from the user dictionary.

ImEnumRegisterWord(himi, imeID, pfnEnumProc, pReading, ulStyle, pWord, pData) / Im32EnumRegisterWord(...): Enumerates words in the user dictionary matching the given reading/style/word filter, calling pfnEnumProc for each match.

ImQueryRegisterWordType(himi, imeID, pWordTypeList, pulCount) / Im32QueryRegisterWordType(...): Returns the list of word style categories the IME supports for user dictionary registration.

Window Positions and Appearance

Conversion window

ImQueryConversionWindowPos(himi, himc, pPoint) / Im32QueryConversionWindowPos(...): Returns the screen position of the composition (conversion) window.

ImSetConversionWindowPos(himi, himc, pPoint) / Im32SetConversionWindowPos(...): Moves the conversion window. Applications call this to position the inline composition window near the insertion point.

ImQueryConversionAngle(himi, himc, pAngle) / Im32QueryConversionAngle(...): Returns the display angle of the conversion window (for vertical text layouts).

ImSetConversionAngle(himi, himc, pAngle) / Im32SetConversionAngle(...): Sets the display angle.

ImQueryConversionFont(himi, himc, pFontMetrics) / Im32QueryConversionFont(...): Returns the font used in the conversion window.

ImSetConversionFont(himi, himc, pFontMetrics) / Im32SetConversionFont(...): Sets the font for the conversion window.

ImQueryConversionFontSize(himi, himc, pSize) / Im32QueryConversionFontSize(...): Returns the font size used in the conversion window.

ImSetConversionFontSize(himi, himc, pSize) / Im32SetConversionFontSize(...): Sets the font size for the conversion window.

Candidate window

ImQueryCandidateWindowPos(himi, himc, ulIndex, pPoint) / Im32QueryCandidateWindowPos(...): Returns the position of the candidate list window.

ImSetCandidateWindowPos(himi, himc, ulIndex, pPoint) / Im32SetCandidateWindowPos(...): Moves the candidate list window.

Status window

ImQueryStatusWindowPos(himi, himc, pPoint) / Im32QueryStatusWindowPos(...): Returns the position of the IME status window.

ImSetStatusWindowPos(himi, himc, pPoint) / Im32SetStatusWindowPos(...): Moves the status window.

ImShowStatusWindow(himi, himc, fShow) / Im32ShowStatusWindow(...): Shows or hides the status window.

Hotkeys

ImQueryHotKey(himi, ulHotKeyID, pHotKey) / Im32QueryHotKey(...): Returns the key assignment for a given IM hotkey ID (e.g. the mode-toggle key, the candidate-list key).

ImSetHotKey(himi, ulHotKeyID, pHotKey) / Im32SetHotKey(...): Reassigns an IM hotkey.

Events and Messaging

Sending and receiving IM events

ImRequestEvent(himi, himc, pEvent) / Im32RequestEvent(...): Sends an IM event to the IME. Applications use this to drive the composition engine programmatically (e.g. to simulate a conversion request).

ImSendEvent(himi, himc, pEvent) / Im32SendEvent(...): Sends a synchronous event to the IME.

ImBroadcastData(himi, pData) / Im32BroadcastData(...): Broadcasts data to all IM instances in the session.

ImIsIMEMessage(himi, msg, mp1, mp2) / Im32IsIMEMessage(...): Returns TRUE if the given PM message is an IM subsystem message that should be forwarded to the IME rather than processed by the application.

ImQueryInfoMsg(himi, himc, msg, mp1, mp2, pInfo) / Im32QueryInfoMsg(...): Retrieves information from an IM notification message (IM_INFO posted to the application window when composition state changes).

Message queue integration

ImQueryMsgQueueProperty(himi, hmq, ulIndex, pValue) / Im32QueryMsgQueueProperty(...): Queries a property of the message queue's IM state.

ImSetMsgQueueProperty(himi, hmq, ulIndex, pValue) / Im32SetMsgQueueProperty(...): Sets a message queue IM property.

IME Escape

ImEscape(himi, himc, ulEscape, pData) / Im32Escape(...): IME-specific extension call. Allows applications and IME authors to exchange data through IME-defined escape codes that are not covered by the standard IM API. The set of valid ulEscape values and pData formats are defined by each individual IME.

IME Manager (Imem*)

The Imem* functions manage the per-session default IME independently of any specific IM instance. They are used by control panel applications and IME installers.

ImemQueryDefaultIME(pIMEID) / Imem32QueryDefaultIME(...): Returns the IMEID set as the system default.

ImemSetDefaultIME(imeID) / Imem32SetDefaultIME(...): Sets the system-wide default IME.

ImemQueryIMEList(pIMEList, pulCount) / Imem32QueryIMEList(...): Enumerates all installed IMEs without requiring an open service handle.

ImemQueryLangList(pLangList, pulCount) / Imem32QueryLangList(...): Returns the list of installed language codes for which IMEs are available.

Dynamic Session Manager (Dsm*)

The DSM interface is used by IME DLLs (not applications) to register callback functions with the IM subsystem. The subsystem calls these hooks when IM events occur.

DsmRegisterFunc(himi, ulFuncID, pfnCallback) / Dsm32RegisterFunc(...): Registers a callback function for a given IM subsystem event. ulFuncID identifies the hook point (e.g. instance creation, mode change, composition update).

DsmDeregisterFunc(himi, ulFuncID, pfnCallback) / Dsm32DeregisterFunc(...): Removes a previously registered callback.

Keyboard Resource Mapper (Krm*)

KrmImeVKeyXlate(himi, himc, usVKey, usFlags, pfTranslated) / Krm32ImeVKeyXlate(...): Translates a virtual key event through the IME's keyboard mapping table. The IME uses this to intercept keystrokes that have special meaning in the current input mode (e.g. converting a Latin key to a kana character). Returns the translated character or indicates that the key was consumed by the IME.

PM Window Procedures

WinDefImeWindowProc(hwnd, msg, mp1, mp2) / Win32DefImeWindowProc(...): Default window procedure for an IME's main window (the conversion or candidate window). IME DLLs call this from their own window procedure for messages they do not handle, analogous to WinDefWindowProc for standard PM windows.

WinDefImePartProc(hwnd, msg, mp1, mp2) / Win32DefImePartProc(...): Default window procedure for an IMI part window. Used by IME DLLs that implement sub-windows for parts of their UI.

IM Instance Parts (IMIPart)

IMI parts are sub-components of an IM instance used when an IME needs to partition its session state (advanced IME authoring scenario, not needed for ordinary application development):

ImCreateIMIPart, ImDestroyIMIPart, ImReleaseIMIPart, ImRequestIMInstance, ImRequestIMIPart, ImReleaseIMInstance, ImResizeIMIPart, ImQueryIMIPartReqCount, ImQueryIMIPartSize

Usage

IBM VisualAge C++ / ILINK

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

OpenWatcom (wlink)

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

EMX/GCC

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

Include files

Header	Contents
`os2im.h`	Master IM header: all `Im`, `Im32`, `Imem`, `Dsm`, `Krm` prototypes; `HIMC`, `HIMI`, `IMEID`, `IMEINFO`, `IMCANDIDATELIST`, `IMCREATESTRUCT` type definitions; `GCS_`, `IMMODE_`, `IMN_` constants.

Typical PM application integration

A PM application that supports IM input handles the IM_INFO message posted to its client window whenever the IME changes composition state:

/* Initialization */
HIMI himi = ImOpenService(hab, 0);
HIMC himc = ImCreateInstance(himi, hwndClient, &createStruct);

/* In WndProc */
case WM_SETFOCUS:
    ImAssociateInstance(himi, hwndClient, himc, NULL);
    break;

case IM_INFO:
    /* Composition string changed - repaint inline display */
    CHAR buf[256];
    ImGetConversionString(himi, himc, GCS_COMPSTR, buf, sizeof(buf));
    /* draw buf at caret position */
    break;

case WM_CHAR:
    if (ImIsIMEMessage(himi, WM_CHAR, mp1, mp2))
        break;  /* consumed by IME */
    /* normal key processing */
    break;

/* Cleanup */
ImDestroyInstance(himi, himc);
ImCloseService(himi);
ImTerminate();

Version History

Version	OS/2 release	Date	Notes
1.0	OS/2 Warp 3 (DBCS editions)	1994	Initial release for Japanese, Chinese (Traditional/Simplified), and Korean editions of OS/2 Warp. Core `Im*` API.
2.0	OS/2 Warp 4 (DBCS editions)	1996	Added `Im32*` explicit 32-bit forms, word registration API (`ImRegisterWord`, `ImEnumRegisterWord`), hotkey management, DSM callback registration.
2.1	OS/2 Warp 4.52 Developer's Toolkit 4.5	2001	Added `Imem32*` variants, `ImQueryDefaultIMWindow`, refinements to candidate and status window APIs. Final IBM release. File size: 31,744 bytes.

Note: OS2IM.LIB and OS2IM.DLL are present only on DBCS (Double-Byte Character Set) editions of OS/2 — Japanese, Chinese, and Korean. SBCS (Single-Byte, Western) OS/2 installations do not include the IM subsystem.