3.4.1 Input Number Conversions

All number conversions in Forth are controlled by the user variable
BASE. The host system's BASE controls all input number conversions on
the host; there is also a BASE (USERVAR 0) in the VM that controls
number conversions performed by the target system. The words in this
section are used both on the host and in target programs to control
BASE. In each case, the requested mode will remain in effect until
explicitly changed.

In addition, OTA input number conversion may be directed to convert a
particular number in a particular base, specified by a prefix character
from Table 9. Following such a conversion, BASE remains unchanged from
its prior value. If the number is to be negative, the minus sign must
follow the prefix and precede the most significant digit. Table 9:
Number conversion prefixes

Prefix  Conversion base     Example
%       Binary              %10101010
@       Octal               @177
#       Decimal             #-13579
$       Hex                 $FE00


INCLUDE H,I

( i*x "<spaces>name" - j*x )

Open the file name and make it the input source. Other stack effects are
due to the words included.

Save the input source specification. Repeat until end of file: read a
line from the file, fill the input buffer from the contents of that
line, and begin interpretation from the start of the input buffer. When
the end of the file is reached, close the file and restore the input
source specification to its saved value.

An ambiguous condition exists if the named file cannot be opened, if an
I/O exception occurs reading the file, or if an I/O exception occurs
while closing the file. When an ambiguous condition exists, the status
(open or closed) of any files that were being interpreted is
implementation-defined.

[DEFINED] bracket-defined H,C,I

( "<spaces>name" - flag )

Find the target word name. If the word is not found, return false flag.
If the word is found, return true flag.

[UNDEFINED] bracket-undefined H,C,I

( "<spaces>name" - flag )

Find the target word name. If the word is found, return false flag. If
the word is not found, return true flag.


BINARY H,T (Sequence)

Interpreting: ( - )

Set the number conversion base to 2 (binary). Used for controlling BASE
on the host during compilation.

Run-time: ( - )

Set the number conversion base in the target to 2 (binary). The sequence
may be implemented as LIT2 LIT0 USERVAR STORE.


," comma-quote H,I

( "ccc<quote>" - )

Parse ccc delimited by " (double-quote). Compile a counted ASCII string
containing ccc in initialised data space.

BUFFER: buffer-colon I ELITU <+addr>

( len "<spaces>name" - )

Parse name. Create a definition for name containing a pointer to its
associated data field in uninitialised data space. Allot len bytes of
uninitialised data space in name's data field.

name Execution:( - addr )

Return addr, the address of name's data field. For buffers defined in
token programs, the address is aligned, regardless of len. For buffers
defined in virtual machine implementations, the address is aligned only
if len is aligned (multiple of four). If the address is aligned, the
space between this addr and any previously allocated buffer is not
accessible.

USER H,I LIT <num> USERVAR

( num "<spaces>name" - )

Skip leading space delimiters. Parse name delimited by a space. Create a
definition for name whose token representation selects task-specific
cell num (values 0-15). An ambiguous condition exists if num is not
within the range 0-15. name is referred to as a "user variable" (see
Volume 1 of this specification).

name Execution:( - a-addr )

Return a-addr, the address of the cell in data space reserved by USER
when it defined name.

-ROT minus-rote H,T MINUSROT

( x1 x2 x3 - x3 x1 x2 )

Place the top stack item under the next two.

C+! c-plus-store H,T (Sequence)

( num c-addr - )

Add num to the byte at c-addr. The sequence may be implemented as:
DUP CFETCH ROT ADD SWAP CSTORE

UMOD u-mod H,T MODU

( u1 u2 - u3 )

Divide u1 by u2 , giving the single-cell remainder u3 .

M/MOD m-slash-mod H,T MSLMOD

( d num1 - num2 num3 )

Divide d by num1 , giving the single-cell quotient num3 and remainder
num2 . Identical to SM/REM, but included here because this name is in
common usage.

NOT H,T SETEQ

( x - flag )

Return true flag if and only if x is equal to zero. NOT is a synonym for
0= (defined for readability purposes), and is used to invert a logical
condition.

WIDEN F,T WIDEN

( char - num )

Sign-extend char from an 8-bit value to a 32-bit value, by propagating
bit 7 of char into bits 8-31.

0<= zero-less-or-equal H,T SETLE

( num - flag )

Return true flag if and only if num is less than, or equal to, zero.

0>= zero-greater-or-equal H,T SETGE

( num - flag )

Return true flag if and only if num is greater than, or equal to, zero.

U<= u-less-than-or-equal H,T CMPLEU

( u1 u2 - flag )

Return true flag if and only if u1 is less than, or equal to, u2 .

U<= u-less-than-or-equal H,T CMPLEU

( u1 u2 - flag )

Return true flag if and only if u1 is less than, or equal to, u2 .

-ZEROS minus-zeros T MINUSZEROS

( c-addr len1 - c-addr len2 )

Eliminate trailing nulls. If len1 is greater than zero, len2 is equal to
len1 less the number of binary zero (null) bytes at the end of the
string specified by c-addr len1 . If len1 is zero, or if the entire
string consists of nulls, len2 is zero.

+STRING plus-string T PLUSSTRING

( c-addr1 len1 c-addr2 len2 - c-addr2 len3 )

Append the string at c-addr1 , for len1 bytes, to the end of the string
at c-addr2 , for len2 bytes. Return the beginning of the destination
string (c-addr2 ) and the sum of the two lengths (len3 ). It is the
programmer's responsibility to ensure that there is room at the end of
the destination string to hold both strings.

C+STRING c-plus-string T (Sequence)

( char c-addr len - c-addr len+1 )

Append char to the string c-addr len.
The sequence may be implemented as:
TWODUP TWOTOR ADD CSTORE TWORFROM ADDLIT1

HEX" hex-quote I,C,H (Sequence)

Interpretation: ( "hex-digits<quote>" - c-addr len )

Parse hex-digits, delimited by " (double-quote). Store the resulting
binary string c-addr len at a temporary location. The maximum length of
the temporary buffer is implementation dependent, but shall be large
enough to store at least 32 characters of input. Subsequent uses of S"
or HEX" may overwrite this temporary buffer.

Compilation: ( "hex-digits<quote>" - )

Parse hex-digits, delimited by " (double-quote). Assemble a binary
string representing the hex-digits, ignoring any spaces. An abort will
occur if a character is encountered that is not a space or a valid hex
digit. If the result is an odd number of nibbles, a zero nibble shall be
appended to the string. Append the run-time semantics given below to the
current definition.

Run-time: ( - c-addr len )

Return c-addr and len, describing a binary string assembled from the
characters in hex-digits. Program validation will ensure that the
returned string is not altered subsequently.

The sequence may be implemented as ELITD <+addr> SLIT <u>.

SCAN H,T SCAN

( c-addr1 len1 char - c-addr2 len2 )

Parse the ASCII string at c-addr1 , for len1 bytes, for bytes containing
char. c-addr2 is the address of the byte where char is found, or is the
end of the string (i.e., effectively discarding any string contents
before char). len2 is the length, in characters, of the remaining string
at c-addr2 , and will be zero if char was not found.

SKIP H,T SKIP

( c-addr1 len1 char - c-addr2 len2 )

Parse the ASCII string at c-addr1 , for len1 bytes, skipping bytes that
contain char. c-addr2 is the address of the first byte that differs from
char, or is the end of the string (i.e., effectively discarding any
string contents before char). len2 is the length, in characters, of the
remaining string at c-addr2 , and will be zero if the string was
completely filled with char.

?THROW question-throw T QTHROW

( k*x num1 num2 - k*x | i*x num2 )

If num1 is non-zero, THROW with value num2 . If num1 is zero, discard
num1 and num2 .

4.8 Date, Time, and Timing Services

The words in this section provide access to the Virtual Machine's
internal clock and calendar.

GET-MSECS get-m-secs T GETMS

( - u )

Return current system free-running milliseconds timer value. The timer
value wraps from 2 32 -1 to zero.

MS m-s F,H,T MS

( u - )

Wait for at least u milliseconds, but not more than u plus twice the
timer resolution. In systems that have a multi-tasking operating
system, u = 0 may cause a scheduling operation; whereas, in other
systems, an immediate return shall be performed.

SET-TIME&DATE set-time-and-date F,H,T SETTIME

( u1 u2 u3 u4 u5 u6 - )

Set the current time and date. u1 is the second {0...59}, u2 is the
minute {0...59}, u3 is the hour {0...23}, u4 is the day {1...31}, u5 is
the month {1...12}, and u6 is the year {0...9999}. Some terminals may
not be able to support this function. On these terminals, an
UNSUPPORTED-OPERATION exception may be thrown.

TIME&DATE time-and-date F,H,T GETTIME

( - u1 u2 u3 u4 u5 u6 )

Return the current time and date. u1 is the second {0...59}, u2 is the
minute {0...59}, u3 is the hour {0...23}, u4 is the day {1...31}, u5 is
the month {1...12}, and u6 is the year {0...9999}.

4.19 Operating System Interface

OSCALL o-s-call T OSCALL

( a-addr num fn - )

Call an operating system function fn with num cell-sized arguments in
the array at a-addr. Individual functions are terminal dependent and are
defined in Appendix D to Volume 1 of this specification. Exception
UNSUPPORTED-OPERATION shall be thrown if a particular function is not
supported by the Virtual Machine.

SETCALLBACK T SETCALLBACK

( xp - )

Announce xp as an OTA routine that may be called by the underlying
operating system.

Note that this functionnality is implementation dependent, and is
provided so that terminal specific programs (TRS) written using OTA
tokens can provide a single callback routine for the operating system.

4.20 Miscellaneous

BOUNDS H,T (Sequence)

( c-addr1 len - c-addr2 c-addr1 )

Given the address and length of a string or array, return suitable
parameters for a DO or ?DO loop (see Section 3.9, "Control Structures")
to process it. The sequence may be implemented as OVER ADD SWAP.

GOTO go-to T IJMP

( xp - )

Branch unconditionally to the definition whose xp is given.