Z88 CamelForth - ANS Forth Compliance Documentation =================================================== Z88 CamelForth is an ANS Forth Standard System: * providing .( .R 0<> 0> 2>R 2R> 2R@ :NONAME <> ?DO AGAIN CASE COMPILE, ENDCASE ENDOF ERASE FALSE HEX NIP OF PAD PARSE REFILL RESTORE-INPUT SAVE-INPUT SOURCE-ID TIB TO TRUE TUCK U.R U> UNUSED VALUE WITHIN \ from the Core Extensions word set * providing the Block word set * providing the Block Extensions word set * providing D+ D- DABS DNEGATE M+ from the Double-Number word set * providing DU< from the Double-Number Extensions word set * providing the Exception word set * providing the Exception Extensions word set * providing the Facility word set * providing the Facility Extensions word set * providing the File-Access word set * providing the File-Access Extensions word set * providing .S ? WORDS from the Programming Tools word set * providing BYE CODE DUMP EDITOR from the Programming Tools Extensions word set * providing the Search-Order word set * providing the Search-Order Extensions word set * providing the String word set * providing the String Extensions word set Optionally-loaded components ============================ A few of the words mentioned or implied above are not present in the system as initially started, since there was not enough space to include everything in the 16K segment used for Z88 CamelForth. These can be loaded at any point using the additional source files provided with the system, with the phrase: S" filename.fth" INCLUDED * Environmental Queries: ENVIRONMENT.FTH -------------------------------------- Environmental queries will always produce FALSE on the standard system, until this file is loaded which provides the strings required for the queries to provide meaningful values. * Line Editor: LINEEDIT.FTH ------------------------- The optional line editor provides: LIST SCR from the Block Extensions word set EDITOR from the Programming Tools Extensions word set It contains all the commands of the classic fig-style line editor, with several additional features. * Programming Tools: DUMP.FTH --------------------------- This file provides: DUMP from the Programming Tools Extensions word set Implementation-defined options: CORE and CORE EXTENSION word sets ================================================================= * Aligned address requirements ---------------------------- There are no special aligned address requirements, and consequently all addresses are treated as aligned. * Behaviour of EMIT for non-graphics characters --------------------------------------------- Unless redirected by the user, EMIT outputs characters via the standard OZ call OS_OUT and therefore behaviour is as documented in the Z88 Manual and the Z88 Developers' Notes. Since OZ can redirect the standard output device, the behaviour depends on the active output device(s), usually the screen. * Character editing of ACCEPT --------------------------- [DEL] Delete character to left of cursor [LEFT] Move cursor left [RIGHT] Move cursor right <>[LEFT] Move cursor to start of line <>[RIGHT] Move cursor to end of line [CAPS] Switch caps lock mode [ENTER] Terminate input These editing facilities can be extended by handling additional codes with the deferred word (ACC_EVT). * Character set ------------- The standard Z88 8-bit character set as described in appendix D of the Z88 Manual (and in more detail in the Z88 Developers' Notes). * Character-aligned address requirements -------------------------------------- There are no special character-aligned address requirements, and consequently all character addresses are treated as aligned. * Character-set-extensions matching characteristics ------------------------------------------------- Any characters except control characters may be used in a definition name. Matching is case-sensitive. * Conditions under which control characters match a space delimiter ----------------------------------------------------------------- Control characters match space delimiters if a space delimiter is used with WORD or PARSE. As the text interpreter uses WORD, control characters also match space delimiters during parsing of any input source. * Control-flow stack format ------------------------- The control-flow stack is not seperate, but implemented using the data stack. * Conversion of digits larger than 35 ----------------------------------- Digits larger than 35 are represented by ASCII characters 91 decimal and above in strict numerical order, so for digits 36 to 72, the following characters are used: [\]^_`abcdefghijklmnopqrstuvwxyz{|}~ ASCII code 127 cannot be entered from the keyboard, so the highest usable base is 73. Also note that lower-case characters always represent digits 42 to 67, and never digits 10 to 35. * Display after input terminates in ACCEPT ---------------------------------------- On termination of accept, input remains on the screen as entered with the cursor position at the following character. * Exception abort sequence of ABORT" ---------------------------------- The address of the counted error string is stored in the user variable ABORT"C and exception -2 is THROWn. * Input line terminator --------------------- ASCII 13 (CR) is used to terminate input, and is produced by pressing ENTER or <>M. * Maximum size of a counted string -------------------------------- 255 characters * Maximum size of a parsed string ------------------------------- 255 characters * Maximum size of a definition name --------------------------------- 127 characters * Maximum string length for ENVIRONMENT? -------------------------------------- 255 characters * Method of selecting user input device ------------------------------------- The user input device can be altered either by revectoring the word KEY to a user-defined word, or by altering OZ's standard input device using a suitable CLI sequence with the *CLI word (see Filer Reference in the Z88 Manual for details of the CLI). Note that revectoring KEY has no effect on lower-level words such as KEY? and EKEY, or ACCEPT. * Method of selecting user output device -------------------------------------- The user output device can be altered either by revectoring the words EMIT and TYPE to user-defined words, or by altering OZ's standard output device using special keystrokes, or a suitable CLI sequence with the *CLI word (see Filer Reference in the Z88 Manual for details of these). * Methods of dictionary compilation --------------------------------- Definitions are compiled in two parts: the header, which is compiled into namespace, and the body, which is compiled into dataspace. Namespace and dataspace are normally both set to RAM, but may be independently altered using the words RAM ROM1 ROM2 and NS. The following defining words require namespace and dataspace to be the same region, and will cause exception -4093 if this is not the case: : :NONAME CODE CONSTANT FCODE PKGCALL VOCABULARY The following defining words may have separate namespace and dataspace: CREATE DEFER VALUE The following defining words are special cases: POOL Requires namespace and dataspace to be the same. Additionally, some uninitialised space is always alloted in the RAM region. VARIABLE Namespace may be in any region, but the body is always alloted in the RAM region, regardless of the current dataspace setting. TASK: Namespace may be in any region, but the body is always alloted in the RAM region, regardless of the current dataspace setting. Codespace as defined in the ANS Standard is considered as part of dataspace. * Number of bits in one address unit ---------------------------------- 8 bits * Number representation and arithmetic ------------------------------------ Binary two's-complement * Ranges for n, +n, u, d, +d, ud ------------------------------ n { -32768..+32767 } +n { 0..32767 } u { 0..65535 } d { -2147483648..+2147483647 } +d { 0..2147483647 } ud { 0..4294967295 } * Read-only data space regions ---------------------------- The following regions are defined: RAM $2400..$BFFF read-write ROM1 $4000..$7FFF read-only ROM2 $8000..$BFFF read-only The regions designated as read-only are usually read-write, but are best used to compile ROMmable applications, and will hence become read-only when a ROMmed application has been generated. * Size of buffer at WORD ---------------------- This is equivalent to the total unused space in the current region, and is therefore the value returned by UNUSED in address units. * Size of one cell in address units --------------------------------- 2 address units * Size of one character in address units -------------------------------------- 1 address unit * Size of keyboard terminal input buffer -------------------------------------- 80 characters * Size of pictured numeric output string buffer --------------------------------------------- 36 characters * Size of scratch area whose address is returned by PAD ----------------------------------------------------- 84 characters * System case-sensitivity characteristics --------------------------------------- The system is case-sensitive for dictionary searches, string comparisons and numeric input. Filenames are not case-sensitive, and follow the normal OZ rules for filenames (including wildcard selection). * System prompt ------------- Lowercase " ok" during interpretation. No prompt during compilation. * Type of division rounding ------------------------- Floored * Values of STATE when true ------------------------- STATE may have the following values: 0 interpretation mode 1 standard compilation mode Words using STATE and acting on it to compile items into the dictionary should be aware that in compilation mode, different actions should be taken if "fast code" compilation is on (this can be determined with FAST? which returns 0 for normal compilation mode and 1 for fast code mode). The standard words COMPILE, and LITERAL take account of this mode, and so words using these to perform their compilation actions will be fine. * Values returned after arithmetic overflow ----------------------------------------- Arithmetic is performed in two's-complement, and thus modulo 2^16 for single precision arithmetic, and modulo 2^32 for double precision arithmetic. Division by zero returns a value of -2. * Whether the current definition can be found after DOES> ------------------------------------------------------- No Ambiguous conditions: CORE and CORE EXTENSION word sets ======================================================= * A name is neither a valid definition name or number during interpretation ------------------------------------------------------------------------- Exception -13 is THROWn. * A definition name exceeded the maximum length allowed ----------------------------------------------------- Ignore and continue: the definition will be incorrectly entered into the dictionary and will cause a crash if execution is attempted. * Addressing a region not listed as dataspace ------------------------------------------- Ignore and continue: a crash may occur if system information is overwritten. * Argument type incompatible with specified input parameter --------------------------------------------------------- Ignore and continue: unexpected results will occur, including possible exceptions from OZ routines. * Attempting to obtain the execution token of a definition with undefined interpretation semantics ----------------------------------------------------------------------- Ignore and continue: the xt may be successfully compiled with COMPILE, but attempts to execute it will cause unexpected results including possible crashes. * Dividing by zero ---------------- Ignore and continue: an erroneous result will be returned. * Insufficient data-stack space or return-stack space (stack overflow) -------------------------------------------------------------------- Ignore and continue: a crash may occur. * Insufficient space for loop-control parameters ---------------------------------------------- Ignore and continue: a crash may occur. * Insufficient space in the dictionary ------------------------------------ Ignore and continue: if following regions are in ROM, compilation will have no further effect; if in RAM, other information will be overwritten, possibly causing a crash. * Interpreting a word with undefined interpretation semantics ----------------------------------------------------------- Ignore and continue: unexpected results will occur, including a possible crash. * Modifying the results of the input buffer or a string literal ------------------------------------------------------------- Ignore and continue: modification will be successful unless the string literal is in ROM. * Overflow of a pictured numeric output string -------------------------------------------- Ignore and continue: the file line input area will be overwritten which may cause problems if interpretation of a file is in progress. * Parsed string overflow ---------------------- Ignore and continue: no overflow can occur with PARSE, but WORD may overflow with the same result as overflowing the dictionary. * Producing a result out of range ------------------------------- Ignore and continue: results will be returned modulo 2^16 for single precision arithmetic and modulo 2^32 for double precision arithmetic. * Reading from an empty data stack or return stack (stack underflow) ------------------------------------------------------------------ Ignore and continue: a crash may occur. * Unexpected end of input buffer, resulting in attempt to use zero-length string as a name ----------------------------------------------------------------------- Ignore and continue: the zero-length name will be entered in the dictionary but will not be findable. * >IN greater than size of input buffer ------------------------------------- Ignore and continue: parsing will erroneously continue beyond the end of the input buffer. * RECURSE appears after DOES> --------------------------- The execution token of the defining word currently being defined will be compiled into the action of the words it defines. * Argument input source different than current input source for RESTORE-INPUT --------------------------------------------------------------------------- The input source is correctly restored. * Data space containing definitions is de-allocated ------------------------------------------------- This is not possible, so no ambiguous condition exists. * Data space read/write with incorrect alignment ---------------------------------------------- All alignments are valid, so no ambiguous condition exists. * Data-space pointer not properly aligned --------------------------------------- All alignments are valid, so no ambiguous condition exists. * Less than u+2 stack items for PICK or ROLL ------------------------------------------ Neither PICK or ROLL are implemented. * Loop-control parameters not available ------------------------------------- Ignore and continue: a crash may occur. * Most recent definition does not have a name (IMMEDIATE) ------------------------------------------------------- The most recent named definition is used instead. * Name not defined by VALUE used by TO ------------------------------------ Ignore and continue: the definition may be corrupted. * Name not found for ' POSTPONE ['] --------------------------------- Exception -13 is THROWn. * Parameters are not of the same type for DO ?DO WITHIN ----------------------------------------------------- Ignore and continue: unexpected results will occur. * POSTPONE applied to TO ---------------------- The semantics of TO will be compiled into the current definition. On execution, according to the value of STATE either the interpretation or compilation semantics of TO will be performed. * String longer than a counted string returned by WORD ---------------------------------------------------- The length of the string modulo 256 will be returned in the count. * u greater than or equal to number of bits in a cell for LSHIFT or RSHIFT ------------------------------------------------------------------------ u is taken modulo 256. If the value is still greater or equal to the number of bits in a cell, then the result will be zero. * Word not defined by CREATE for >BODY >DOES ------------------------------------------ Ignore and continue: unexpected results may occur, although >BODY returns useful results for VARIABLEs VALUEs and DEFERred words. * Words improperly used outside <# and #> --------------------------------------- Ignore and continue: unexpected results will occur, including corruption of the top two stack itmes, possibly resulting in stack underflow and a crash. Other system documentation: CORE and CORE EXTENSION word sets ============================================================= * Non-standard words using PAD ---------------------------- None. Note that nesting of input levels above 6 will overwrite PAD, however. * Operator's terminal facilities ------------------------------ The standard terminal provides an 8 line by 91 character scrolling display with input facilities described above as for ACCEPT. Z88 CamelForth interfaces properly with the rest of the Z88 operating system, OZ, and may be treated as any other standard application. Enhanced terminal facilities such as multiple windows, graphics map area and display formatting are documented elsewhere. * Program dataspace available in address units -------------------------------------------- The space available in the current region can be displayed with UNUSED U. * Return stack space available in cells ------------------------------------- The main terminal task has 93 cells of return stack space; other tasks each have 64 cells of return stack space. * Stack space available in cells ------------------------------ A total of 128 cells is available for the data stack (in practice, more is normally available to the active task, but a maximum of 128 cells must be present when PAUSE is executed). * System dictionary space required in address units ------------------------------------------------- Z88 CamelForth uses the whole of segment 3 for its system dictionary (16K address units). Implementation-defined options: BLOCK and BLOCK EXTENSION word sets =================================================================== * Format used for display by LIST ------------------------------- A header showing the "Block " and the block number is first displayed, followed by 16 lines of 64 characters preceded by the line number (0..15) and a space. After every 8 lines of output, the display is paused for the user to press a key using PW. * Length of a line affected by \ ------------------------------ 64 characters Ambiguous conditions: BLOCK and BLOCK EXTENSION word sets ========================================================= * Correct block read was not possible ----------------------------------- Exception -35 (invalid block number) is THROWn if the block number is not in the range 1..16384. If the relevant range of blocks has not been mapped to a file with MAP, then OZ will cause a fatal error of bad handle and terminate the application. Otherwise, block reads of non-existent blocks are usually successful, resulting in the file being extended as necessary. However, if an ior result is returned by the file handling words, block words will THROW the ior as an exception. * I/O exception in block transfer ------------------------------- See above discussion. * Invalid block number -------------------- Exception -35 * A program directly alters the contents of BLK --------------------------------------------- Ignore and continue: the input source will be switched to the following block the next time that it becomes exhausted. This could cause confusion in the system if the current source is not a block (ie the unmodified contents of BLK were zero). If a program alters BLK to zero from a non-zero value, confusion will definitely reign... * No current block buffer for UPDATE ---------------------------------- Ignore and continue: this may result in an error attempting to write block 0. Other system documentation: BLOCK and BLOCK EXTENSION word sets =============================================================== * Restrictions due to multiprogramming system on buffer addresses --------------------------------------------------------------- Buffers are shared between all tasks (as are all other data areas). Therefore, after a PAUSE, all buffer addresses previously obtained are invalid. * Number of blocks available for source text and data --------------------------------------------------- Limited only by available memory in the Z88. Implementation-defined options: EXCEPTION and EXCEPTION EXTENSION word sets =========================================================================== * Values used in the system by CATCH and THROW -------------------------------------------- Standard exceptions: -1 ABORT -2 ABORT" -13 undefined word -35 invalid block number -49 search-order overflow System-specific exceptions: -4095 word cannot be "fast"-compiled -4094 input nesting exception -4093 non-contigious compilation spaces -4092 invalid block buffer allocation -(256+OZerr) OZ/package error code (see Z88 Developers' Notes and individual package documentation for details) -(512+pkgid) Package not found Implementation-defined options: FACILITY and FACILITY EXTENSION word sets ========================================================================= * Encoding of keyboard events by EKEY ----------------------------------- Key events are encoded as follows: 0..255 standard ASCII codes and control characters, including ENTER DEL TAB and ESC 256..511 subtracting 256 from this value leaves a special key code returned by the OZ call OS_IN, and detailed in the Z88 Developers' Notes section 9 (Input and the keyboard decoder). The value 256 indicates an error occurred during input; this usually means that the application has been preempted. * Duration of a system clock tick ------------------------------- 1/100s (one centisecond) * Repeatability to be expected from execution of MS ------------------------------------------------- This word is implemented using an accurate machine-coded delay loop. However, a certain amount of variation can be expected, depending on the current load placed on the system interrupts. When in multi-programming mode, this word executes PAUSE every 10ms and therefore becomes wildly inaccurate if any other tasks are awake. Ambiguous conditions: FACILITY and FACILITY EXTENSION word sets =============================================================== * AT-XY operation can't be performed on user output device -------------------------------------------------------- The operation is simply ignored with no effect Implementation-defined options: FILE and FILE EXTENSION word sets ================================================================= * File access methods used ------------------------ The R/O R/W amd W/O file access methods are implemented using the equivalent OZ methods, except that for OPEN-FILE the W/O method is substituted by R/W to prevent OZ from deleting any existing file. The BIN method is a no-operation, as binary and text files are indistinguishable on the Z88. * File exceptions --------------- None * File line terminator -------------------- READ-LINE accepts either CR (ASCII 13) or LF (ASCII 10) as a terminator. For files with compound (CRLF or LFCR) line terminators, each line returned by READ-LINE will be followed by an additional line of zero length. * File name format ---------------- This follows the conventions detailed in the Filer Reference section of the Z88 Manual, and may include device specifications, directories, filenames and wildcards. File names are case-insensitive. * Information returned by FILE-STATUS ----------------------------------- The value returned is an address of a structure in a transient area holding the creation and update time/date in internal machine format. This area may be overwritten on pre-emption or with the use of other words accessing OZ's facilities, so are best converted to time & date on the stack with the word INT>T&D: For creation time & date with "x" on the stack: INT>T&D ( x -- sec min hr d m y ) For update time & date with "x" on the stack: 6 + INT>T&D ( x -- sec min hr d m y ) * Input file state after an exception ----------------------------------- When an exception is THROWn, any files currently being interpreted by INCLUDED or INCLUDE-FILE that are exited by the exception are automatically closed. * IOR values and meaning ---------------------- All ior values returned are the result of adding 256 to the OZ error received and then negating the result, ie -(256+OZerr). OZ error codes are documented in the Z88 Developers' Notes. * Maximum depth of file input nesting ----------------------------------- Up to 8 nested levels are permissible. However, this number of levels will overwrite PAD; for safety it is recommended that a maximum of 6 nested levels are used. * Maximum size of input line -------------------------- 128 characters * Methods for mapping block ranges to files ----------------------------------------- No block buffers are allocated initially, so this must be done first using: BLKS ( n -- ) This allocates n block buffers for use (n=1..4) with the system, and may only be performed once, or exception -4092 will be THROWn. Prior to using any words from the BLOCK and BLOCK EXTENSION word sets, an existing file must first be mapped to one of four available ranges using the word: MAP ( caddr u n -- ) Where caddr u is a filename, and n specifies a range of blocks to map the file to as follows: n=0 Blocks 1...4096 n=1 Blocks 4097...8192 n=2 Blocks 8193..12288 n=3 Blocks 12289..16384 Up to 4 files can be mapped at once, one to each of the available ranges. To unmap a file from a range of blocks, use the following word: UNMAP ( n -- ) which unmaps the file just unmapped. This must be done before exiting Z88 CamelForth, to avoid leaving files open. Note that use of MAP and UNMAP always invalidate ALL the block buffers. One final point to make is that there is no correlation between the number of block buffers allocated and the number of files mapped; the system will work just as well with 4 buffers and 1 file as with 1 buffer and 3 files, or any other combination. * Number of string buffers provided by S" --------------------------------------- 1 * Size of string buffer used by S" -------------------------------- 128 characters Ambiguous conditions: FILE and FILE EXTENSION word sets ======================================================= * Attempting to position a file outside its boundaries ---------------------------------------------------- For files opened with the R/O access method, an ior of -276 will be returned (corresponding to the OZ error code rc_wp). For files opened with the R/W or W/O access methods, the size of the file will be extended to incorporate the new position. * Attempting to read from file positions not yet written ------------------------------------------------------ For files opened with the R/O access method, an ior of -276 will be returned (corresponding to the OZ error code rc_wp). For files opened with the R/W or W/O access methods, the size of the file will be extended to incorporate the new position. * Fileid is invalid ----------------- OZ usually returns a fatal error of Bad Handle which normally results in the application being terminated. * Named file cannot be opened --------------------------- Exception -274 is THROWn (corresonding to the OZ error code rc_onf). * Requesting an unmapped block number ----------------------------------- If no file is mapped to blocks, exception -35 will be THROWn. Otherwise, the file will be extended as necessary to allow mapping to the requested block number (if this causes a file error, the ior will be THROWn as an exception). * Using SOURCE-ID when BLK is not zero ------------------------------------ Under these circumstances SOURCE-ID will return zero. Implementation-defined options: PROGRAMMING TOOLS and EXTENSION word sets ========================================================================= * Ending sequence for input following CODE ---------------------------------------- The word NEXT will compile a jump to the inner interpreter, forming a suitable ending sequence. * Manner of processing input following CODE ----------------------------------------- No assembler is provided, so code must be hand-assembled and compiled into the dictionary with the C, and , words. * Search-order capability for EDITOR ---------------------------------- The ANS Forth Search-Order word set. Implementation-defined options: SEARCH-ORDER and EXTENSION word sets ==================================================================== * Maximum number of word lists in the search order ------------------------------------------------ 8 * Minimum search order -------------------- FORTH Ambiguous conditions: SEARCH-ORDER and SEARCH-ORDER EXTENSION word sets ======================================================================= * Changing the compilation word list ---------------------------------- This has no adverse affects, since the definition is entered into the compilation word list before it can be changed, and any changes made by IMMEDIATE and the like apply to the latest definition, irrespective of the compilation word list. * Search order empty ------------------ Ignore and continue: this will cause a crash. * Too many word lists in search order ----------------------------------- Exception -49 (search order overflow) is THROWn.