ANS FORTH DOCUMENTATION

For TDS2020F compliance with the American National Standard Forth specification X3.215-1994 the following documentation is necessary. See the booklet 'TDS2020F ANS Forth Floating Point' for additional documentation and also TDS2020F LANGUAGE, page 126. Most of these ANS Forth words are present at power-up but some need to be compiled from file #ANS.TDS:

q       All CORE word set

q       All CORE EXTENSION word set

q       All DOUBLE NUMBER word set

q       All DOUBLE NUMBER EXTENSION word set

q       All EXCEPTION word set

q       All STRING word set

q       All FLOATING POINT word set (extra charge)

q       From the FACILITY word set these words:
   FORGET  KEY?   PAGE  MS  TIME&DATE

q       From the PROGRAMMING TOOLS word set these words:
   .S  DUMP   WORDS

q       From the SEARCH ORDER word set these words:
   GET-CURRENT  DEFINITIONS

IMPLEMENTATION DEFINED OPTIONS

Aligned addresses is the set of all even addresses.

Behaviour of EMIT for characters outside the range hex 20 to 7E inclusive is to send the binary value to serial Port 1. The displayed character, if any, will depend on the terminal or emulator connected to it.

Character editing of ACCEPT and EXPECT is to ignore bit 7 of all received characters and replace it with a 0, e.g. hex A1 is treated as 21. Both the backspace character hex 08 and the delete character hex 7F cause the last entered character (if any) to be removed from the accumulated string.

Character set of the system including characters received and sent by KEY and EMIT includes all ASCII characters from hex 00 to FF.

Character-aligned addresses are universal throughout the system.

Character set extensions in definition names are supported. Any ASCII character except hex 00, 08, 0A, 0D & FF can be used.

Conditions under which control characters match a space delimiter are none. For example the tab character hex 09 can not be used in source code.

Control-flow stack is implemented using the data stack.

Conversion of digits larger than 35 is not performed.

Display after input terminates in ACCEPT and EXPECT remains unchanged.

Exception abort sequence (as in ABORT" ) is to perform a carriage return and to continue execution after the overlying CATCH , or to enter the interactive Forth loop QUIT if there is no CATCH .

Input line terminator is the carriage return character hex 0D.

Maximum size of a counted string is 255 characters.

Maximum size of a parsed string is 255 characters.

Maximum size of a definition name is 31 characters.

Maximum string length for ENVIRONMENT? is 31 characters.

Method of selecting user input device is via the user variable 'KEY . This variable contains the execution token of the word KEY appropriate for the selected input device, for instance serial link or keypad. By default the user input device is connected to serial Port 1.

Method of selecting user output device is via the user variable 'EMIT . This variable contains the execution token of the word EMIT appropriate for the selected input device, for instance serial link or LCD. By default the user output device is connected to serial Port 1.

Method of dictionary compilation is, in ascending sequence of addresses:

q       One character whose value is the number of characters in the original name, bit 7 set to 1, bit 6 set to 1 if the definition is immediate and bit 5 set if the definition is not to be found with FIND . The address of this character is called the name field address (nfa).

q       A string with the definition name (may be truncated but at least one character). Bit 7 of the last character is set to a 1.

q       A two character (16-bit) link field containing the name field address of the previous definition in the linked list of definitions.

q       A two character (16-bit) value at the execution token address for this definition. This value is itself an address which is the start of a section of machine code (inner interpreter for this definition).

q       A variable number of two character (16-bit) values representing compiled execution tokens etc. of the words comprising the definition.

The name space described in the first 4 points above, and the code space by the last one, are read-write during development and read-only in a stand-alone system in PROM or protected Flash-EEPROM. The data space available to a program even in a stand-alone system is always read-write RAM memory.

Number of bits in one address unit is 8.

Number representation and arithmetic is two's complement.

Ranges for numbers are: n: -32,768 to +32,767   +n: 0 to +32,767   u: 0 to 65,535   d: -2,147,483,648 to +2,147,483,647   +d: 0 to +2,147,483,647   ud: 0 to 4,294,967,295.

Read-only data space regions are not present, only read-only name and code spaces (if the application is put into a PROM or protected Flash-EEPROM.

Size of buffer at WORD is 34 bytes.

Size of one cell in address units is 2.

Size of one character in address units is 1.

Size of the keyboard terminal input buffer is 84 characters.

Size of the pictured numeric output string buffer is 34 characters.

Size of the scratch area whose address is returned by PAD is 84 characters.

System case-sensitivity characteristics are such that case is always significant in making and finding definition names.

System prompt is the string '<space>ok'.

Type of division rounding for */  */MOD  /  /MOD   MOD is symmetric. The word FM/MOD is provided to allow floored division equivalents.

Value of STATE when true is hex C0.

Values returned after arithmetic overflow should not be used, they will be those calculated using two's complement arithmetic.

Whether the current definition can be found after DOES> : No

Values used in the system by CATCH and THROW are shown under ERROR-HANDLING, page 144.

Duration of a system clock tick is 814ns.

Repeatability to be expected of MS is �45�s (due to timekeeping interrupt) except where the application program introduces its own interrupts.

Ending sequence for input following ;CODE or CODE is either END-CODE or NEXT JMP, . In the case of a subroutine or interrupt starting with CODE the ending is either RTS, or RTE, respectively. See SUBROUTINES & FORTH RE-ENTRY POINTS, page 156 and INTERRUPTS USING ASSEMBLY LANGUAGE, page 166.

Manner of processing input following ;CODE or CODE is described under H8/500 STRUCTURED FORTH ASSEMBLER, page 150.

AMBIGUOUS CONDITIONS

GENERAL

Name is neither a valid definition name nor a valid number during text interpretation: the message UNDEFINED is displayed.

Definition name exceeded the maximum length of 31 allowed: the first 31 characters are used.

Addressing a region not data space will work for read and write during development and for read-only in a stand-alone system where the program is in PROM or protected Flash-EEPROM.

Argument type incompatible with specified input parameter will be accepted and results will be ambiguous. There is no data typing.

Attempting to obtain the execution token of a definition with undefined interpretation semantics (e.g. with FIND or ' ) will be accepted but the result will be meaningless.

Dividing by zero with */  */MOD  /  /MOD  FM/MOD  MOD   SM/REM  UM/MOD  M*/ gives the same result as dividing by 1 and there is no error indication.

Overflow of the return stack may cause a crash causing a THROW to the overlying CATCH with display of the error message WATCHDOG, ADDR ERR or INV INSTN. Alternatively the external watchdog may attempt to restart the program by holding the reset line low for 10�s or it is possible failing all of these protection mechanisms that the processor will hang up.

Overflow of the Data Stack is similar but during interpretation or compilation will give the message FULL STACK and the operation will be terminated.

Insufficient space for loop control parameters causes overflow of the return stack, see above.

Insufficient space in the dictionary gives the warning message 'xx left' where xx is the number of bytes whenever under 118 bytes remain. If fewer than 34 bytes remain the error message DICT FULL is displayed.

Interpreting a word with undefined interpretation semantics gives the error message COMP ONLY.

Modifying the contents of the input buffer will succeed.

Modifying a string literal will only succeed during development, not after a program has been put into PROM or the Flash-EEPROM has been protected.

Overflow of a pictured numeric output string may cause a crash with actions similar to overflow of the return stack.

Parsed string overflow (happens if a string has more than 255 characters) may cause a crash with actions similar to overflow of the return stack.

Producing a result out of range, e.g. multiplication using * , resulting in a value too big for a single cell integer, will cause no error indication but the result should not be used.

Reading from an empty return stack (stack underflow) may cause a crash with actions similar to overflow of the return stack.

Reading from an empty data stack (stack underflow) is similar but during interpretation or compilation will give the message EMPTY STK.

Unexpected end of input buffer resulting in an attempt to use a zero-length string as a name will give the error message NO NAME.

WORD SPECIFIC

>IN greater than size of input buffer will result in interpretation of memory outside the input buffer and may cause a crash with actions similar to overflow of the return stack.

RECURSE appearing after DOES> will function normally.

Argument input source different than current input source for RESTORE-INPUT will usually result in the returned validation flag being true.

Deallocation of data space containing definitions may cause a crash with actions similar to overflow of the return stack.

Data space read/write with incorrect alignment will result in the message ADDR ERR with subsequent actions similar to overflow of the return stack.

Less than u+2 stack items for PICK or ROLL will cause no error indication but the result should not be used.

Loop control parameters not available in +LOOP  I   J  LEAVE  LOOP or UNLOOP may cause a crash similar to overflow of the return stack.

If most recent definition does not have a name when using IMMEDIATE , it will apply to the most recent definition with a name.

If a name not defined by VALUE is used by TO there will be no error indication and the system may cause a crash with actions similar to overflow of the return stack.

Name not found by '   POSTPONE  ['] or [COMPILE] will give the message UNDEFINED.

If parameters are not of the same type in DO  ?DO  WITHIN they will be accepted and will cause no error indication but the result should not be used. There is no data typing.

POSTPONE or [COMPILE] applied to TO will work normally.

A string longer than a counted string returned by WORD will be truncated to 31 characters plus the count byte of 31.

If u is greater than or equal to the number of bits in a cell for RSHIFT or LSHIFT the result will be zero.

If a word not defined via CREATE is used by >BODY or DOES> there will be no error indication but the result should not be used.

Words improperly used outside <# and #> (applies to #  #S  HOLD and SIGN ) may cause a system crash with actions similar to overflow of the return stack.

d outside range of n in D>S will cause no error indication but the result should not be used.

If name cannot be found in FORGET name, the message UNDEFINED is displayed.

If name is not defined via CREATE when using ;CODE , operation of the word being defined will be as if CREATE had been used.

Removing a needed definition with FORGET may cause a system crash with actions similar to overflow of the return stack.

OTHER SYSTEM DOCUMENTATION

There are no non-standard words using PAD .

Operator's terminal facilities are available by default on serial Port 1 by RS232 serial communication using 8 data bits, one start and one stop bit at 9600 baud.

Program data space available is 45,752 address units (bytes).

Return stack space available is 23 cells (16-bit words) plus 2 dedicated to recovery into interactive Forth ( QUIT ) on a crash in the absence of any user application of CATCH .

Stack space available is 109 cells (16-bit words).

System dictionary space required is 16,384 address units (bytes). This is in addition to the 45,752 bytes of program space.