View source for Workplace OS/2 and OS/2 32-Bit API Strategy

''by [[Ken Borgendale]] and [[Arnold Bramnick]]''

The OS/2 Version 2.1 operating system provides you with a solid platform on which you can develop 32-bit applications. We promised that your investment in 32-bit OS/2 APIs would be safe and repaid with portability. Workplace OS/2 (WP-OS/2) will deliver on that promise by providing a portable platform for pure 32-bit OS/2 applications, and opens the door to true source portability between platforms.

You have asked for 32-bit versions of the keyboard (Kbd), mouse (Mou) and Video (Vio) APIs to allow the migration of 16-bit text mode applications to 32-bit applications. WP-OS/2 will provide base video and console support by implementing 32-bit versions of most of the OS/2 1.x Vio, Mou, and Kbd calls. However, a few of these calls do not have 32-bit counterparts due to platform portability issues.

This version of The Developer Connection for OS/2 contains the tools necessary to build a 32-bit OS/2 application that uses Kbd, Mou, or Vio. That application will run today on OS/2 Version 2.1 and be fully portable to WP-OS/2. 

==History==
In OS/2 Version 1.0, no windowing system existed, and Vio was the primary method of graphical interaction. Vio created a virtual model of the video support of the VGA hardware. The Vio functions replaced the DOS BIOS calls and some of the Vio functions allowed direct access to hardware functions. A subset of the Vio functions was allowed within a [[FAPI]] program that can be run in both OS/2 and DOS.

Note: FAPI is a set of 'Family' APIs that are common between OS/2 and DOS. This allowed a programmer to create a single binary that would run natively in both environments. Since FAPI was inherently 16-bit, this solution will not be available on Workplace OS.

OS/2 Version 1.1 introduced Presentation Manager (PM). The full-base OS/2 still existed, but a complete separation still existed between the base and PM. PM added a new graphics interaction using the Win and Gpi calls. In addition, a virtual Vio was created that let you run programs written for Vio in a PM window. Several of the Vio calls that are closely tied to physical hardware are not supported in windowed Vio.

By OS/2 Version 2.0, the base and PM had merged to some extent. The two video systems (PM and base) still existed, but PM was clearly the dominant video system. And because the PM interface was the preferred method of system interaction, the Vio calls were not implemented as 32-bit APIs.

This resulted in the occasional use of Vio or Kbd (16-bit) calls by otherwise full 32-bit PM applications, often only in installation and error handling. There are also functions, such as command prompts and host emulation, for which Vio is a natural implementation method. Because no 32-bit APIs existed, those applications also remained 16-bit. 

==Detailed APIs==
The following provides a high-level description of the migration of the 16-bit APIs to 32-bit. Read the appropriate .doc file on the CD-ROM to see the specifics of this 32-bit API solution for WP-OS/2.

==Vio and Avio Calls==
Return codes from the Vio calls are [[USHORT]] in the 16-bit APIs. This is changed to [[APIRET]] (32-bit unsigned) in the 32-bit APIs. Most USHORTs in the parameter lists have been changed to [[ULONG]].

The HVIO operand is zero for most calls, but can be the value returned by [[VioCreatePS]].

The [[AVIO|Avio]] calls let PM applications use windowed Vio. These remain unchanged, except that the Avio font logic will be extended. Register, physical buffer, and base font support will not be migrated to 32-bit APIs.

==Kbd Calls==
Registration, custom keyboard, and logical keyboard Kbd calls will not be migrated in 32-bit APIs. Therefore, the KbdHandle field must always be set to zero. The synchronization provided by logical keyboards must continue to be implemented by creating threads that wait for a mouse or keyboard event.

==Mou Calls==
Mou calls cannot be made from a PM session. In this case, use the PM mouse messages. Mouse calls that are made in a Vio window will work in WP-OS/2. For portability reasons, the only calls that will not be migrated to 32-bit will be [[MouDeRegister]] and [[MouRegister]]. The return codes are changed from USHORT to APIRET (32-bit unsigned).

==An Example==
In most cases, the 32-bit textmode APIs are the same as the previous 16-bit OS/2 1.x textmode APIs. The following general changes have been made:
* Most USHORT operands have been changed to ULONG. This is normally only a problem for return data fields.
* All fields have been placed on natural alignment (4-byte boundary for 4-byte fields). The length of some structures has changed. This can cause problems if you have hard-coded a size, instead of using sizeof().
* Several names have been expanded. For instance, [[VioScrollDn]]() is now [[VioScrollDown]](). Defines are provided for the old names. The return code is APIRET, which is an unsigned long (it was an unsigned short).

Note: Most of these require changes only to the declarations of the operands, and not of the API call itself.

Using 16-bit API's:
 USHORT row, column, rc; /* Variables were short */
 HVIO hvio;
 BYTE cell[2];
 VIOCONFIGINFO config;
 
 hvio = 0;
 rc = VioGetCurPos (&row, &column, hvio);
 rc = VioScrollDn (row, 0, row+3, column, 1, &cell, hvio);
 config.cb = sizeof(VIOCONFIGINFO); /* All config items */
 rc = VioGetConfig(0, &config, hvio);

Using 32-bit API's:
 ULONG row, column, rc; /* Change to ULONG */
 HVIO hvio;
 BYTE cell[2];
 VIOCONFIGINFO config;
 
 hvio = 0;
 rc = VioGetCurPos (&row, &column, hvio);
 rc = VioScrollDown (row, 0, row+3, column, 1, &cell, hvio);
 config.cb = sizeof(VIOCONFIGINFO); /* Size of structure changed */
 rc = VioGetConfig(0, &config, hvio);

==Try It for Yourself!==
Most of the 16-bit text-mode APIs have new 32-bit character mode counterparts. Use the files on the CD-ROM to convert your application's 16-bit OS/2 calls to 32-bit. Let us know what you think - use The Developer Connection section on CompuServe, or use the address listed in this newsletter.

{{IBM-Reprint}}
[[Category:Developer Connection News]]