Forth Programmer’s Handbook

acquired.

!If a query returns true (known) and a numerical value, subsequent queries with the same string must also return true and the same numerical value. In other words, added capabilities may not take away or fundamentally alter entitlements already presented to the program.

!Flags indicating presence or absence of optional word sets may change; the flag indicating floored or symmetric division may not change.

Return information about the system software configuration. The character string specified by c-addr u should contain one of the strings from Table 6. If it does not, return false; otherwise, return true with data specified in Table 6 for that string. “environment-query”

3.3 SERIAL I/O

Forth supports a variety of means to perform I/O with a terminal, printer, or other serial-type I/O device. In addition, a simplified method is provided to make use of cursor positioning and other hardware-dependent features, without forcing the use of particular terminal models.

References ACCEPT, Section 3.3.1

TYPE, Section 3.3.2

3.3.1 Terminal Input

The words described in this section handle character input from devices. The input is received from the current input device (e.g., keyboard, serial port). Selection of the current input device is system dependent.

ACCEPT awaits a character string from the terminal or other serial device, given the maximum number of characters and the address where they are to be stored. Input is terminated by a return (0DH). If the terminator is not received before the maximum character count is reached, the excess characters

System Functions 81

Forth Programmer’s Handbook

are discarded. ACCEPT returns the length of the character string that was stored at the given address. For example,

PAD 10 ACCEPT

will await up to ten characters, place them at PAD, and return the actual character count on the stack.

On most systems, incoming characters are checked for the return, which terminates input; and for backspace (08) or DEL (7FH), which cause the character pointer to be “backed up” one and a backspace (or equivalent) to be sent to the terminal. All other characters are echoed to the terminal.

ACCEPT should not be executed if there is no terminal or serial device capable of providing input for the task.

No indication is provided at the terminal that the system is awaiting input as a result of an ACCEPT request. The programmer should indicate this fact through some output message issued prior to the ACCEPT request.

The command KEY awaits one character and leaves it on the stack. It does not edit or echo.

The conventional place to put incoming strings is the input message buffer. At least 80 bytes are available. The system text interpreter ACCEPTs 80 bytes into the input message buffer and performs the necessary housekeeping to process the text. The text interpreter is called by QUIT, which performs a terminal’s basic idle loop behavior.

Get, at most, +n1 characters from the current input device, echo each, and place them in memory beginning at c-addr. The process continues until ACCEPT encounters a carriage return (line terminator). If the line terminator is not received before a count of +n1 is reached, any excess characters are discarded. Return +n2, the actual count of characters received. An example of use is:

PAD 5 ACCEPT <carriage-return> 12345 ok

. 5 ok

82 System Functions

Forth Programmer’s Handbook

ACCEPT is used for most terminal input. On many systems, ACCEPT will back up over previously input characters in response to the backspace or rubout key. When the character pointer points to c-addr, the original address, ACCEPT stops backing up and may thereafter emit a tone for each backspace or rubout it receives.

Check whether a valid keyboard event has been received on the task’s serial device since the last call to ACCEPT, KEY, or EKEY. If so, return true, otherwise return false. The value of the event may be obtained by the next execution of EKEY. After EKEY? returns with a value of true, subsequent executions of EKEY? before executing KEY, KEY?, or EKEY will also return true, because they refer to the same event. “E-key-question”

KEY ( — b ) Core

Accept exactly one byte of data from the input device and place its value on the stack. KEY does not echo. KEY is sometimes used for input prompting and in serial protocols. KEY is also often useful to interactively determine the ASCII numeric value of a character. For example, if you type:

KEY .

…the system will wait for you to press one key and will display its ASCII value.

KEY? ( — flag ) Facility

Check whether a valid character has been received on the current input device since the last call to ACCEPT, KEY, or EKEY. If so, return true, otherwise return false. Invalid (non-character) keyboard events occurring before a valid character are discarded and made unavailable. The value of the character received may be obtained by the next execution of KEY. After KEY? returns with a value of true, subsequent executions of KEY? before executing KEY or EKEY will also return true, without discarding keyboard events. “key-question”

System Functions 83

Forth Programmer’s Handbook

References String operations, Section 2.3

Input number conversion, Section 4.1.4

QUIT, Section 4.1.2

3.3.2 Terminal Output

Forth provides words to output character strings, as well as single characters. The output is sent to the current output device (e.g., display, printer). Selection of the current output device is system dependent.

TYPE outputs a character string to the terminal or other serial device (such as a printer). The character string is emitted exactly as it appears in storage, with parity bits added by the hardware, if required by the terminal in use.

The length of the string, in bytes, must be on top of the stack, with the address of the first byte of the string beneath it.

For example, you could use the following phrase to display thirty-two characters from PAD on the terminal:

Check that it is okay to output a character (e.g., the device is ready, etc.). Return flag, which is false if it is known that the execution of EMIT instead of

84 System Functions