Announcing

The 32-bit Unicode Console API for OS/2

version 1.0.3
by
Jonathan de Boyne Pollard

As shipped, OS/2 Warp has no 32-bit Console API. It has the same 16-bit VIO, KBD, and MOU subsystems that were in OS/2 version 1. It is impossible to write a purely 32-bit OS/2 program that has a textual user interface (other than the simplest "glass tty" style of interface), since the program must contain some 16-bit code in order to thunk down to and call those 16-bit subsystems.

For many years, the IBM Developer Connection CD-ROMs have contained "32TEXT", a beta version of new 32-bit VIO, KBD, and MOU subsystems for Intel OS/2 that were inspired by the 32-bit VIO, KBD, and MOU subsystems that were in PowerPC OS/2. But this code has remained beta code accessible only to those with DevCon subscriptions, and has never been added to the operating system proper. It looks as if it never will be, at this rate. Moreover, the DLLs on the DevCon CD-ROMs contain numerous bugs, not the least of which is a problem in the 32-bit KbdCharIn API function that causes SYS3175s if more than one "console mode" process is running in the system at any one time.

The 32-bit Unicode Console API is a completely new console API for textual user interface programs. By using it, applications programmers no longer need to have 16-bit code in their applications that performs thunking. If the application uses no other 16-bit APIs (either explicitly or via the runtime library of the compiler used to build it), its executables should contain no 16-bit memory objects at all and will be "Pure 32-bit".

On IBM OS/2, the 32-bit Unicode Console API is implemented on top of the 32-bit VIO, MOU, and KBD subsystems. Rather than using IBM's "32TEXT" API from the DevCon CD-ROMs, it is bundled with an implementation of those subsystems that is DLL entrypoint compatible with 32TEXT but which does not suffer from the aforementioned problem in KbdCharIn().

FEATURES

As far as applications are concerned, characters written to and read from the console are in Unicode. A "cell" on the console display is a combination of an attribute byte and a Unicode character.

Since the PC display hardware itself uses a single-byte character set (as do the underlying OS/2 subsystems), the API translates from Unicode to a single-byte character set according to the current code page. Code pages 437 (U.S. PC), 850 ("International"), and 1004 (ISO 8859-1, a.k.a. "Latin 1") are fully supported.
The 32-bit Unicode Console API is similar in operation to the console API used in Win32, making it easy to port from Win32 to an OS/2 program that uses the 32-bit Unicode Console API (certainly easier than porting from Win32 to the 16-bit VIO, MOU, and KBD subsystems).
OS/2 programs can choose to migrate to the 32-bit VIO, KBD, and MOU subsystems, which are only available on IBM OS/2, or to the 32-bit Unicode Console API proper.
The Console API uses the standard system calling convention, and should thus be accessible from any programming language, provided that suitable headers/interface definitions are written. (Only bindings for the C++ language are supplied as part of the package itself. The import libraries are not specific to any particular language, of course.)
A replacement <bse.h> header, a new <bsecon.h> header and a new CONCALLS.LIB import library are provided for applications wishing to use the new 32-bit Unicode Console API (accessible via a new INCL_CONSOLE feature enabling macro similar to the other INCL_xxxx macros).
A replacement <bsesub.h> header and CON3216.LIB import library are supplied so that applications can use the 32-bit VIO, MOU, and KBD APIs. Applications can also use the replacement <bsesub.h> that is supplied in IBM's "32TEXT" package, instead.
The new 32-bit VIO, KBD, and MOU APIs are contained in a single, self-contained DLL, CON3216.DLL. The new 32-bit Unicode Console API is contained in CONCALLS.DLL. Both simply drop in to the \OS2\DLL directory.
The package also contains a freely distributable runtime-only package, suitable for distribution to end users, containing just the Runtime DLLs for IBM OS/2 and the directions for installing them. This allows applications to be distributed without having to bundle the new DLLs along with them (in much the same way that EMXRT.ZIP or VBRUN.ZIP are distributed separately from the applications that use their DLLs).

For full information, see the on-line documentation.

© Copyright 2000,2001,2009 Jonathan de Boyne Pollard. "Moral" rights asserted.
Permission is hereby granted to copy and to distribute this web page in its original, unmodified form as long as its last modification datestamp information is preserved.