VAX-11 fig-Forth Version 2.0 GLOSSARY by Rodrick A. Eldridge Central Iowa Forth Interest Group Iowa State University The public domain VAX-11 Fig-Forth Version 1.0 is provided through the courtesy of Forth Interest Group, P. O. Box 1105, San Carlos, CA 94070 This public domain publication is provided through the courtesy of Central Iowa FIG (CIFIG), Iowa State University, Ames, IA 50011 Futher distribution must include these notices - 1 - NOTICE This document and its related software is placed in the public domain. Permission is granted to reproduce and distribute this document and its related software with the following restriction: No distributor is allowed to restrict its further redistribution. Further distribution must include the following notices: * * * * * The public domain VAX-11 fig-Forth Version 1.0 is provided through the courtesy of Forth Interest Group, P. O. Box 1105, San Carlos, CA 94070 This public domain publication is provided through the courtesy of Central Iowa FIG (CIFIG), Iowa State University, Ames, IA 50011 * * * * * Please send corrections and modifications to: Central Iowa Forth Interest Group c/o Rodrick A. Eldridge Iowa State University 104 Computer Science Ames, Iowa 50011 - 2 - REFERENCES fig-Forth Installation Manual by Willaim F. Ragsdale Forth Interest Group Forth-79 Standard Forth Interest Group Forth-83 Standard Forth Interest Group fig-Forth for VAX-11, Assembly Source Listing by Bob Haller and Doug Mercer Forth Interest Group fig-Forth for PDP-11, Assembly Source Listing by John S. James Forth Interest Group Systems Guide to fig-Forth by C. H. Ting, Offete Enterprises, Inc. All About Forth, An annotated Glossary by Glen B. Haydon Mountain View Press, Inc. - 3 - GLOSSARY This glossary contains all of the word definitions in this implementation. The first line of each entry shows a symbolic description of the action of the procedure on the parameter stack. The symbols indicate the order in which input parameters have been placed on the stack. Three dashes "---" indicate the execution point and any parameters left on the stack are listed. In this notation, the top of the stack is to the right. The symbols shown include: addr memory address b 8 bit byte c 7 bit ascii character cfa code field address count 16 bit signed integer number d 32 bit signed double number f boolean flag. 0=false, non-zero=true ff boolean false flag=0 lfa link field address n 16 bit signed integer number nfa name field address pfa parameter field address u 16 bit unsigned integer number ud 32 bit unsigned double number tf boolean true flag=non-zero Unless otherwise noted, all references to numbers are for 16 bit signed integers. For 32 bit signed double numbers, the most significant portion with sign is on top of stack. Unless otherwise specified in the glossary, all arithemetic is implicitly 16 bit signed integer math, with error and under-flow indication unspecified. The first line also shows the "standard" in which the word is defined. These symbols include: FIG defined in fig-Forth F79 defined in Forth-79 F83 defined in Forth-83 ISU local definition or modification - 4 - ^@ ( --- ) FIG This is a pseudonym for the dictionary entry for a name of one character of ascii "null" (i.e. hex 00). It is the execution procedure to terminate interpretation of a line of text from the terminal or within a disk buffer, as both buffers always have a "null" at the end. ! ( n addr --- ) FIG,F79,F83 Store n at address. Pronounced "store". !CODE ( --- ) FIG Used by CONSTANT, USER and VARIABLE to compile a constant, user variable and variable, respectively. !CSP ( --- ) FIG Save the stack position in CSP. Used as part of the compiler security. # ( d1 --- d2 ) FIG,F79,F83 Generate from a double number d1, the next ascii character which is placed in an output string. The result, double number d2, is the quotient after division by BASE and is maintained for further processing. Used between <# and #> #> ( d --- addr count ) FIG,F79,F83 End numeric output conversion by dropping d, leaving the text address and character count suitable for TYPE. #S ( d1 --- d2 ) FIG,F79,F83 Convert all digits of a double number d1, adding each to the pictured numeric output text, until the remainder is zero. A single zero is added to the output string if the number was initially zero. Used between <# and #> ' ( --- pfa ) FIG,F79,F83 Used in the form: ' - 5 - If executing, leave the parameter field address of the next word accepted from the input stream. If compiling, compile this address as a literal. Later execution will place this value on the stack. If the word is not found after a search of CONTEXT and CURRENT, an appropriate error message is given. Pronounced "tick". Note: in Forth-83, ' leaves the code field address. ( ( --- ) FIG,F79,F83 Used in the form: ( comment) Accept and ignore comment characters from the input stream, until the next right parenthesis. As a word, the left parenthesis must be followed by one blank. It may be freely used while executing or compiling. Note: both ( and ) must be on the same line. (+LOOP) FIG The run time procedure compiled by +LOOP which increments the loop index by the value on the stack and tests for loop completion. See +LOOP (.") FIG The run time procedure compiled by ." which transmits the following in-line text to the terminal. See ." (;CODE) FIG The run time procedure compiled by ;CODE that rewrites the code field of the most recently defined word to point to the following machine code sequence. See ;CODE (ABORT) FIG Executes after an error when WARNING is -1. This word normally executes ABORT but may be altered to a user's alternative procedure. See ABORT - 6 - (BLOCK-READ) ISU Used by BLOCK-READ. See BLOCK-READ (BLOCK-WRITE) ISU Used by BLOCK-WRITE. See BLOCK-WRITE (CR) ISU Used by CR. See CR (DO) FIG The run time procedure compiled by DO which moves the loop control parameters to the return stack. See DO (EMIT) ISU Used by EMIT. See EMIT (EXPECT) ISU Used by EXPECT. See EXPECT (FIND) ( addr nfa --- ff ) FIG ( addr nfa --- pfa b tf ) Searches the dictionary starting at the name field address, matching to the text at addr. Returns the parameters field address, the length byte of the name field and boolean true flag for a good match. If no match is found, only a boolean false flag is left. See -FIND (HELP) ISU Used by HELP. See HELP - 7 - (ID) ISU Used by ID. and VLIST. (KEY) ISU Used by KEY. See KEY (LINE) ( n1 n2 --- addr count ) FIG Convert the line number n1 and the screen number n2 to the disk buffer address containing the data. A count of C/L indicates the full line text length. (LOAD-SYSTEM) ISU Used by LOAD-SYSTEM. See LOAD-SYSTEM (LOOP) FIG The run time procedure compiled by LOOP which increments the loop index and tests for loop completion. See LOOP (NEED) ISU Used by NEED. See NEED (NUMBER) ( d1 addr1 --- d2 addr2 ) FIG Convert the ascii text beginning at addr1+1 with regard to BASE. The new value is accumulated into double number d1, being left as d2. addr2 is the address of the first unconvertable digit. See NUMBER Note: in Forth-79 and Forth-83, (NUMBER) is called CONVERT. (QUERY) ( --- addr count ) ISU Used by QUERY at COLD start. Returns the "foreign command line" specified at run time. If the "foreign command": FORTH := VAXUSR:[CLASSLIB.005003.VAX.FORTH]FORTHV2. is executed as: FORTH - 8 - then, (QUERY) will return the address of the and a count of these characters. You may execute (QUERY) anytime yourself to return this address and count. See also QUERY. (R/W) ISU Used by R/W. See R/W (SAVE-SYSTEM) ISU Used by SAVE-SYSTEM. See SAVE-SYSTEM (SCR) ISU Used by ?SCR. See ?SCR (TYPE) ISU Used by TYPE. See TYPE * ( n1 n2 --- n3 ) FIG,F79,F83 Leave the signed product of n1 * n2. */ ( n1 n2 n3 --- n4 ) FIG,F79,F83 Multiply n1 by n2, divide the result by n3 and leave the quotient. The quotient is rounded toward zero. The product of n1 * n2 is maintained as and intermediate 32 bit value for greater precision than the otherwise equivalent sequence: n1 n2 * n3 /. */MOD ( n1 n2 n3 --- n4 n5 ) FIG,F79,F83 Multiply n1 by n2, divide the result by n3 and leave the remainder n4 and quotient n5. A 32 bit intermediate product is used as for */. The remainder has the same sign as n1. - 9 - + ( n1 n2 --- n3 ) FIG,F79,F83 Leave the sum of n1 + n2. +! ( n addr --- ) FIG,F79,F83 Add n to the 16 bit value at addr. +- ( n1 n2 --- n3 ) FIG Appy the sign of n2 to n1, which is left as n3. +BUF ( addr1 --- addr2 f ) FIG Advance the disk buffer address addr1 to the address of the next buffer addr2. Boolean flag f is false when addr2 is the buffer presently pointed to by variable PREV. +LOOP ( n --- ) FIG,F79,F83 Used in the form: DO .. +LOOP Used only in a colon definition. Add the increment n to the loop index and compare the total to the loop limit. Return execution to the corresponding DO until the new index is equal to or greater than the limit (n>0) or until the new index is less than the limit (n<0). Upon exiting the loop, the parameters are discarded and execution continues ahead. See also DO +ORIGIN ( n --- addr ) FIG Leave the memory address relative by n to the ORIGIN parameter area. n is in bytes. This definition is used to access or modify the boot-up parameters at the ORIGIN area. , ( n --- ) FIG,F79,F83 Allocate two bytes in the dictionary, storing n there. Pronounced "comma". - 10 - - ( n1 n2 --- n3 ) FIG,F79,F83 Leave the difference of n1 - n2. --> ( --- ) FIG,F79,F83 Continue interpretation with the next disk screen. Pronounced "next-screen". -DUP ( n --- n ) ( if zero) FIG ( n --- n n ) ( if non-zero) Reproduce n only if it is non-zero. This is usually used to copy a value just before IF to eliminate the need for an ELSE part to DROP it. Note: in Forth-79 and Forth-79, -DUP is called ?DUP -FIND ( --- ff ) FIG ( --- pfa b tf ) Accepts the next text word, delimited by blanks, in the input stream to HERE and searches the CONTEXT vocabulary and then the CURRENT vocabulary for a matching entry. If found, the dictionary entry's parameter field address, its length byte, and a boolean true flag is left, otherswise, only a boolean false flag is left. -TRAILING ( addr n1 --- addr n2 ) FIG,F79,F83,ISU Adjusts the character count n1 of a text string beginning at addr to exclude trailing blanks, i.e. the characters at addr+n2 to addr+n1 are blanks. . ( n --- ) FIG,F79,F83 Display n converted according to BASE in a free field format with one trailing blank. If n is negative, . will display the negative sign. Pronounced "dot". ." ( --- ) FIG,F79,F83 Used in the form: ." string" Compiles an in-line string, delimited by the trailing ." with an execution procedure to transmit the text to the terminal. If executed outside a definition, ." will immediately print the text until the final closing quote. - 11 - .LINE ( n1 n2 --- ) FIG Print to the terminal, a line of text from the disk by its line number n1 and screen number n2. Trailing blanks are suppressed. .R ( n1 n2 --- ) FIG Print n1 right aligned in a field whose width is n2 characters according to BASE. If n2 is less than 1, no leading blanks are supplied. / ( n1 n2 --- n3 ) FIG,F79,F83 Leave the signed quotient of n1 / n2. /MOD ( n1 n2 --- n3 n4 ) FIG,F79,F83 Leave the remainder and the signed quotient of n1 / n2. The remainder has the same sign as the dividend. 0 ( --- n ) FIG A constant leaving 0 on the stack. 1 ( --- n ) FIG A constant leaving 1 on the stack. 2 ( --- n ) FIG A constant leaving 2 on the stack. 3 ( --- n ) FIG A constant leaving 3 on the stack. 0< ( n --- f ) FIG,F79,F83 Leave a true flag if the number is less than zero (negative), otherwise, leave a false flag. - 12 - 0= ( n --- f ) FIG,F79,F83 Leave a true flag if the number is equal to zero, otherwise, leave a false flag. 0BRANCH ( f --- ) FIG The run time procedure to conditionally branch. If f is false (zero), the following in-line address is used to branch to. 1+ ( n1 --- n2 ) FIG,F79,F83 Increment n1 by 1, leaving the sum n2. 2+ ( n1 --- n2 ) FIG,F79,F83 Increment n1 by 2, leaving the sum n2. 2DROP ( d --- ) FIG This word is not defined in this implementation. Use DDROP 2DUP ( d --- d d ) FIG This word is not defined in this implementation. Use DDUP 2OVER ( d1 d2 --- d1 d2 d1 ) FIG This word is not defined in this implementation. Use DOVER 2SWAP ( d1 d2 --- d2 d1 ) FIG This word is not defined in this implementation. Use DSWAP : ( --- ) FIG,F79,F83 Used in the form: : .. ; Creates a dictionary entry defining as equivalent to the following - 13 - sequence of Forth word definitions ".." until the next ; or ;CODE. The compiling process is done by the text interpreter as long as STATE is non-zero. Other details are that the CONTEXT vocabulary is set to the CURRENT vocabulary and that words with the precedence bit set are executed rather than being compiled. Pronounced "colon". ; ( --- ) FIG,F79,F83 Terminate a colon definition and stop futher compilation. Compiles the run time procedure ;S. ;CODE ( --- ) FIG Used in the form: : .. ;CODE assembly_mnemonics Stop compilation and terminate a new defining word by compiling the run time procedure (;CODE). Set the CONTEXT vocabulary to ASSEMBLER and assemble to machine code the following mnemonics. When later executes in the form: the word will be created with its execution procedure given by the machine code following . That is, when is executed, it does so by jumping to the code after . An existing defining word must exist in prior to ;CODE. ;S ( --- ) FIG Stop interpretation of a screen. ;S is also the run time word compiled at the end of a colon definition which returns execution to the calling procedure. < ( n1 n2 --- f ) FIG,F79,F83 Leave a true flag if n1 < n2, otherwise, leave a false flag. <# ( --- ) FIG,F79,F83 Initialize for pictured numeric output formatting using the words: <# # #S SIGN #> The conversion is done on a double number producing text at PAD. - 14 - .. ; Each time is executed, later executes in the form: uses with a cell to the DOES> part for . When is later executed, it has the address of its parameter area on the stack and executes the words after DOES> in . allow run time procedures to be written in high-level rather than in assembler code as required by ;CODE. See also DOES> Note: in Forth-79 and Forth-83, ( n1 n2 --- f ) FIG,F79,F83 Leave a true flag if n1 > n2, otherwise, leave a flase flag. >IN ( --- addr ) F79,F83 In fig-Forth, >IN is called IN. See IN >R ( n --- ) FIG,F79,F83 Transfer n to the return stack. Every >R must be balanced by a R> in the same control structure nesting level of a colon definition. Pronounced "to-r". See also R> ? ( addr --- ) FIG,F79 Print the value contained at addr in free format according to BASE. - 15 - ?COMP ( --- ) FIG Issue an error message if not compiling. ?CSP ( --- ) FIG Issue an error message if the stack position differs from the value saved in CSP. ?DUP ( n --- n ) ( if zero) F79,F83 ( n --- n n ) ( if non-zero) In fig-Forth, ?DUP is called -DUP. See -DUP ?ERROR ( --- ) FIG Issue an error message number n, if the boolean flag is true. ?EXEC ( --- ) FIG Issue an error message if not executing. ?LOADING ( --- ) FIG Issue an error message if not loading. ?PAIRS ( --- ) FIG Issue an error message if n1 does not equal n2. The message indicates that compiled conditionals do not match. ?SCR ( n --- f ) ISU Leaves a boolean true flag on the stack if SCR # n exists, otherwise, leaves a boolean false flag. - 16 - ?STACK ( --- ) FIG,ISU Issue an error message if the stack is out of bounds. ?TERMINAL ( --- f ) FIG Perform a test of the terminal keyboard for actuation of the break key. A true flag indicates actuation. @ ( addr --- n ) FIG,F79,F83 Leave on the stack the number contained at addr. Pronounced "fetch". ABORT ( --- ) FIG,F79,F83 Clear the stacks and enter the execution state. Return control to the terminal and print a message. ABS ( n --- u ) FIG,F79,F83 Leave the absolute value of n as u. AGAIN ( --- ) FIG,F79,F83 Used in the form: BEGIN .. AGAIN Used only in a colon definition. Effect an uncontional jump back to the start of a BEGIN-AGAIN loop. AGAIN is an alias of REPEAT. See REPEAT ALLOT ( n --- ) FIG,F79,F83 Add n bytes to the parameter field of the most recently defined word. May be used to reserve memory space. AND ( n1 n2 --- n3 ) FIG,F79,F83 Leave the bitwise logical "and" of n1 and n2. - 17 - B/BUF ( --- n ) FIG,ISU A constant leaving the number of bytes per block buffer. In this implementation, although there are 2048 bytes per buffer, only 1920 bytes are used (i.e. 24 lines by 80 characters). B/SCR ( --- n ) FIG,ISU A constant leaving the number of blocks per editing screen. In this implementation, there is one block per editing screen. BACK ( addr --- ) FIG Compiles addr into the next available dictionary memory address. BASE ( --- addr ) FIG,F79,F83 Leave the address of a user variable containing the current input and output numeric conversion base. BEGIN ( --- ) FIG,F79,F83 Used in the form: BEGIN .. UNTIL BEGIN .. WHILE .. REPEAT Used only in a colon definition. BEGIN marks the start of a word sequence for repetitive execution. A BEGIN-UNTIL loop will be repeated until flag f is true. See UNTIL A BEGIN-WHILE-REPEAT loop will be repeated until flag f is false. WHILE is optional. AGAIN is an alias of REPEAT. See WHILE and REPEAT The words after UNTIL or REPEAT will be executed when either loop is finished. BINARY ( --- ) ISU Set the input-output numeric conversion base to two (binary). - 18 - BL ( --- c ) FIG A constant that leaves the ascii value for "blank". BLANKS ( addr n --- ) FIG Fill an area of memory beginning at addr with n blanks. BLK ( --- addr ) FIG,F79,F83 A user variable containing the block number begin interpreted. If zero, input is being taken from the terminal input buffer. BLOCK ( n --- addr ) FIG,F79,F83 Leave the memory address of the block buffer containing block n. If the block is not already in memory, it is transferred from disk to which ever buffer was least recently written. If the block occupying that buffer has been marked as updated, it is rewritten to disk before block n is read into the buffer. See also BUFFER BLOCK-READ ( addr1 addr2 count --- ff 0 ) FIG,F79,F83,ISU ( addr1 addr2 count --- tf n ) Reads a block from disk into addr1. addr2 (address of ascii screen number) and count were created by R/W. If no I/O error occured, a boolean false flag and zero are left on the stack, otherwise, a boolean true flag and an error number are left on the stack. See also R/W BLOCK-WRITE ( addr1 addr2 count --- ff 0 ) FIG,F79,F83,ISU ( addr1 addr2 count --- tf n ) Writes a block from addr1 to disk. addr2 and count was created the same way as for BLOCK-READ. If no I/O error occured, a boolean false flag and zero are left on the stack, otherwise, a boolean true flag and an error number are left on the stack. See BLOCK-READ BRANCH ( --- ) FIG The run time procedure to unconditionally branch. An in-line address is used to branch to. - 19 - BUFFER ( n --- addr ) FIG Obtain the next memory buffer, assigning it to block n. If the contents of the buffer is marked as updated, it is written to the disk. The block is not read from the disk. The address left is the first cell within the buffer for data storage. See also BLOCK BYE ( --- ) FIG FLUSH all buffers and exit Forth. See also MON C! ( b addr --- ) FIG,F79,F83 Store 8 bits of b at addr. C, ( b --- ) FIG,F79,F83 Store 8 bits of b into the next available dictionary byte, advancing the dictionary pointer. C/L ( --- n ) FIG A constant leaving the number of character per line on the stack. In this implementation, there are 80 characters per line. C@ ( addr --- b ) FIG,F79,F83 Leave on the stack the contents of the byte at addr. CFA ( pfa --- cfa ) FIG Convert the parameter field address of a definition to its code field address. CMOVE ( addr1 addr2 n --- ) FIG,F79,F83 Copy n bytes starting at addr1 to addr2. The move proceeds from low memory to high memory. - 20 - COLD ( --- ) FIG The cold start procedure to adjust the dictionary pointer to the minimum standard and restart via ABORT. COLD may be called to remove application programs and restart. See ABORT. See also WARM COMPILE ( --- ) FIG,F79,F83 When the word containing COMPILE executes, the execution address of the word following COMPILE is copied (compiled) into the dictionary. This allows specific compilation situations to be handled in addition to simply compiling an execution address. CONSTANT ( n --- ) FIG,F79,F83 Used in the form: n CONSTANT Creates word with it parameter field address containing n. When is later executed, it will push the value of n to the stack. CONTEXT ( --- addr ) FIG,F79 A user variable containing a pointer to the vocabulary within which dictionary searches will first begin. CONVERT ( d1 addr1 --- d2 addr2 ) F79,F83 In fig-Forth, CONVERT is called (NUMBER). See (NUMBER) COUNT ( addr1 --- addr2 count ) FIG,F79,F83 Leave the address, addr2, and the byte count of a text string beginning at addr1. It is presumed that the first byte at addr1 contains the text byte count and the actual text starts with the second byte. Typically COUNT is followed by TYPE. CR ( --- ) FIG,F79,F83,ISU Transmit a carriage return and line feed to the terminal. - 21 - CREATE ( --- ) F79,F83 In fig-Forth, this form of CREATE is called Used by such words as CODE and CONSTANT to create a dictionary header for a Forth definition. The code field address contains the address of the word's parameters field address. The new word is created in the CURRENT vocabulary. Note: in Forth-79 and Forth-83, DEFINITIONS Set the CURRENT vocabulary to the CONTEXT vocabulary. DEFDIR ( --- addr ) ISU A user variable that contains the default DIR setting for disk access in HELP and MESSAGE. DEFDIR defaults to 0, i.e. HELP and MESSAGE use "FORTH0:" by default. See also DIR DEFSCR ( --- addr ) ISU A user variable that contains the default SCR setting for disk access in MESSAGE. DEFSCR defaults to 4, i.e. MESSAGE uses SCR # 4 by default. See also MESSAGE DIR ( n --- ) ISU Sets the logical name "FORTHn:" and stores n into the user variable OFFSET. All disk access will be taken from this logical name. If n is not between 0 and 15, exclusively, an error message is given. DIGIT ( c n1 --- n2 tf ) FIG ( c n1 --- ff ) Converts the ascii character c (using base n1) to its binary equivalent n2, accompanied by a boolean true flag. If the conversion is invalid, leaves only a boolean false flag. - 24 - DLITERAL ( d --- d ) ( executing) FIG ( d --- ) ( compiling) If compiling, compile a stack double number into a literal. Later execution of the definition containing this literal will push it on the stack. If executing, the number will remain on the stack. DMINUS ( d1 --- d2 ) FIG Convert d to it double number two's complement. Note: in Forth-79 and Forth-83, DMINUS is called DNEGATE DNEGATE ( d1 --- d2 ) F79,F83 In fig-Forth, DNEGATE is called DMINUS. See DMINUS DO ( n1 n2 --- ) FIG,F79,F83 Used in the form: DO .. +LOOP DO .. LOOP Used only in a colon definition. Begin a loop which will terminate based on control parameters. The loop index begins at n2 and terminates based on the limit n1. At LOOP or +LOOP, the index is modified by a positive or negative value. The range of a DO-LOOP is determined by the terminating word and DO-LOOP my be nested. See also I LEAVE LOOP and +LOOP DOES> ( --- ) FIG,F79,F83 A word which defines the run time action within a high level defining word. DOES> alters the code field address and first parameter of the new word to execute the sequence of compiled word addresses following DOES>. Used in combination with part executes, it begins with the address of the first parameter of the new word on the stack. This allows interpretation using this area or its contents. Typical uses include the Forth assembler, multi-dimentional arrays, and compiler generation. See also Deletes definition named from the dictionary with all entries physically following it. An error message will occur if the CURRENT and CONTEXT vocabularies are not currently the same. FORTH ( --- ) FIG,F79,F83 The name of the primary vocabulary. Execution makes FORTH the CONTEXT vocabulary. Until additional user vocabularies are defined, new user definitions become a part of the FORTH vocabulary. FORTH is immediate, so it will execute during the creation of a colon definition, to select this vocabulary at compile time. HELP ( --- ) ISU Used in the form: HELP Accepts the next text word , delimited by blanks, in the input stream and searches the Forth HELP library for a matching entry. If found, the help text is displayed, otherwise, an error message is given. - 29 - HERE ( --- addr ) FIG,F79,F83 Leave the address of the next available dictionary location on the stack. HEX ( --- ) FIG Set the input-output numeric conversion base to sixteen (hexadecimal). HLD ( --- addr ) FIG A user variable that holds the address of the latest character of text during numeric output conversion. HOLD ( c --- ) FIG,F79,F83 Used between <# and #> to insert an ascii character into a pictured numeric output string. I ( --- n ) FIG,F79,F83 Used within a DO-LOOP to copy the loop index to the stack. See also R ID. ( nfa --- ) FIG,ISU Print a definition's name from its name field address. As a special case, all one character definition names with values less than hex 20 will be printed as ^letter (i.e. the "null" character will be printed as ^@, hex 01 will be printed as ^A, hex 02 will be printed as ^B, etc.). IF ( f --- ) FIG,F79,F83 Used in the form: IF .. ENDIF IF .. ELSE .. ENDIF Used only in a colon definition. If flag f is true, the words following IF are executed and the words following ELSE are skipped. The ELSE part is optional. If flag f is false, the words between IF and ELSE, or between IF and ENDIF (when no ELSE is used), are skipped. See also ELSE and ENDIF Note: in place of extensive nesting, it may be more efficient to define and use one of the several CASE utilities which have been defined in FORTH DIMENSIONS. - 30 - IMMEDIATE ( -- ) FIG,F79,F83 Mark the most recently made dictionary entry as a word which will be executed when encounterd during compilation rather than compiled. The user may force compilation of an IMMEDIATE definition by preceeding it with [COMPILE]. IN ( --- addr ) FIG A user variable containing the byte offset within the current input text buffer (terminal or disk) from which the next text will be accepted. WORD uses and moves the value of IN. Note: in Forth-79 and Forth-83, IN is called >IN INDEX ( n1 n2 --- ) FIG Print the first line of each screen over the range from screen n1 to n2. This is used to view the comment lines of the first line on disk screens. INPUT ( --- addr ) ISU A user variable that contains the VAX/VMS $QIO mask for input. INPUT defaults to IO$M_TRMNOECHO. INTERPRET ( --- ) FIG,F79,F83 The outer text interpreter which sequentially executes or compiles text from the input stream (terminal or disk) depending on STATE. If the word name cannot be found after a seach of CONTEXT and then CURRENT, it is converted to a number according to BASE. If that also fails, an error message echoing the name with a "?" will be given. Text input will be taken according to the convention for WORD. If a decimal point is found as part of a number, a double number value will be left. The decimal point has no other purpose then to force this action. See also NUMBER KEY ( --- c ) FIG,F79,F83,ISU Leave the ascii value of the next terminal key struck. - 31 - L/S ( --- n ) ISU A constant leaving the number of lines per screen on the stack. In this implementation, there are 24 lines per screen. LATEST ( --- nfa ) FIG Leave the name field address of the topmost word in the CURRENT vocabulary. LEAVE ( --- ) FIG,F79,F83 Force termination of a DO-LOOP at the next LOOP or +LOOP by setting the loop limit equal to the current value of the index. The index itself remains unchanged, and execution proceeds normally until the loop terminating word is encountered. LFA ( pfa --- lfa ) FIG Convert the parameter field address of a dictionary definition to its link field address. LIMIT ( --- addr ) FIG A constant leaving the address just above the highest memory available for a disk buffer. LIST ( n --- ) FIG,F79,ISU Display the ascii text of screen n to the terminal, setting the user variable SCR to n. Trailing blank lines will not be displayed. LIT ( --- n ) FIG Within a colon definition, LIT is automatically compiled before each 16 bit literal number encountered in the input test. Later execution of LIT causes the contents of the next dictionary address to be pushed to the stack. LITERAL ( n --- n ) ( executing) FIG,F79,F83 ( n --- ) ( compiling) If compiling, then compile the stack value n as a 16 bit literal, which when later executed, will leave n on the stack. If executing, leave n on the stack. - 32 - LOAD ( n --- ) FIG,F79,F83 Begin interpretation of screen n. Screen zero is unloadable. Loading will terminate at the end of the screen or at ;S. See also ;S and --> LOAD-SYSTEM ( --- ) ISU Used in the form: LOAD-SYSTEM Accepts the next text word , delimited by blanks, in the input stream, and loads the binary file containing the executable code after TASK using as the file name. LOAD-SYSTEM uses the current "FORTHn:" logical name. HERE is updated to point to the next available dictionary location after the load. See DR0 DR1 TASK and HERE LOOP ( --- ) FIG,F79,F83 Used in the form: DO .. LOOP Used only in a colon definition. LOOP increments the DO-LOOP index by one, and terminates the loop if the new index is equal to or greater than the limit. See also DO M* ( n1 n2 --- d) FIG A mixed magnitude math operation which leaves the double number signed product of n1 * n2. M+ ( d1 n --- d2 ) FIG A mixed magnitude math operation which will add the double number d1 to n and leave the double number result d2. M/ ( d n1 --- n2 n3 ) FIG A mixed magnitude math operation which leaves the remainder n2 and quotient n3, from a double number dividend d and divisor n1. The remainder takes its sign from the dividend. - 33 - M/MOD ( ud1 u2 --- u3 ud4 ) FIG A mixed magnitude math operation when leaves a double number quotient ud4 and remainder u3, from a double number dividend ud1 and divisor u2. MAX ( n1 n2 --- n3 ) FIG,F79,F83 Leave the greater of two numbers. MAXERRS ( --- addr ) ISU A user variable the contains the maximum number of system software errors allowed. If MAXERRS is exceeded, the message: %FORTH-F-MAXERRS, exceeded maximum number of errors allowed is displayed and control is returned to the operating system. MAXERRS defaults to 16. MESSAGE ( n --- ) FIG,ISU Print on the terminal, the text of line n relative to SCR # DEFSCR in DEFDIR. n may be positive or negative. If WARNING is zero, the message will simply be printed as a number. See also ERROR WARNING DEFSCR and DEFDIR MIN ( n1 n2 --- n3 ) FIG,F79,F83 Leave the less of two numbers. MINUS ( n1 --- n2 ) FIG Leave the two's complement of a number. Note: in Forth-79 and Forth-83, MINUS is called NEGATE MOD ( n1 n2 --- n3 ) FIG,F79,F83 Leave the remainder of n1 / n2, with the same sign as n1. - 34 - MON ( --- ) FIG Empty buffers and exit Forth. See also BYE and EMPTY-BUFFERS NEED ( --- ) ISU Used in the form: NEED Accepts the next text word , delimited by blanks, in the input stream; searches the CURRENT and CONTEXT vocabularies to see if has already been defined; and if not, searches the current NEED library for a matching entry. If found, the corresponding screen is loaded, otherwise, an error message is given. To load a word installed in "FORTH0:", issue: DR0 NEED DR1 NEGATE ( n1 --- n2 ) F79,F83 In fig-Forth, NEGATE is called MINUS. See MINUS NFA ( pfa --- nfa ) FIG Convert the parameter field address of a definition to its name field address. NUMBER ( addr --- d ) FIG Convert a count and character string at addr, to a signed double number, using the current BASE. If numeric conversion is not possible, an error message will be given. If a decimal point is encounted in the text, its position will be recorded in the user variable DPL, but no other effect occurs. The string may contain a preceding negative sign. OCTAL ( --- ) ISU Set the input-output numeric conversion base to eight. OFFSET ( --- addr ) FIG,ISU A user variable which contains the last value set by DR0, DR1, etc. See DR0 DR1 - 35 - OR ( n1 n2 --- n3 ) FIG,F79,F83 Leave the bitwise logical "or" of two 16 bit values as n3 on the stack. ORIGIN ( --- addr ) FIG A user variable that contains the address of the origin parameter area. OUT ( --- addr ) FIG A user variable that contains a value incremented by EMIT. The user may alter and examine OUT to control display formatting. OUTPUT ( --- addr ) ISU A user variable that contains the VAX/VMS $QIO output mask. OUTPUT defaults to 0. OVER ( n1 n2 --- n1 n2 n1 ) FIG,F79,F83 Leave a copy of the second number on the stack. PAD ( --- addr ) FIG,F79,F83,ISU Leave the address of the text output buffer, which is a fixed offset above HERE. In this implementation, PAD is 256 bytes above HERE. PFA ( nfa --- pfa ) FIG Convert the name field address of a compiled definition to its parameter field address. PREV ( --- addr ) FIG A user variable containing the address of the disk buffer most recently referenced. The UPDATE command marks this buffer to be later written to disk. - 36 - QUERY ( --- ) FIG,F79,ISU Accept input of up to 80 characters (or until a "return") from the terminal, into the terminal input buffer. Text is positioned at the address contained in TIB with IN set to zero. See also TIB and IN QUIT ( --- ) FIG,F79,F83 Clear the return stack, setting execution mode, and return control to the terminal. No OK message is given. R@ ( --- n ) F79,F83 In fig-Forth, R@ is called R. See R R ( --- n ) FIG Copy the top of the return stack to the computation stack. Note: in Forth-79 and Forth-83, R is called R@ R# ( --- addr ) FIG A user variable which may contain the location of an editing cursor, or other file related functions. R/W ( addr n f --- ) FIG,F79,F83 The fig-Forth standard disk read-write linkage. addr specifies the source or distination block buffer, n is the sequential number of the referenced block, and f is a flag for f=0 write and f=1 read. R/W determines the location on the disk, performs the read-write and performs error checking. See also BLOCK-READ and BLOCK-WRITE R0 ( --- addr ) FIG A user variable containing the initial location of the return stack. See also RP! - 37 - R> ( --- n ) FIG,F79,F83 Remove the top value from the return stack and leave it on the computation stack. Pronounced "r-from". See also >R and R REPEAT ( --- ) FIG,F79,F83 Used in the form: BEGIN .. REPEAT BEGIN .. WHILE .. REPEAT Used in a colon definition. REPEAT returns to just after the corresponding BEGIN. See also BEGIN ROT ( n1 n2 n3 --- n2 n3 n1 ) FIG,F79,F83 Rotate the top three values on the stack, bringing the third to the top. RP! ( --- ) FIG Initialize the return stack pointer from the user variable R0. See R0 S->D ( n --- d ) FIG Sign extend a single number to form a double number. Pronounced "s-to-d". S0 ( --- addr ) FIG A user variable that contains the initial value for the stack pointer. See also SP! SAVE-SYSTEM ( --- ) ISU Used in the form: SAVE-SYSTEM Accepts the next text word , delimited by blanks, in the input stream to HERE, and writes a binary file containing the executable code from TASK to HERE using as the file name. The file is written to the current "FORTHn:" logical name. See also DR0 DR1 TASK and HERE - 38 - SCR ( --- addr ) FIG A user variable that contains the screen number most recently referenced by LIST. SIGN ( n d --- d ) FIG,F79,F83 Insert the ascii "-" (negative sign) into the pictured numeric output string, if n is negative. n is removed from the stack but double number d is retained. Must be used between <# and #> SMUDGE ( --- ) FIG Used during word definition to toggle the "smudge bit" in a definition's name field. This prevents an uncompleted definition from being found during dictionary searches, until compiling is completed without error. SP! ( --- ) FIG Initialize the stack pointer from the user variable S0. See S0 SP@ ( --- addr ) FIG Return the address of top of the stack, just before SP@ was executed. SPACE ( --- ) FIG,F79,F83 Transmit an ascii blank to the terminal. SPACES ( n --- ) FIG,F79,F83 Transmit n ascii blanks to the terminal. STATE ( --- addr ) FIG,F79,F83 A user variable containing the compilation state. A non-zero value indicates compilation. - 39 - SWAP ( n1 n2 --- n2 n1 ) FIG,F79,F83 Exchange the top two values on the stack. TASK ( --- ) FIG A no-operation word which marks the boundary between applications. By forgetting TASK and re-compiling, an application can be discarded in its entirety. THEN ( --- ) FIG,F79,F83 An alias for ENDIF. See ENDIF Note: in Forth-79 and Forth-83, ENDIF is not defined. TIB ( --- addr ) FIG,F79 A user variable containing the address of the terminal input buffer. TOGGLE ( addr b --- ) FIG Complement the contents of addr by the bit pattern b. TRAVERSE ( addr1 n --- addr2 ) FIG Move across the name field of a fig-Forth variable length dictionary header. addr1 is the address of either the length byte or the last letter. The direction is based on n: 1. if n is 1, the motion is toward high memory, and 2. if n is -1, the motion is toward low memory. The addr2 resulting is the address of the other end of the name. TRIAD ( n1 n2 --- ) FIG This word is not defined in this implementation. - 40 - TYPE ( addr n --- ) FIG,F79,F83,ISU Transmit n characters from addr to the terminal. No action takes place for n less than or equal to zero. U* ( u1 u2 --- ud ) FIG,F79 Perform an unsigned multiplication of u1 by u2, leaving the unsigned double number product ud. Note: in Forth-83, U* is called UM* UM* ( u1 u2 --- ud ) F83 In fig-Forth and Forth-79, UM* is called U*. See U* U. ( u --- ) FIG,F79,F83 Display u converted according to BASE as an unsigned number, in a free field format, with one trailing blank. U/ ( ud u1 --- u2 u3 ) FIG Leave the unsigned remainder u2 and unsigned quotient u3 form the unsigned double dividend and unsigned divisor u1. Note: in Forth-79, U/ is called U/MOD; in Forth-83 U/ is called UM/MOD U/MOD ( ud u1 --- u2 u3 ) F79 In fig-Forth, U/MOD is called U/. See U/ UM/MOD ( ud u1 --- u2 u3 ) F83 In fig-Forth, UM/MOD is called U/. See U/ UNTIL ( f --- ) FIG,F79,F83 Used in the form: BEGIN .. UNTIL Used only in a colon definition. Terminate the BEGIN-UNTIL loop if f is true, - 41 - otherwise, return to just after the corresponding BEGIN. END is an alias for UNTIL. UPCASE ( addr n --- ) ISU Converts the word at HERE to upper case. Used by -FIND UPDATE ( --- ) FIG,F79,F83 Marks the most recently reference block (pointed to by PREV) as modified. The block will subsequently be automatically transferred to disk should its memory buffer be needed for storage of a different block, or upon execution of FLUSH. See also FLUSH and BYE USE ( --- addr ) FIG A user variable containing the address of the block buffer to use next, as the least recently written. USER ( n --- ) FIG Used in the form: n USER When USER is executed, it creates a user variable . The parameter field address of contains n as a fixed offset within the user area where the value for is stored. Execution of leaves its absolute user area storage address. In this implementation, there are 30 predefined user variables. VARIABLE ( n --- ) FIG,F79,F83 Used in the form: n VARIABLE When VARIABLE is executed, it creates a dictionary entry for and assigns two bytes for storage in the parameter field address, initializing it to n. When is later executed, it will place the storage address on the stack, so that a fetch or store may access this location. Note: in Forth-79 and Forth-83, the variable is not initialized. - 42 - VLIST ( --- ) FIG,ISU List the word names of the CONTEXT vocabulary starting with the most recent definition. The "break" key will terminate the listing. VOC-LINK ( --- addr ) FIG A user variable containing the address of a field in the definition of the most recently created vocabulary. All vocabulary names are linked by these fields to allow control for forgetting through multiple vocabularies. VOCABULARY ( --- ) FIG,F79,F83 Used in the form: VOCABULARY When VOCABULARY is executed, it creates a vocabulary definition . Subsequent use of will make it the CONTEXT vocabulary which is searched first by INTERPRET. The sequence " DEFINITIONS" will also make the CURRENT vocabulary into which new definitions are placed. In fig-Forth, will be so chained as to include all definitions of the vocabulary in which is itself defined. All vocabularies ulitmately chain to FORTH. By convention, vocabulary names are to be declared IMMEDIATE. See also FORTH and VOC-LINK WARM ( --- ) FIG Restart Forth with empty buffers. See EMPTY-BUFFERS. See also COLD WARNING ( --- addr ) FIG A user variable containing a flag which enables the output of selected non-fatal error messages: 1. if WARNING is 1, screen 4 of "FORTH0:" is the base location for messages. 2. if WARNING is 0, messages will be given by number. 3. if WARNING is -1, (ABORT) will be executed. See also MESSAGE and ERROR - 43 - WHILE ( f --- ) FIG,F79,F83 Used in the form: BEGIN .. WHILE .. REPEAT Used in a colon definition. If f is true, execution will continue through to REPEAT, which then returns back to just after BEGIN. If f is false, execution is skipped to just after the corresponding REPEAT. See also BEGIN. WIDTH ( --- addr ) FIG A user variable containing the maximum number of letters saved in the compilation of a definition's name. It must be 1 through 31, with a default value of 31; this value may be changed at any time within these limits. The name character count and its natural characters are saved, up to the value in WIDTH. WORD ( c --- ) FIG,F79,F83 Read the next text characters from the input stream being interpreted, until a delimiter character c is found, storing the packed character string beginning at the dictionary buffer HERE. WORD leaves the character count in the first byte, the characters, and ends with two or more blanks. Leading occurances of character c are ignored. If the user variable BLK is zero, text is taken from the terminal input buffer, otherwise, text is taken from the disk block number stored in BLK. Note: in Forth-79 and Forth-83, the address of the beginning of this packed string is left on the stack. XOR ( n1 n2 --- n3 ) FIG,F79,F83 Leave the bitwise logical "exclusive-or" of two 16 bit numbers. [ ( --- ) FIG,F79,F83 Used in the form: : .. [ .. ] .. ; Suspend compilation. The words between [ and ] are executed, not compiled. This allows calculation or compilation execptions before resuming compilation with ]. See also LITERAL and ] - 44 - [COMPILE] ( --- ) FIG,F79,F83 Used in the form: : .. [COMPILE] FORTH .. ; [COMPILE] will force the compilation of an immediate definition, that would otherwise execute during compilation. The above example will select the FORTH vocabulary when executes, rather than at compile time. ] ( --- ) FIG,F79,F83 Resume compilation, to the completion of a colon definition. See [ - 45 -