home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / conapi.zip / TAU / README / CONAPI / Blurb.TXT next >
Text File  |  2000-02-11  |  7KB  |  137 lines
  1.  
  2.                               Announcing the
  3.  
  4.                         ──────────────────────────
  5.                         32-bit Unicode Console API
  6.                         ──────────────────────────
  7.  
  8. As shipped, OS/2 Warp has no 32-bit Console API.  It has the same 16-bit
  9. VIO, KBD, and MOU subsystems that were in OS/2 version 1.  It is
  10. impossible to write a purely 32-bit OS/2 program that has a textual user
  11. interface (other than the simplest "glass tty" style of interface), since
  12. the program must contain some 16-bit code in order to thunk down to and
  13. call those 16-bit subsystems.
  14.  
  15. For many years, the IBM Developer Connection CD-ROMs have contained
  16. "32TEXT", a beta version of new 32-bit VIO, KBD, and MOU subsystems for
  17. Intel OS/2 that were inspired by the 32-bit VIO, KBD, and MOU subsystems
  18. that were in PowerPC OS/2.  But this code has remained beta code
  19. accessible only to those with DevCon subscriptions, and has never been
  20. added to the operating system proper.  It looks as if it never will be, at
  21. this rate.  Moreover, the DLLs on the DevCon CD-ROMs contain numerous
  22. bugs, not the least of which is a problem in the 32-bit KbdCharIn API
  23. function that causes SYS3175s if more than one "console mode" process is
  24. running in the system at any one time.
  25.  
  26. The 32-bit Unicode Console API is a completely new console API for textual
  27. user interface programs.  By using it, applications programmers no longer
  28. need to have 16-bit code in their applications that performs thunking.  If
  29. the application uses no other 16-bit APIs (either explicitly or via the
  30. runtime library of the compiler used to build it), its executables should
  31. contain no 16-bit memory objects at all and will be "Pure 32-bit".
  32.  
  33. On IBM OS/2, the 32-bit Unicode Console API is implemented on top of the
  34. 32-bit VIO, MOU, and KBD subsystems.  Rather than using IBM's "32TEXT" API
  35. from the DevCon CD-ROMs, it is bundled with an implementation of those
  36. subsystems that is DLL entrypoint compatible with 32TEXT but which does
  37. not suffer from the aforementioned problem in KbdCharIn().
  38.  
  39. FEATURES
  40. ────────
  41.  
  42. ■ As far as applications are concerned, characters written to and read
  43.   from the console are in Unicode.  A "cell" on the console display is a
  44.   combination of an attribute byte and a Unicode character.
  45.  
  46.   Since the PC display hardware itself uses a single-byte character set
  47.   (as do the underlying OS/2 subsystems), the API translates from Unicode
  48.   to a single-byte character set according to the current code page.  Code
  49.   pages 437 (U.S. PC), 850 ("International"), and 1004 (ISO 8859-1, a.k.a.
  50.   "Latin 1") are fully supported.
  51.  
  52. ■ The 32-bit Unicode Console API is similar in operation to the console
  53.   API used in Win32, making it easy to port from Win32 to an OS/2 program
  54.   that uses the 32-bit Unicode Console API (certainly easier than porting
  55.   from Win32 to the 16-bit VIO, MOU, and KBD subsystems).
  56.  
  57. ■ OS/2 programs can choose to migrate to the 32-bit VIO, KBD, and MOU
  58.   subsystems, which are only available on IBM OS/2, or to the 32-bit
  59.   Unicode Console API proper.
  60.  
  61. ■ The Console API uses the standard system calling convention, and should
  62.   thus be accessible from any programming language, provided that suitable
  63.   headers/interface definitions are written.  (Only bindings for the C++
  64.   language are supplied as part of the package itself.  The import
  65.   libraries are not specific to any particular language, of course.)
  66.  
  67. ■ A replacement <bse.h> header, a new <bsecon.h> header and a new
  68.   CONCALLS.LIB import library are provided for applications wishing to use
  69.   the new 32-bit Unicode Console API (accessible via a new INCL_CONSOLE
  70.   feature enabling macro similar to the other INCL_xxxx macros).
  71.  
  72. ■ A replacement <bsesub.h> header and CON3216.LIB import library are
  73.   supplied so that applications can use the 32-bit VIO, MOU, and KBD APIs.
  74.   Applications can also use the replacement <bsesub.h> that is supplied in
  75.   IBM's "32TEXT" package, instead.
  76.  
  77. ■ The new 32-bit VIO, KBD, and MOU APIs are contained in a single,
  78.   self-contained DLL, CON3216.DLL.  The new 32-bit Unicode Console API is
  79.   contained in CONCALLS.DLL.  Both simply drop in to the \OS2\DLL
  80.   directory.
  81.  
  82. ■ The package also contains a freely distributable runtime-only package,
  83.   suitable for distribution to end users, containing just the Runtime DLLs
  84.   for IBM OS/2 and the directions for installing them.  This allows
  85.   applications to be distributed without having to bundle the new DLLs
  86.   along with them (in much the same way that EMXRT.ZIP or VBRUN.ZIP are
  87.   distributed separately from the applications that use their DLLs).
  88.  
  89. WHERE TO FIND THE 32-BIT UNICODE CONSOLE API
  90. ────────────────────────────────────────────
  91.  
  92. The primary repository for the distribution archive (which is available in
  93. both ZIP and RAR format) are FIDONET nodes 1:109/921.0 (TSR BBS in the
  94. U.S.) and 2:257/609.0 (Air Applewood BBS in Europe), from whence it can be
  95. File Requested by anyone at any time of the day.
  96.  
  97. The distribution archive is also available on any site that hosts the
  98. Fidonet file distribution echo from Fernwood BBS in the U.S., and on the
  99. Hobbes FTP site run by New Mexico State University and the LEO FTP site.
  100.  
  101. The file names for the Console API and developers' toolkit are CONAPI.ZIP
  102. and CONAPI.RAR.  The filenames for the archive containing just the Console
  103. API Runtime DLLs are CONRT.ZIP and CONRT.RAR.
  104.  
  105.  
  106. ABOUT THE AUTHOR
  107. ────────────────
  108.  
  109. Jonathan de Boyne Pollard is a professional computer programmer who
  110. specialises in consultancy and development of operating systems and tools.
  111. Other previous projects of his include such things as a complete
  112. replacement for the runtime library for Borland C++ 3.1, allowing it to be
  113. used to develop 16-bit OS/2 programs; and the OS/2 Command Line Utilities,
  114. a suite of many useful command-line tools for OS/2 ranging from file
  115. finders to digital clocks.  He also maintained the Highly Unofficial
  116. Fidonet OS2PROG C++ Compiler Pros and Cons List for several years, and is
  117. the moderator of the international OS2DOS Fidonet echo.  He is currently
  118. working on a project which he believes will astonish 32-bit OS/2 users.
  119.  
  120. The best, most reliable, and quickest, way to contact him is on Fidonet,
  121. by sending netmail addressed to either
  122.  
  123.     Jonathan de Boyne Pollard, FIDONET#2:257/609.3
  124.  
  125.         or
  126.  
  127.     Jonathan de Boyne Pollard, FIDONET#1:109/921.70,
  128.  
  129. which are his two permanent "point" addresses.  Alternatively, you can
  130. post a message in the Fidonet OS2PROG or OS2 echoes.
  131.  
  132. Another way to contact him is via the Internet mailbox
  133. <J.deBoynePollard@tesco.net>.  Since this is a mailbox hosted by one of
  134. the U.K.'s "free ISPs", and subject to the standard "use every 90 days or
  135. it will be deleted" conditions that such ISPs impose, this latter address
  136. is not guaranteed to be reliable, or even valid, however.
  137.