KbdCharIn

Description

Reads a character data record from the keyboard.

Syntax

#define INCL_KBD
#include <os2.h>

PKBDKEYINFO    CharData;  /* Pointer to character data. */
ULONG          Wait;      /* Wait Flag. */
HKBD           hkbd;      /* Reserved. Must be 0. */
APIRET         rc;        /* Return code. */

rc = KbdCharIn(CharData, Wait, hkbd);

Parameters

CharData (PKBDKEYINFO) - output

Pointer to character data.

A pointer to a KBDKEYINFO structure in which the character data is returned.

Wait (ULONG) - input

Wait Flag.

• 0 IO_WAIT: Wait for a keystroke if one is not available. The keystroke returned is removed from the queue.
• 1 IO_NOWAIT: Return immediately, with or without a keystroke. If a keystroke is returned, remove it from the queue.
• 2 IO_PEEK: Return immediately, with or without a keystroke. Do not remove the keystroke from the queue.
• 3 IO_PEEKWAIT: Wait for a keystroke if one is not available. Return the keystroke but do not remove it from the queue.

hkbd (HKBD) - input

Reserved. Must be 0.

Return Code

rc (APIRET) - returns

KbdCharIn returns one of the following values:

• 0 - NO_ERROR
• 0375 - ERROR_KBD_INVALID_IOWAIT
• 0445 - ERROR_KBD_FOCUS_REQUIRED
• 0447 - ERROR_KBD_KEYBOARD_BUSY
• 0504 - ERROR_KBD_EXTENDED_SG

Remarks

Note: KbdCharIn returns a complete keystroke. This behavior is unlike the OS/2 1.3 version, which returned only a single byte. This affects only double-byte character set (DBCS) characters.

If bit 0 of fbStatus is set, the character returned is either 0 or 0xe0. The Unicode character contains the virtual key.

For valid characters, the character in the current code page is returned, and the Unicode character contains the Unicode encoding of the character.

On an enhanced keyboard, the secondary enter key returns the normal character 0DH and a scan code of E0H.

Extended ASCII codes are identified by bit 1 of the status byte being set to on, and the ASCII character code being either 00H or E0H. Both conditions must be satisfied for the character to be an extended keystroke. For extended ASCII codes, the scan-code byte returned is the second code (extended code). Usually, the extended ASCII code is the scan code of the primary key that was pressed.

A thread in the foreground session that repeatedly polls the keyboard with KbdCharIn (with no wait), can prevent all regular priority-class threads from executing. If polling must be used, and a minimal amount of other processing is being performed, the thread should periodically yield to the CPU by issuing a DosSleep call for an interval of at least 5 milliseconds.