DOS Console I/O

Technical Notes

Overview
Performing Character I/O
Performing String I/O
Manipulating the Input Buffer
Redirection Rules

Overview

This unit consists of functions which get characters and strings from STDIN, put characters and strings to STDOUT, and manipulate the input buffers associated with STDIN. Redirection is supported as well as ctrl-break and ctrl-C checking. These functions provide a low-overhead method for performing keyboard input and screen output in command line oriented programs. Screen oriented programs should use the console I/O functions instead of the functions in this unit.

See Appendices B, C, and D for a complete list of supported keystrokes and key codes.

The functions in this unit ignore DOS errors, even under redirection.

Performing Character I/O

_get_chr: Gets a character from STDIN.
_get_chra: Gets a character from STDIN.
_get_chre: Gets a character from STDIN and echoes it to STDOUT.
_get_chrae: Gets a character from STDIN and echoes it to STDOUT.
_put_beep: Puts a BEL character to STDOUT.
_put_chr: Puts a character to STDOUT.
_put_newline: Puts a carriage return and linefeed to STDOUT.

These functions read characters from STDIN and write characters to STDOUT.

_get_chr and _get_chre read characters from STDIN. Extended characters (F1, F2, etc.) are indicated by a zero return value; the function must be called again to obtain the code for the extended keystroke. Normal (ASCII) characters and ALT-keypad characters are returned on the first call.

The _get_chra and _get_chrae functions are functionally equivalent to _get_chr and _get_chre except that all of the character information is returned in a single call-even for extended characters. _get_chra and _get_chrae return -1 if the keystroke was an extended character and 0 if the keystroke was a normal (ASCII) character or ALT-keypad character. The code for the keystroke is placed in a parameter that is passed on the stack. _get_chr and _get_chra do not echo input characters; _get_chre and _get_chrae echo normal characters to the STDOUT device if they are in the range 0x20 to 0x7E.

_put_chr writes a character to STDOUT. The special characters BEL, BS, TAB, CR, and LF receive special handling by the STDOUT device; all other characters are written to the output device without any special intervention. _put_beep and _put_newline write a BEL and a CR/LF pair to STDOUT, respectively.

Performing String I/O

_get_str: Gets a string from the STDIN device.
_put_str: Puts a string to STDOUT.
_fput_str: Puts a far string to STDOUT.

These functions read strings from STDIN and write strings to STDOUT.

_get_str reads characters from STDIN into an input buffer. Simple editing of the input string may be performed using the backspace key. The system speaker sounds a tone if an attempt is made to read too many keys into the input buffer. Input terminates when a CR is encountered (i.e., when the Enter key is pressed), at which time a CR/LF pair is echoed to STDOUT and the function returns. The resulting string is NULL terminated.

_put_str and _fput_str write an ASCIIZ string to the STDOUT device. All characters except the terminating NULL are written. _fput_str is a far version of _put_str which always accepts a far string pointer in small data models.

Manipulating the Input Buffer

_check_key: Checks STDIN to determine if a keystroke is waiting to be read.
_flush_keys: Flushes pending input from STDIN.

These functions manipulate the input buffer associated with the STDIN device. _check_key checks STDIN to determine if a keystroke is waiting to be read. If STDIN has been redirected from a file, _check_key indicates that a character is ready unless the file pointer is at end-of-file. _flush_keys empties pending characters from the input buffer. If STDIN has been redirected from a file, _flush_keys moves the file pointer to end-of-file (EOF).

Redirection Rules

All of these functions work properly with STDIN and/or STDOUT redirected. If STDIN is redirected from a file, the characters in the file must appear in the same format and order as they would if standard DOS character input functions were used to read the keyboard. Normal characters are represented by their ASCII values; extended characters are represented by a NULL followed by an extended ASCII value.

Caution needs to be exercised when redirecting STDIN. If the last character in the file is a NULL, it will be interpreted as an extended character flag and the input function will wait indefinitely for the second half of the extended character to become available.