KbdStringIn

Description

Gets a string of keyboard input.

Syntax

#define INCL_KBD
#include <os2.h>

PCH             pch;    /*  Pointer to the character string buffer. */
PSTRINGINBUF    pchin;  /*  Pointer to buffer-length data. */
ULONG           Flag;   /*  Wait flag. */
HKBD            hkbd;   /*  Reserved.  Must be 0. */
APIRET          rc;     /*  Return code. */

rc = KbdStringIn(pch, pchin, Flag, hkbd);

Parameters

pch (PCH) - output

Pointer to the character string buffer.

pchin (PSTRINGINBUF) - in/out

Pointer to buffer-length data.

A pointer to the STRINGINBUF structure containing buffer-length data.

Flag (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

KbdStringIn returns one of the following values:

• 0 NO_ERROR
• 373 ERROR_KBD_PARAMETER
• 375 ERROR_KBD_INVALID_IOWAIT
• 376 ERROR_KBD_INVALID_LENGTH
• 439 ERROR_KBD_INVALID_HANDLE
• 445 ERROR_KBD_FOCUS_REQUIRED
• 504 ERROR_KBD_EXTENDED_SG

Remarks

This function is retained only for compatibility. New code should not use it. KbdGetConsole is the preferred function for new code.

The contents and ending condition depend on the keyboard state:

ASCII

Only valid characters are placed in the input buffer. The function ends when a turnaround character is found or when the buffer is full. The turnaround character is not placed in the buffer.

BINARY

Both valid characters and extended keys are returned. The extended keys are returned as two-byte strings with a leading 0x00 or 0xe0 character. The function ends when the buffer is full.

TERM

Valid characters and escape sequences are placed in the input buffer. The function ends when the turnaround character is found, when an escape sequence is complete, or when the buffer is full. The turnaround character is placed in the buffer.

The maximum buffer length is 255 bytes.

The character strings can be optionally echoed on the display if echo mode is set. When echo is on, each character is echoed as it is read from the keyboard. Echo mode and binary mode are mutually exclusive. See KbdGetStatus and KbdSetStatus for more information.

The default input mode is ASCII. In ASCII mode, 2-byte character codes only return in complete form. An extended ASCII code is returned in a 2-byte string. The first byte is 0DH or E0H and the next byte is an extended code.

In input mode (binary or ASCII), the following returns can be set and retrieved with KbdGetStatus and KbdSetStatus:

• Turnaround Character
• Echo Mode
• Interim Character Flag
• Shift State

The received input length is also used by the KbdStringIn line edit functions for re-displaying and entering a caller-specified string. On the next KbdStringIn call the received input length indicates the length of the input buffer that can be recalled by the user using the line-editing keys. A value of 0 inhibits the line-editing function for the current KbdStringIn request.