Many of the OS/2 kernel functions for keyboard input will seem very familiar, though some new facilities have been added. The Presentation Manager keyboard and mouse inputs are a new story.
From the viewpoint of an application program, the keyboard is not a particularly complex device. The keyboard simply generates a stream of codes that the operating system stores in a circular buffer and then passes on to the program. Consequently, the part of the operating system's application program interface (API) devoted to the keyboard is usually simple and straight-forward.
The OS/2 kernel is no exception to this rule. If you've worked with the keyboard in MS-DOS and with the PC BIOS, you'll find that the OS/2 keyboard interface are quite similar.
Under MS-DOS a program can obtain keyboard input or clear the keyboard buffer through several low-number MS-DOS functions calls (01h, 06h, 07h, 08h, 0Ah, 0Bh, and 0Ch). These calls date back to DOS 1.0 and actually originated in CP/M. DOS supports reading standard input through function call 3Fh ("Read from a file or device"). Standard input is normally keyboard input, but standard input can also be redirected so it comes from a file or from another program through a pipe.
Many application programs that run under DOS obtain keyboard input through Interrupt 16h, which is part of the PC BIOS. Interrupt 16h has three function calls that let a program read the next key from the buffer, peek at the key without removing it from the buffer, and obtain the state of the shift and the toggle keys on the keyboard. RAM-resident popups (and some application programs), on the other hand, obtain keyboard information directly from the hardware. These programs intercept interrupt 09h and access the keyboard I/O ports.
OS/2 has facilities that duplicate and improve upon the functionality of all these DOS and BIOS keyboard functions. One improvement I'm sure will be appreciated is in the size of the keyboard buffer. The PC BIOS has a 15- key buffer; under OS/2 the buffer is expanded to 61 keys.
READING STANDARD INPUT An OS/2 program can read standard input using the DosRead function. In C, a call to DosRead looks like this:
DosRead (0, &Buffer, BufferLen, &BytesRead);
The first parameter of 0 means to read standard input, which is normally the keyboard. The function reads up to BufferLen bytes into the area of memory pointed to by the Buffer address. The last parameter is a pointer to a variable that receives the number of bytes actually read by the function.
In general, however, DosRead is not a good function for simply obtaining keyboard information. It is most valuable in programs designed to work with redirected standard input, such as the PAGE program presented later in this column.
READING KEYBOARD INPUT The OS/2 functions devoted to the keyboard all begin with the letters Kbd. The most important keyboard input function is KbdCharIn:
KbdCharIn (&KeyData, NoWaitFlag, 0) ;
This function obtains the next key from the keyboard buffer. The function is roughly equivalent to a BIOS interrupt 16h call with AH equal to 0.
The first parameter to KbdCharIn is a pointer to a structure of type KeyData. For C programmers, this structure is defined in the SUBCALLS.H header file included with the June, 1987 release of the OS/2 Software Development Kit. (The names and contents of these header files may be different in the OS/2 Software Development Kit expected out in 1988.)
The KeyData structure has six fields that OS/2 uses to return keyboard information to the program. These fields are:
Field Data Type
----- ---------
char_code unsigned char (1 byte)
scan_code unsigned char (1 byte)
status unsigned char (1 byte)
nls_shift unsigned char (1 byte)
shift_state unsigned int (2 bytes)
time unsigned long (4 bytes)
The char_code and scan_code fields are equivalent to the two codes returned in registers AL and AH when a DOS program calls interrupt 16h with AH equal to 0. The char_code field is usually the ASCII character code of the key pressed and the scan_code field is the hardware scan code. However, if the char_code field is 00h, then the key is a non-character key, such as a function key or a cursor movement key. In that case, the scan_code field contains the extended keyboard code. These extended codes are the same as those used by the PC BIOS under DOS.
The status and nls_shift fields are used for supporting double-byte character sets for some foreign-language keyboards. ("NLS" stands for "national language support.") These two fields are not yet documented well enough to make head or tail of how they work.
The 16-bit shift_state field provides the state of all the keyboard shift and toggle keys at the time the key was pressed. The definition of the shift_state bits is shown in Figure 1.
There seems to be a little confusion about the time field in the KeyData structure. The pre-release documentation accompanying the OS/2 Software Development Kit indicates that the four bytes give the time in terms of an hour, minute, second, and hundredths of a second. However, under the beta version of the OS/2 Kernel, the time field reports an elapsed time in milliseconds between the time the system was booted and the time the key was pressed.
A program can use the time field to determine how long the keystroke has been waiting in the keyboard buffer. The current elapsed time (measured from the system boot) is stored in the "global information segment," the address of which is available from the DosGetInfoSeg function.
The second parameter to KbdCharIn is called the "no-wait flag." Normally, the KbdCharIn function waits for a keystroke if the keyboard buffer is currently empty. The function does not return control to the program unless it returns the next key. However, if you set the no-wait flag to 1, then KbdCharIn returns immediately even if the keyboard buffer is empty. If both the char_code and scan_code fields are set to 0, then no keystroke was available from the buffer. This parameter has important implications for multitasking, as I'll discuss later in this column.
The last parameter to KbdCharIn is a "keyboard handle." Under the OS/2 Kernel, this must be set to 0 .
Like the PC BIOS interrupt 16h, KbdCharIn returns only key presses, not key releases. The key is not echoed to the screen. The toggle keys and shift keys do not generate key codes that are stored in the buffer. Instead, you obtain the current status of these keys from the shift_state field of the KeyData structure. The Insert key is an exception: it generates an extended keyboard code and affects the shift_state word.
OTHER KEYBOARD FUNCTIONS If a program wants to look at the next keystroke in the keyboard buffer without removing it, the KbdPeek function can be used instead of KbdCharIn:
KbdPeek (&KeyData, 0) ;
The char_code and scan_code fields of the KeyData structure are set to 0 if no key is waiting in the buffer. This function replaces the BIOS interrupt 16h call with AH equal to 1.
A program can clear the keyboard buffer by calling:
KbdFlushBuffer (0) ;
The single parameter is the keyboard handle, which must be set to 0.
A program can obtain the state of the toggle and shift keys by a call to KbdGetStatus. The state of the toggle keys can be changed using KbdSetStatus. (Under DOS, changing the state of the toggle keys requires the program to access the BIOS data area directly.)
The KbdStringIn function is useful for obtaining a string of characters from the keyboard:
This function replaces the DOS function call 0Ah. The second parameter is a pointer to a structure of type KbdStringInLength. It contains an input length on entry to the function, and it contains the number of bytes entered by the user on return to the program. During the KbdStringIn call the normal DOS editing keys (F3 and so forth) can be used to edit text already in the buffer.
Like DOS, OS/2 allows the redefinition of keys using ANSI control sequences. These keyboard redefinitions are recognized only by the DosRead and KbdStringIn functions. But don't assume that KbdStringIn reads standard input. KbdStringIn always reads the keyboard regardless of the redirection of standard input.
In one sense, DosRead and KbdStringIn play a unique role in keyboard handling. It is analogous to the role of DosWrite and VioWrtTTY in screen output. This is summarized in Figure 2.
THE PAGE PROGRAM Let's now look at a simple example of DosRead and KbdCharIn in a program that uses both functions.
The PAGE.C program shown in Figure 3 is similar to the DOS (and OS/2) MORE program. It displays standard input one screenful at a time. However, unlike the teletype output of MORE, PAGE uses the OS/2 Vio functions to pop each page to the full screen.
Using the C compiler included with the beta version of the OS/2 Software Development Kit, you can compile and link PAGE with the following command:
CL -G2 -Zp PAGE.C
You can use PAGE to look at the contents of a large file thus:
PAGE <filename
Or you can display standard output originating from another program through a pipe. For example, if you have a long directory list, you can look at it a screen at a time with
DIR | PAGE
PAGE is easy to use. Pressing any key goes to the next page. The Escape key exits.
PAGE first determines whether standard input is coming from a source other than the keyboard by calling DosQHandType ("query handle type"). If standard input is coming from the keyboard, PAGE exits with an error message. Otherwise, the program saves the initial contents of the screen with VioReadCellStr and later restores it with VioWrtCellStr. PAGE writes to the screen using the OS/2 virtual screen buffer. The VioGetBuf function obtains a selector (segment address) for this buffer. The program then stores its screen output in the buffer and updates the screen through a call to VioShowBuf.
PAGE reads standard input using DosRead with a first parameter of 0. PAGE reads the keyboard with KbdCharIn. The keyboard handling is very simple. When KbdCharIn returns with the next key, PAGE checks only if the char_code field of the KeyData structure is «PT3»\x1B«PT2» (the Escape key). This causes PAGE to terminate. PAGE also terminates when it runs out of standard input to display. This is indicated by a zero value for BytesRead following the call to DosRead.
OS/2 PIPES Piping of standard output from one program to standard input of another program is significantly different in OS/2. In DOS, if you run the command
DIR | MORE
DOS first creates a temporary file for the output from the DIR command. Standard output from DIR is redirected to this file. When the DIR command is finished, DOS closes the file. DOS then runs the MORE program. The standard input to MORE is redirected from the file. When MORE is finished, DOS deletes the temporary file.
Under OS/2, pipes are memory blocks rather than files. As you would expect, this speeds up piping considerably.
Even more important, the programs on each side of the pipe run simultaneously. While the DIR command is writing its standard output to the pipe, MORE (or PAGE) can read its standard input from the pipe. This means that PAGE does not have to wait for the DIR command (or whatever) to finish before it displays the first screenful of standard input to the screen.
You'll notice that near the end of PAGE.C (just before the program terminates) PAGE continues reading standard input using DosRead until the BytesRead variable is zero. An earlier version of PAGE did not have this code. With this earlier version if I executed:
DIR | PAGE
for a long directory and ended PAGE by pressing the Escape key, the DIR command would give me an error message that the disk was full. What DIR really meant was that the pipe was broken because PAGE stopped reading DIR's output. Adding the two lines of code at the end of PAGE.C fixed this problem.
KEYSTROKES AND MULTITASKING
Now for a lecture.
There's been a lot of disinformation about OS/2 circulated in recent months. Most of this stuff apparently orginates with the CEOs of companies who compete with Microsoft in the applications and languages market. Lazy press people who have never run OS/2 and don't know any better pass these falsehoods on to the public.
One quite persistent piece of disinformation concerns multitasking. It is said that if you have two programs running under OS/2, they'll both run at half speed. After all, OS/2 must continually switch between the two programs, so each program gets only half the microprocessor time it got under DOS. Seems obvious, doesn't it?
Well, no.
It is obvious only if both programs are actually doing something at the same time, such as recalculating a spreadsheet, running a spelling check, or sorting a database. However, most programs spend much of their time doing nothing except waiting for the next keystroke from the user.
If an OS/2 program is running in a background screen group and is waiting for a keystroke with a call to KbdCharIn or KbdStringIn, then that program implicitly forfeits its normal time slice. Because the program is not going to get a keystroke until the screen group is moved to the foreground there's no reason for the program to eat up valuable time doing nothing. OS/2 knows this and functions accordingly. OS/2 is simply not as stupid as some people think. I wouldn't be wasting my time learning about OS/2 and writing about OS/2 if it were.
Anybody who's spent time with OS/2 knows this: You can have a bunch of screen groups active, each running a program, and if each of these programs is waiting for a keystroke, there is no significant speed degradation.
However, in order for OS/2 to work this way, it is important that application programs call KbdCharIn with the no-wait flag set to 0. This allows OS/2 to recognize that it should not give the program a normal time slice if the keyboard buffer is empty. If a program instead sits in a loop and continually calls KbdCharIn with the no-wait flag parameter to 1, then the program will indeed get a normal time slice and it will slow down the whole system.
But why would a programmer want to set the no-wait flag to 1 anyway? Well, suppose the program used both keyboard input and mouse input. An OS/2 program obtains mouse events (movement of the mouse or mouse button depressions) by calling the MouReadEventQue function. This function has its own no-wait flag parameter. Setting this flag to 1 causes MouReadEventQue to return control to the program even if the mouse queue is empty.
One way to handle both keyboard and mouse input is to alternate between reading the keyboard with KbdCharIn and reading the mouse queue with MouReadEventQue. The no-wait flag in both functions is set to 1 so the program won't miss mouse input while it's hung up in a KbdCharIn call and won't miss keyboard input while waiting for MouReadEventQue to return.
While such a method sounds reasonable, it's wrong, wrong, wrong! A program that does this will slow down the whole system even when the program is running in a background screen group and cannot possibly get keyboard or mouse input. And I promise you that any commercial OS/2 program we see that works in this way will be classified personally by me as an "Editor's Reject."
But now we apparently have a problem. What recourse does a program have when it must read both keyboard and mouse input?
Simple. The program reads the keyboard and mouse from two separate threads of execution. These two threads run simultaneously. In both the KbdCharIn and MouReadEventQue calls, the no-wait parameter is set to 0. This ensures that both threads give up their time slices when the program is running in a background screen group.
THE PRESENTATION MANAGER The various Kbd functions are designed for programs written for the OS/2 Kernel. They are not used by programs written for the OS/2 Presentation Manager.
Instead, Presentation Manager programs receive keyboard input in the form of "messages." These messages are stored in the program's message queue along with other messages such as those relating to mouse input. Under the Presentation Manager, a program does not need to use separate threads of execution for processing keyboard and mouse input because both forms of input are stored in the same queue.
A Presentation Manager program obtains more information about keystrokes than does an OS/2 Kernel program. In particular, every keyboard event (key releases as well as depressions) is reported to the program. Presentation Manager programs also obtain key combinations that are ignored by the OS/2 Kernel, such as the Ctrl key in combination with the period.
COMING UP: KEYBOARD MONITORS So far we've seen how OS/2 duplicates the functionality of the DOS interrupt 21h and BIOS interrupt 16h keyboard functions. However, we haven't seen anything yet that lets a program intercept keyboard information in the same way that a DOS RAM-Resident programs does with interrupt 09h.
Is such a thing possible under OS/2? It sure is. In fact, unlike DOS, OS/2 has a documented, built-in facility that lets a program intercept and (optionally) alter keyboard input before it gets to other programs.
This is certainly an important topic, which is why I'll devote all of next issue's Environments columns to the subject of "keyboard monitors."
FIGURES:
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|15|14|13|12|11|10| 9| 8| 7| 6| 5| 4| 3| 2| 1| 0|
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| | | | | | | | | | | | | | | |
| | | | | | | | | | | | | | | +--- Right SHIFT down
| | | | | | | | | | | | | | |
| | | | | | | | | | | | | | +------ Left SHIFT down
| | | | | | | | | | | | | |
| | | | | | | | | | | | | +--------- Either CTRL down
| | | | | | | | | | | | |
| | | | | | | | | | | | +------------ Either CTRL down
