
DX-Forth Extension Wordset Glossary for CP/M
--------------------------------------------

The DX-Forth Extension Wordset is provided in addition to the FORTH-94
Standard words.


Attributes:

I    Words that have the immediate flag set
A    Words residing in the DX-Forth APPLICATION dictionary
S    Words residing in the DX-Forth SYSTEM dictionary
94   Words defined in the Forth-94 Standard
83   Words defined in the Forth-83 Standard
79   Words defined in the Forth-79 Standard
FIG  Words defined in the fig-Forth model
C    Words requiring custom installation

Stack notation:

Note: The following naming conventions for addresses are used to
maintain compatibility with the ANS FORTH document.  As DX-Forth does
not currently execute on architectures requiring address alignment,
all address types may be used interchangeably.

number    type                          cells      range
-----     ----                          -----      -----
addr      address                       1         0..65535
a-addr    aligned address               1         0..65535
c-addr    character-aligned address     1         0..65535
f-addr    float-aligned address         1         0..65535
p-addr    CPU port address              1         0..255

true      boolean true -1               1         -1
false     boolean false 0               1         0
flag      boolean true or false         1         -1 or 0
ior       input/output result           1         0..255

n         signed number                 1         -32768..32767
+n        positive number               1         0..32767
u         unsigned number               1         0..65535
x         unspecified number            1         -32768..65535
d         signed double number          1         -2147483648..
                                                    2147483647
+d        positive double number        2         0..2147483647
ud        unsigned double number        2         0..4294697295
xd        unspecified double number     2         -2147483648..
                                                    4294697295
r         real number                   2         +-5E-39..1E38
c         character or byte             1         0..255

ccc       any arbitrary blank-delimited character string or word name
          parsed from the input stream

"ccc"     same as for ccc; typically shown within a stack comment but
          represents characters parsed from the input stream.


Contents

 1. Disk File Interface
 2. Screen Files
 3. Tools
 4. DOS Interface
 5. Input/Output
 6. Arithmetic and Stack
 7. Conversion
 8. Strings and Memory
 9. Dictionary
10. Facility
11. Miscellaneous
12. Floating Point
13. Compiler Security
14. Control Flow Stack


1. Disk File Interface
----------------------

Note: When a file function returns a non-zero ior then an error has
occurred.  Refer to DXFORTH.TXT for a list of ior values and their
corresponding DOS error.

 #FCB  ( -- u )                                        A

     Return the maximum number of file handles available.  The default
     value is 10.  #FCB represents the maximum number of files that may
     be open at any one.  If more handles are needed it can be increased
     as follows e.g.

          20 TO #FCB  COLD

     This would change the maximum number of handles to 20.

 +EXT  ( c-addr1 u1 c-addr2 u2 -- c-addr3 u3 )         A

     Conditionally append the file extension c-addr2 u2 to the filename
     string c-addr1 u1 to produce c-addr3 u3.  If addr1 u1 does not
     already contain an extension (the '.' character is not present)
     then trailing blanks are removed and c-addr2 u2 is appended.
     Formerly named +FILENAME .

     Note: The returned string resides in a transient region and may be
     overwritten by subsequent operations.

     See: >FNAME

 -EXT  ( c-addr u1 -- c-addr u2 )                      A

     Delete any extension from the filename string c-addr u1.  The
     resulting string is c-addr u2.  Formerly named -FILENAME .

 -PATH  ( c-addr u1 -- c-addr u2 )                     A

     Delete any path from the filename string c-addr u1.  The resulting
     string is c-addr u2.

 >FNAME  ( c-addr1 u -- c-addr2 )                      A

     Convert the string c-addr1 u to a zero-terminated counted string
     c-addr2 in the filename buffer.  A maximum of two filenames can
     exist in the buffer at one time.  c-addr2 returns the counted
     string, whereas c-addr2 + 1 returns the zero-terminated string.

     Note: The returned string resides in a transient region and may be
     overwritten by subsequent operations.

     DX-Forth functions that use >FNAME or the filename buffer include:
     PATH +EXT OPEN-FILE CREATE-FILE DELETE-FILE RENAME-FILE

 BIN  ( fam1 -- fam2 )                                 A I 94

     Modify the file access method fam1 to additionally select a binary,
     i.e., not line oriented, file access method, giving access method
     fam2.  This has no effect under CP/M.

 CLOSE-FILE  ( fid -- ior )                            A 94

     If open, close the disk file associated with the current file-
     handle.  If the file could not be closed, ior is non-zero.

 CREATE-FILE  ( c-addr u fam -- fid ior )              A 94

     Create and open a disk file specified by the filename c-addr u
     using file access method fam.  Valid fam are R/W (read/write)
     R/O (read-only) and W/O (write-only).

     If a file with the same name already exists it will be erased.
     The file-pointer is set to the start of the file.  If the file
     could not be created, ior is non-zero.

 DELETE-FILE  ( c-addr u -- ior )                      A 94

     Delete the disk file specified by the string c-addr u.  If the file
     could not be deleted, ior is non-zero.

     Note: DELETE-FILE must not be performed on an open file.

 FILE-POSITION  ( fid -- ud ior )                      A 94

     Return the current position the file-pointer of the disk file
     associated with the file-handle fid.

 FILE-SIZE  ( fid -- ud ior )                          A 94

     Return the number of bytes in the file associated with file-handle
     fid.  For CP/M this number will be a multiple of 128.

     Note: FILE-SIZE returns the length of the file at the time it
     was opened.

 GETUSR  ( -- u )                                      A

     Return the current CP/M disk user number.

 LOADFILE  ( -- c-addr u )                             A

     Return a string containing the name of the disk file associated
     with the current file-handle.

     Note: The returned string resides in a transient region and may
     be overwritten by subsequent operations.

 OPEN-FILE  ( c-addr u fam -- fid ior )                A 94

     Open the existing disk file specified by the filename c-addr u
     using file access method fam.  Valid fam are R/W (read/write)
     R/O (read-only) and W/O (write-only).  If the file could not be
     opened, ior is non-zero.

 PATH  ( u1 -- c-addr u2 ior )                         A

     Get the full directory path for disk drive u1.  If an error occurs,
     ior is non-zero.  The returned string c-addr u2 includes the drive
     letter, current user number and trailing colon.  For the currently
     selected drive u1 = 0, otherwise u1 = 1 for drive A, 2 for drive B
     etc.

     Note: The returned string resides in a transient region and may be
     overwritten by subsequent operations.

 READ-FILE  ( a-addr u1 fid -- u2 ior )                A 94

     Read u1 bytes from the disk file associated with the current file-
     handle into memory starting at a-addr.  If ior is zero, u2 is the
     number of characters received.  If end of file is reached before
     any characters are read u2 is zero.

 READ-LINE  ( c-addr u1 fid -- u2 flag ior )           A 94

     Read a line of text from the disk file associated with file-handle
     fid into memory starting at address c-addr.  At most, u1 characters
     (255 maximum) are read.  If ior is zero and flag is true, u2 is the
     number characters received not including the line terminator.  If
     u2 = u1 then a line terminator was not yet received.  If an end-of-
     text character (1A hex) is read or the end of the file is reached
     before any other character is read then flag is false.

 REPOSITION-FILE  ( ud fid -- ior )                    A 94

     Reposition the file-pointer of the disk file associated with the
     file-handle fid to position ud.  If the file is positioned outside
     the file boundaries or an error occured, ior is non-zero.  If
     ud = 0 the file-pointer is positioned at the start of the file.

 RENAME-FILE  ( c-addr1 u1 c-addr2 u2 -- ior )         A 94

     Rename the disk file specified by c-addr1 u1 to the new name
     c-addr2 u2.  If the file cannot be found or the new name already
     exists then ior is non-zero.  Any drive/user prefix attached to
     the new name is ignored and is assumed to be the same as the old
     name.

     Note: RENAME-FILE must not be performed on an open file.

 RESET-DISKS  ( -- )                                   A

     Reset all disks to read/write status.  The currently logged drive
     and user number are unchanged.  RESET-DISKS is used after a disk
     change has occured.

 RSTUSR  ( -- )                                        A

     Restore the CP/M disk user number previously saved by SETUSR.

     See: SETUSR

 SETFCB  ( c-addr1 u1 a-addr2 -- u2 )                  A

     Parse the filename string specified by c-addr1 u1 in the form

          [d[u]:]filename[.typ]

     into the File Control Block at a-addr2.  Leading spaces are
     skipped.  The filename may optionally contain a drive letter (A-P)
     and user number u (0-15 for CP/M, 0-31 for Z-System).  If a drive/
     user is not specified, the current drive/user will be assumed.
     The following characters are treated as delimiters:

     space tab . , : ; < = > _ control-characters

     Note: Only the first 16 bytes of the File Control Block at a-addr2
     are initialized.  The parsed user number is not acted upon but
     returned as u2.  Formerly named PARSE-FILENAME .

 SETUSR  ( u -- )                                      A

     Set the current CP/M disk user number to u (0-15 for CP/M, 0-31
     for Z-System).  The previous user number is saved.

     See: RSTUSR

 WRITE-FILE  ( a-addr u fid -- ior )                   A 94

     Write u bytes from memory starting at a-addr to the disk file
     associated with the current file-handle.  If the disk was full
     or an error occured, ior is non-zero.

 WRITE-LINE  ( c-addr u fid -- ior )                   A 94

     Write a line of text c-addr u (255 maximum) followed by the CP/M
     line terminator (0D 0A hex) to the disk file associated with file-
     handle fid.  If the disk was full or an error occured, ior is non-
     zero.


2. Screen Files
---------------
In DX-Forth several screenfiles (default is 6) may be open at any one
time.  The most recently opened file is termed the "current" file.  All
screen/block words operate on the current file.

Screen/block numbers are valid only in the range 0 to 8191.  Only one
block buffer is allocated in memory, thus BLOCK and BUFFER always return
the same physical address.

DX-Forth also supports text source files.  See the section 'Tools' for
details.

 #SCREENS  ( -- +n )                                   S

     Return the number of screens (blocks) in the current screenfile.

 B/BUF  ( -- u )                                       S FIG

     A VALUE returning the number of bytes per block buffer.  Default
     is 1024.

     Note: Must be a multiple of 128 and a maximum of 1280.

 C/L  ( -- u )                                         S FIG

     A VALUE returning the number of characters per line in a screen
     block.  Default is 64.

 CLOSE  ( -- )                                         S

     Flush and close the current screenfile.  No errors are reported
     with this function.

 CLOSE-ALL  ( -- )                                     S

     Perform CLOSE on all open source files beginning with the current
     screenfile.  Any open text files are also closed with this
     function.

 FILE?  ( -- flag )                                    S

     Return true if the current screenfile is open otherwise return
     false.

 FILEBLOCKS  ( +n -- )                                 S

     Resize the current screenfile to +n blocks.  If n is less than the
     current size, the screenfile is truncated otherwise the file is
     extended and the new blocks are filled with blanks.

 FLOAD  ( +n "filename[.SCR]" -- )                     S

     Save the current screenfile specification then open the specified
     file and load block +n.  At completion of the load, close the file
     and restore the previous file.  If the filename does not include
     an extension then .SCR is assumed.  Screenfiles may be nested.

     Note: Read-only files cannot be opened with this function.

 GETFILENAME  ( "filename" -- c-addr u )               S

     Parse a filename string from the input stream returning c-addr u.
     An exception occurs if the string is empty.

 LOADED  ( +n1 +n2 c-addr u -- )                       S

     Save the current screenfile specification then open the file
     specified by c-addr u and load blocks +n1 thru +n2.  At completion
     close the file and restore the previous.  If the filename does not
     include an extension then .SCR is assumed.  Screenfiles may be
     nested.

     Note: Read-only files cannot be opened with this function.

 LOADFILE  ( -- c-addr u )                             S

     Return a string containing the name of the current sourcefile.
     If no sourcefile is open or the input source is the console,
     c-addr u is ambiguous.  Formerly named FNAME FILENAME .

     See: FILE?

 LOADLINE  ( -- u )                                    S

     Return the current line number of the text file being INCLUDEd.
     Starting line number is 1.

 OPEN  ( c-addr u -- ior )                             S

     Open the specified disk file for read/write as the current
     screenfile.  If an error occurs, ior is non-zero.  If the
     filename does not include an extension then .SCR is assumed.

     Note: Read-only files cannot be opened with this function.
     The programmer is responsible for closing or maintaining the
     previous current screenfile.

     See: SWAP-FILE CLOSE CLOSE-ALL

 SWAP-FILE  ( -- )                                     S

     Switch the current and 'swap' screenfiles.  SCR is preserved
     across swaps.

     Note: SWAP-FILE causes the current block buffer to be unassigned.
     The contents of the buffer, however, are not affected.

     See: FYI

 USING  ( "filename[.SCR]" -- )                        S

     Close the current screenfile.  Open or conditionally create the
     specified disk file for read/write as the current screenfile.  If
     the filename does not include an extension then .SCR is assumed.
     If the file cannot be opened/created then ABORT is performed.
     SCR is set to 0.

     Note: Read-only files cannot be opened with this function.
     The programmer is responsible for closing or maintaining the
     previous current screenfile.

     See: SWAP-FILE CLOSE CLOSE-ALL


3. Tools
--------

Note: These words are available only after the file TOOLS.SCR has been
loaded.

 (*                                                    I S

     Begin a block comment.  Parse and discard text delimited by the
     token *) .  If the parse area is exhausted before the delimiter
     is found refill the input buffer and resume the process.

     An ambiguous condition exists if the delimiter is not found and
     the parse area cannot be refilled.

     Note: (* is primarily intended for text files.  May be relocated
     to the kernel if/when it gains greater popularity.

 -TOOLS  ( -- )                                        S

     A marker word used for deleting the utilities and any words defined
     thereafter.  Typically used to gain extra System dictionary space.

 .S  ( -- )                                            S

     Display the values on the data and floating-point stacks.

 B  ( -- )                                             S

     Decrement variable SCR and list the screen.

     See: L N

 DELETE  ( "filename" -- )                             S

     Erase the specified file from disk.  DELETE must not be performed
     on an open file.

 DIR  ( "filename" -- )                                S

     List the current disk directory.  Filename if specified may
     include path and wildcards.

 DUMP  ( addr u -- )                                   S

     Dump u bytes of memory starting at the address addr.

 EDIT  ( | scr -- )                                    S

     Performs the same function as EDIT in the screenfile editor.  If
     the editor is not resident then EDITOR.SCR is first loaded.  If
     scr is not given then editing begins at the position where the
     last error occured.

 FYI  ( -- )                                           S

     "For Your Information".  Display information about the current
     forth environment including dictionary size, vocabularies, logged
     drive and open screenfiles.  Formerly named MAP .

 ICLOSE  ( -- )                                        S

     Close the current text file.

     INCLUDEd text files are automatically closed after loading.  If
     an error occurs or loading is interrupted (e.g. QUIT was executed),
     nested text files may remain open preventing external editing or
     cause difficulty loading ("too many files" error message).  Should
     this occur use ICLOSE or CLOSE-ALL to restore proper operation.

     Note: Performing ICLOSE without a preceding INCLUDE or INCLUDED
     may result in the current screenfile being closed without
     flushing.

     See: INCLUDE INCLUDED CLOSE-ALL

 INCLUDE  ( "filename[.F]" -- )                        S

     Compile the ascii text source file specified by the filename.
     If a filename extension is not included then .F is assumed.
     Text files may be nested.

     Note: Uses the default DTA buffer at address $80.

     See: ICLOSE

 INCLUDED  ( c-addr u -- )                             S

     Compile the ascii text source file specified by the filename
     given by c-addr u.  Text files may be nested.

     Note: Uses the default DTA buffer at address $80.

     See: ICLOSE

 INDEX  ( +n1 +n2 -- )                                 S FIG

     List line 0 of screens +n1 thru +n2 from the screenfile.  Line 0
     typically contains a comment indicating the contents of the screen.

     See: QX

 L  ( -- )                                             S

     List the screen specified by variable SCR.

     See: N B

 N  ( -- )                                             S

     Increment variable SCR and list the screen.

     See: L B

 QX  ( +n -- )                                         S

     Quick index.  Starting with screen +n, list line 0 of 60 sequential
     screens from the screenfile.  Line 0 typically contains a comment
     indicating the contents of the screen.

     See: INDEX

 RENAME  ( "oldfile" "newfile" -- )                    S

     Rename the specified disk file with a new name.  RENAME must not
     be performed on an open file.

 SHOW  ( +n1 +n2 -- )                                  S

     List screens +n1 through +n2 from the screenfile to the printer,
     formatted 3 screens to the page.  A form-feed character (0C hex) is
     output at the end of each page.

 VOCS  ( -- )                                          S

     List all vocabularies beginning with the most recent.

 WORDS  ( "pattern" -- )                               S

     Lists the names of forth words in the context wordlist beginning
     with the most recent.  If a pattern string is specified, only
     words whose names include "pattern" are listed.  Immediate words
     are preceded with a '#' character and system words with a '|'
     character.  fig-forth equivalent is VLIST.


4. DOS Interface
----------------

 CMDTAIL  ( -- c-addr u )                              A

     Return the string representing the command entered at the DOS
     prompt when the program was first initiated.

     Note: The returned string resides in a transient region and may be
     overwritten by subsequent operations.

 BDOS  ( DE u -- A )                                   A

     Perform CP/M BDOS call number u.  DE is the value passed to the
     DE register.  Return the contents of the A register.

     See: FDOS

 BIOS  ( BC u -- A )                                   A

     Perform CP/M BIOS call number u.  BC is the value passed to the
     BC register.  Return the contents of the A register.

     Note: CP/M 3 compatible.

 BIOSHL  ( DE BC u -- HL )                             A

     Perform CP/M BIOS call number u.  DE and BC are the values passed
     to the DE and BC registers respectively.  Return the contents of
     the HL register.

     Note: CP/M 3 compatible.

 DOSVER  ( -- minor major )                            A

     Return CP/M version number.

 FDOS  ( DE u -- HL A )                                A

     Perform CP/M BDOS call number u.  DE is the value passed to the
     DE register.  Return the contents of the HL and A registers.

     See: BDOS

 PC@  ( p-addr -- u )                                  A

     Perform the 8080 IN instruction on port address p-addr and return
     the value u.  The upper 8 bits of u is set to zero.  Fig-Forth
     equivalent is P@.

 PC!  ( u p-addr -- )                                  A

     Perform the 8080 OUT instruction sending the lower 8 bits of u to
     port address p-addr.  Fig-Forth equivalent is P!

 ZENV  ( -- addr | false )                             A

     Return the Z-System external Environment Descriptor address.
     If Z-System is not present return false.


5. Input/Output
---------------

 (D.)  ( d -- c-addr u )                               A

     Convert the signed double number d to a string c-addr u.
     Primitive for D.

     Note: The returned string resides in a transient region and may be
     overwritten by subsequent operations.

 CONSOLE  ( -- )                                       A

     Redirect KEY and EMIT to the console.

 SYS-VEC  ( -- addr )                                  A

     Return the address of the system vector & parameter table.

     offset      type  function            parameter        default

     0   vKEY?   xt    KEY?                -- flag          ?terminal
     2   vKEY    xt    KEY                 -- char          conin
     4   vEMIT   xt    EMIT                char --          conout *
     6   vCON    xt    CONSOLE out         char --          conout
     8   vLST    xt    PRINTER out         char --          lstout
     10  aINIT   addr  INIT patch          --               NOOP *
     12  aIDENT  addr  IDENTIFY patch      --               NOOP *
     14  aFNUMB  addr  FNUMBER patch       c-addr u -- ?|0  FALSE *
     16  reserved
     18  aNUMB   addr  NUMBER? patch       c-addr u -- ?|0  NUMBER?
     20  reserved
     22  reserved
     24  nUS     u     USER area size
     26  nPNO    u     HOLD buffer size
     28  reserved
     30  reserved

     * set according to mode or installed option

     Sizes are expressed in bytes unless otherwise noted.

 KEY  ( -- char )                                      A 94

     Receive the next character from the console.

 KEY?  ( -- flag )                                     A 94

     Return true if a console key has been pressed.  KEY is subsequently
     used to retrieve the character.  fig-Forth equivalent is ?TERMINAL.

 PRINTER  ( -- )                                       A

     Redirect EMIT to the printer.

 OUT  ( -- a-addr )                                    A FIG

     A USER variable that contains the number of characters output by
     EMIT or TYPE since the last CR.


6. Arithmetic and Stack
-----------------------

 -ROLL  ( xu ... x1 x0 u -- x0 xu ... x1 )             A

     Remove u.  Rotate xu ... x1 to the top of the stack pushing x0 to
     the position vacated by xu.  The reverse of ROLL.

 -ROT  ( x1 x2 x3 -- x3 x1 x2 )                        A

     Rotate the top stack item to the third position.  The reverse of
     ROT.

 2+  ( x1 -- x2 )                                      A 83 FIG

     Add two (2) to n1|u1 giving the sum n2|u2.

 2-  ( x1 -- x2 )                                      A 83

     Subtract two (2) to n1|u1 giving the sum n2|u2.

 ><  ( x1 -- x2 )                                      A

     Swap the high order byte (bits 8-15) with the low order byte
     (bits 0-7) of x1.

 FM/MOD  ( d n1 -- n2 n3 )                             A 94

     Divide double number d by single n1, giving the floored quotient
     n3 and the remainder n2.

 LSHIFT  ( x1 u -- x2 )                                A 94

     Perform a logical left shift of u bit-places on x1 giving x2.
     Put zero into the least significant bits vacated by the shift.

 M*  ( n1 n2 -- d )                                    A 94

     Multiply n1 by n2 giving the double result d.

 M*/  ( d1 n1 +n2 -- d2 )                              A 94

     Multiply double number d1 by single n1 producing the triple
     length intermediate result t.  Divide t by +n2 giving the
     double quotient d2.

 M+  ( d1 n -- d2 )                                    A 94

     Add single length number n to double d1, giving the sum d2.

 NIP  ( x1 x2 -- x2 )                                  A 94

     Drop the first item below the top of stack.

 NOT  ( x -- flag )                                    A 79

     Reverse the boolean value of x.  Functionally equivalent to 0= .

     Note: Do not confuse this function with FORTH-83 NOT which behaved
     as INVERT.

 RSHIFT  ( x1 u -- x2 )                                A 94

     Perform a logical right shift of u bit-places on x1 giving x2.
     Put zero into the most significant bits vacated by the shift.

 TUCK  ( x1 x2 -- x2 x1 x2 )                           A 94

     Copy the first (top) stack item below the second stack item.

 UMAX  ( u1 u2 -- u1 | u2 )                            A

     Return the greater of two unsigned numbers.

 UMIN  ( u1 u2 -- u1 | u2 )                            A

     Return the lesser of two unsigned numbers.


7. Conversion
-------------

 DPL  ( -- a-addr )                                    A 83

     A USER variable containing the number of places to the right of
     the decimal point following number input conversion.

     In DX-Forth DPL is incremented for each character successfully
     converted by >NUMBER.  Applications may use this feature to create
     custom number conversion routines.

     See: NUMBER?

 NUMBER?  ( c-addr u -- d true | false )               A

     Convert the case-insensitive string c-addr u to a double number
     according to the current base.  If successful, return double
     number d and a true flag.  A leading '-' character signifies a
     negative number.  If a punctuation character '.' occurs at the
     end of the string then DPL is 0 otherwise it is -1.  If conversion
     is unsuccessful or the string was empty or contained blanks then a
     false flag is returned and DPL is meaningless.

     See: DPL SYS-VEC

 UPCASE  ( c1 -- c2 )                                  A

     Convert the character c1 to its uppercase equivalent c2.

     Note: The name of this function is subject to change.

 UPPER  ( c-addr u -- )                                A

     Convert the character string c-addr u to uppercase.

     Note: The name of this function is subject to change.


8. Strings and Memory
---------------------

 +STRING  ( c-addr1 u1 c-addr2 u2 -- c-addr2 u3 )      A

     Append the string c-addr1 u1 to the end of string c-addr2 u2
     returning the resulting string c-addr2 u3.  It is the programmer's
     responsibility to ensure sufficient room is available at c-addr2
     to hold both strings.

 ,"  ( "ccc<">" -- )                                   S

     Parse the character string delimited by '"' and compile as a
     counted string.  The delimiter character may be included in the
     string by entering it twice.

     See: PARSE$

 /STRING  ( c-addr1 u1 n -- c-addr2 u2 )               94

     Truncate the string c-addr1 u1 by n characters.  The resulting
     string c-addr2 u2 begins at c-addr1+n and has a length u1-n.
     n may be negative.

 CAPS  ( -- )                                          A

     Causes the next occurrence of COMPARE or SEARCH to be performed as
     if all characters in the source and destination strings were
     uppercase.  Used in the form:

              ( c-addr1 u1 c-addr2 u2 ) CAPS COMPARE
              ( c-addr1 u1 c-addr2 u2 ) CAPS SEARCH

     Note: The effect of CAPS is temporary.  It is automatically reset
     by COMPARE SEARCH COLD, or when an error occurs and QUIT is
     executed.

 CELL-  ( a-addr1 -- a-addr2 )                         A

     Subtract the size in address units of a cell to a-addr1, giving
     a-addr2.

 COMPARE  ( c-addr1 u1 c-addr2 u2 -- -1 | 0 | 1 )      94

     Compare string c-addr1 u1 with string c-addr2 u2.  Return 0 if
     match, -1 if c-addr1 u1 is less than c-addr2 u2 or 1 if greater.

     See: CAPS

 MOVE  ( a-addr1 a-addr2 u -- )                        A 94

     Move u bytes from a-addr1 to a-addr2 without overlap.

 OFF  ( a-addr -- )                                    A

     Clear all bits of the cell at a-addr.  Equivalent to: 0 a-addr !

 ON  ( a-addr -- )                                     A

     Set all bits of the cell at a-addr.  Equivalent to: TRUE a-addr !

 PARSE$  ( char "ccc<char>" -- c-addr u )              S

     Parse ccc delimited by char and store the string (255 characters
     max) in a temporary buffer.  The delimiter character may be
     included in the string by entering it twice.

     Note: The returned string resides in a transient region which may
     be overwritten by subsequent operations.

     PARSE$ is used by S" .( and ," .  PARSE$ and WORD share the same
     buffer by default.  Simultaneous use is permitted provided the
     combined length of the strings does not exceed 255+31 chars.  As
     the buffer returned by WORD builds downwards, its length is limited
     to that of the returned string plus the count and trailing space
     characters.

 PLACE  ( c-addr1 u c-addr2 -- )                       A

     Store the string c-addr1 u as a counted string placed at c-addr2.
     An ambiguous condition exists if u is greater than 255 or the
     buffer at c-addr2 is less than u+1 characters.  The source and
     destination strings are permitted to overlap.

 S"  ( "ccc<">" -- )                                   I S 94
     ( -- c-addr u ) run-time

     Parse a string from the input stream delimited by '"' .  At
     runtime, leave the string address and count (255 characters
     maximum) on the stack.  The delimiter character may be included
     in the string by entering it twice.

     When interpreting, the string is placed in a transient region
     which may be overwritten by subsequent operations.

     See: PARSE$

 SCAN  ( c-addr1 u1 char -- c-addr2 u2 )               A

     Scan the string c-addr1 u1 for the character char.  Leave match
     address c-addr2 and length remaining u2.  If no match occurred
     then u2 is zero and c-addr2 is c-addr1 + u1.

 SEARCH  ( c-addr1 u1 c-addr2 u2 --                    A 94
           c-addr3 u3 -1 | c-addr1 u1 0 )

     Search string c-addr1 u1 for the occurence of string c-addr2
     u2.  If found, return -1 and the match address c-addr3 with
     u3 characters remaining.

     See: CAPS

 SKIP  ( c-addr1 u1 char -- c-addr2 u2 )               A

     Skip leading occurences of the character char in the string
     c-addr1 u1.  Leave the address of the first non-matching character
     c-addr2 and length remaining u2.  If no characters were skipped
     leave c-addr1 u1.

 TOGGLE  ( c-addr x -- )                               A

     Exclusive-or the character stored at c-addr with x.

 SLITERAL  ( c-addr1 u -- ) compilation                I S 94
           ( -- c-addr2 u ) run-time

     Compile the string c-addr u (maximum 255 characters) into the
     dictionary.  When later executed c-addr2 u is left on the stack.


9. Dictionary
-------------

 (NAME)  ( nfa -- c-addr u )                           S

     Return the string c-addr u representing the name of the forth word
     whose name field address is nfa.

     Note: The returned string resides in a transient region and may be
     overwritten by subsequent operations.

 -?  ( -- )                                            S

     Suppress redefinition and system compilation warnings for the next
     definition only.

     See: WARNING

 .ID  ( nfa -- )                                       S

     Display the name of the forth word whose name field address is
     nfa.  If the word is nameless (nfa is zero) then "[noname]" is
     displayed.  fig-FORTH equivalent is ID.

 .NAME  ( xt -- )                                      S

     Display the name of the forth word whose execution token address
     is xt.  If the word is nameless or xt invalid then "[noname]" is
     displayed.  If the word is an alias then the primary name is
     displayed.

 .WID  ( wid -- )                                      S

     Display the name associated with wordlist wid.  Wordlists may be
     nameless in which case "[noname]" will be displayed.  Formerly
     named .VOC .

     See: VOCABULARY W>NAME

 APPLICATION  ( -- )                                   S

     Place subsequent definitions into the Application dictionary.  The
     application dictionary holds words that may be executed by turnkey
     programs.  Equivalent to:  FALSE SYS !

     Note: APPLICATION is the default mode on boot-up or COLD.

     See: SYS SYSTEM

 BEHEAD  ( "name1" "name2" -- )                        S

     Search the first wordlist in the search order and make invisible
     the words between name1 and name2 inclusively.  Beheaded words
     will not be found in a wordlist search or displayed by WORDS.
     The behaviour of beheaded words is not affected.  An ambiguous
     condition exists if the names reside in protected dictionary.
     Formerly named EXCISE .

     See: CHECKING

 CHAIN  ( "name" -- )                                  S

     Append wordlist "name" to the base of the CURRENT wordlist.  An
     ambiguous condition exists if "name" does not correspond to a
     valid wordlist, is the same as or defined later than the CURRENT
     wordlist.  This function is subject to change.

 DP  ( -- a-addr )                                     A FIG

     A double USER variable containing pointers to the next free
     address in the application and system dictionaries.  e.g.

       DP @   ( -- appDP )
       DP 2@  ( -- sysDP appDP )

 EMPTY  ( -- )                                         S

     Delete all definitions created since the last execution of COLD
     or FREEZE.  Wordlist is set to FORTH.

 FORGET  ( "name" -- )                                 S 83 FIG

     If word "name" is found in the compilation wordlist, delete it
     and all words added to the dictionary after "name" was defined,
     regardless of their wordlist.  An ambiguous condition exists if
     "name" is an alias or the word is located in the protected
     dictionary.

     See: CHECKING

 FREEZE  ( -- )                                        S

     Protect the current state of the dictionary.  Existing definitions
     will no longer be able to be erased.

     See: CHECKING

 LIMIT  ( -- addr )                                    A FIG

     A CONSTANT that returns the upper limit address of the application
     dictionary and the start of the System dictionary.

     LIMIT for TURNKEY applications will be the upper memory limit
     currently used by the forth compiler.

 MARKER  ( "name" -- )                                 S

     A defining word used in the form:
              MARKER name
     Typically used to mark the beginning of an application which may
     later be removed by executing FORGET name.  "name" is placed in
     the System dictionary.

     Note: MARKER differs from the Forth-94 specification in that
     "name" has no effect when executed.

 N>NAME  ( nfa1 -- nfa2 | 0 )                          S

     Given the name field address of a word, return the nfa of the
     previous word in the wordlist.  If the end of the wordlist is
     reached then 0 is returned.

 REMEMBER  ( xt -- )                                   S

     Append execution token xt to the REMEMBER list.

     When words are discarded or the dictionary is otherwise reduced,
     xt's in the REMEMBER list that lie outside the new dictionary
     boundary will be executed beginning with the most recent.
     Typically xt represents a function whose purpose is to restore
     critical system values to their previous state.  Executed xt's
     are automatically removed from the REMEMBER list.

     Note: Functions executed by the REMEMBER list run only after the
     new dictionary boundary has been established.  Consequently these
     functions may be residing in free memory when executed.

 SYS  ( -- a-addr )                                    A

     A VARIABLE that determines the compilation dictionary.  Definitions
     will be compiled to the system dictionary if SYS is non-zero and to
     the application dictionary if zero.

     See: APPLICATION SYSTEM

 SYSTEM  ( -- )                                        S

     Place subsequent definitions into the System dictionary.  The
     System dictionary holds the compiler and other support functions
     not generally required for turnkey applications.
     Equivalent to:  TRUE SYS !

     See: SYS APPLICATION

 VOC-LINK  ( -- a-addr )                               S FIG

     A USER variable containing a pointer to the most recently defined
     wordlist.

 VOCABULARY  ( "name" -- )                             S 83

     Create a new empty word list.  When "name" is later executed
     replace the first wordlist in the search order with the wordlist
     associated with "name".

 W>NAME  ( wid -- nfa | 0 )                            S

     Return the name field address of the most recently defined word
     in wordlist wid.  If the wordlist is empty then zero is returned.

 WARNING  ( -- a-addr )                                S

     A VARIABLE that controls warning messages.  When set to zero,
     word redefinition and System compilation warnings are disabled.
     Users may set WARNING to TRUE or FALSE (e.g. using ON or OFF )
     - other values must not be used.

     See: -?


10. Facility
------------

 AT-XY  ( x y -- )                                     A C 94

     Move the cursor to the specified coordinates relative to the
     current text window.

 BEEP  ( -- )                                          A

     Generate a bell sound.

 CLEAR-LINE  ( -- )                                    A C

     Delete all characters from the current cursor position to the end
     of the line.  The cursor position remains unchanged.

 DELETE-LINE  ( -- )                                   A C

     Delete the line at the current cursor position.  All subsequent
     lines are moved up one position.  An empty line appears at the
     bottom of the screen.

 EXIT-VIDEO  ( -- )                                    A C

     Send video terminal reset sequence.

 HIGHLIGHT  ( -- )                                     A C

     Begin standout video mode (usually reverse or bright).

 INIT-VIDEO  ( -- )                                    A C

     Send video terminal initialisation sequence.

 INSERT-LINE  ( -- )                                   A C

     Insert an empty line at the current cursor position.  All
     subsequent lines in the text window are moved down one position.
     The bottom line is lost.

 MS  ( u -- )                                          A C 94

     Delay u milliseconds.

     Note: The accuracy of this function is determined by the 16-bit
     value at memory location 292 ($0124).  The default value is 4
     which assumes a real 4MHz Z80 CPU.  Change the value by manually
     patching the memory location, or using INSTALL.COM.  With the
     correct value installed the following should produce a 10 second
     delay:  BEEP 10000 MS BEEP

 NORMAL  ( -- )                                        A C

     End standout video mode.

 PAGE  ( -- )                                          A C 94

     For the console, clear the text screen window and place the cursor
     at the upper left; otherwise output a formfeed character (0C hex).

     See CONSOLE PRINTER.


11. Miscellaneous
-----------------

 'NEXT  ( -- addr )                                    A

     Return the address of the centralized NEXT routine - the forth
     "address interpreter".

 'SOURCE  ( -- a-addr )                                S

     A double variable containing the current parameters for SOURCE.
     'SOURCE 2@ is the equivalent of SOURCE.

 (EXIT)  ( -- )

     Run-time prodecure compiled by EXIT.  Exit the current colon
     definition and return control to the calling definition.

 -->  ( -- )                                           I S 83 FIG

     Continue interpretation on the next sequential block.  May be
     used within a colon definition that crosses a block boundary.

@EXECUTE  ( i*x a-addr -- i*y )                        A

     Execute xt located at address a-addr.  If xt is zero then no
     action is performed.  Other stack effects are due to the word
     executed.

     Named PERFORM in some Forth implementations.

 ADDR  ( "name" -- a-addr )                            I S

     "address of".  Return the data field address of the word "name".

     An ambiguous condition exists if "name" was not created by VALUE
     DEFER CREATE VARIABLE 2VARIABLE CONSTANT 2CONSTANT and other
     functions as may be specified.

     Named &OF or & in some Forth implementations.

 AKA  ( "oldname" "newname" -- )                       S

     "Also Known As".  Create an alias name "newname" for existing word
     "oldname".  If oldname was immediate then newname will be
     immediate.

     Note: In DX-Forth aliases consume only header space, and the xt of
     an alias is the same as the xt of the original word.  The function
     appears in other Forth implementations albeit with different names
     and usage e.g. SYNONYM ALIAS .

 BETWEEN  ( n1|u1 n2|u2 n3|u3 -- flag )                A

     Perform a comparison of a test value n1|u1 with a lower limit
     n2|u2 and an upper limit n3|u3, returning true if either (n2|u2
     <= n3|u3 and (n2|u2 <= n1|u1 and n1|u1 <= n3|u3)) or (n2|u2 >
     n3|u3 and (n2|u2 < n1|u1 or n1|u1 < n3|u3)) is true, returning
     false otherwise.  An ambiguous condition exists if n1|u1, n2|u2,
     and n3|u3 are not all the same type.

     This is similar to WITHIN with the exception that the limits are
     inclusive.

 BUILD  ( xt "name" -- )                               S

     Skip leading space delimiters.  Parse name delimited by a space.
     Create a definition for name with the execution semantics specified
     by xt.  If the data-space pointer is not aligned, reserve enough
     data space to align it.  The new data-space pointer defines name's
     data field.  BUILD does not allocate data space in name's data
     field.  When name is executed name's data field address is placed
     on the data stack and execution proceeds according to the semantics
     given by xt.

     BUILD provides an alternative to CREATE ... DOES> .  Typical use:

         SYSTEM
         : CONSTANT  ['] @  BUILD , ;
         APPLICATION

     BUILD may be used outside a definition e.g.

         \ adapted from a posting by "Bee" on c.l.f.

         :NONAME ( c-addr -- )
           C@ BASE @ >R BASE ! U. R> BASE ! ; ( xt)

         ( xt)
         DUP BUILD .B ( u -- )  2 C,
         DUP BUILD .O ( u -- )  8 C,
         DUP BUILD .D ( u -- ) 10 C,
             BUILD .H ( u -- ) 16 C,

 BYE  ( -- )                                           S FIG 94

     Perform CLOSE-ALL and EXIT-VIDEO then exit to the operation system
     with 0 RETURN.

 CASE  ( -- )                                          I S 94

     Mark the start of a CASE construct.  Used in the form:

          CASE  ( x1 -- )
            x2  OF ... ENDOF
            x3  OF ... ENDOF
            x1  ...
            x1  ENDCASE

 CATCHER  ( -- a-addr )                                A

     A USER variable containing the last exception handler.  If the
     contents is zero no more exception frames (installed by CATCH)
     are present.

 CHAR  ( -- c )                                        S 94

     Parse the next word in the input stream and return the ASCII
     value of the first character.

 COLD  ( -- )                                          A FIG

     Cold restart the forth environment or turnkey application.

 COMPILE                                               S 83

     COMPILE is obsolete and should not be used directly in
     applications.  COMPILE is a factor of POSTPONE and is present in
     the dictionary as a named word for error handling purposes.

 DEFER  ( "name" -- )                                  S

     Creates a deferred word whose action word may be subsequently
     altered using the sequence: ' ccc IS name

     Deferred words are used to create forward references that will
     be resolved later.  Attempting to execute an unresolved deferred
     word will result in an abort with an error message.

     Note: The current action of a deferred word may be obtained
     using

       ' >BODY @  ( "name" -- xt )  or
       ADDR @     ( "name" -- xt )

     See: IS

 DXFORTH  ( -- minor major )                           A

     Return the DX-Forth version number.

 ENDCASE  ( x -- )                                     I S 94

     Mark the end of a CASE construct.  Discard x.

     See CASE OF ENDOF.

 ENDOF  ( -- )                                         I S 94

     Mark the end of an OF ENDOF pair.

     See CASE OF ENDCASE.

 EVALUATE  ( c-addr u -- )                             S 94

     Save the current input source specification.  Make the string
     described by c-addr u both the input source and input buffer,
     set >IN to zero, and interpret.  When the parse area is empty,
     restore the prior input source specification.

 FDB  ( -- a-addr )                                    S

     Get the address of the next free file descriptor block.  If no more
     free descriptors exist the function aborts with a "too many files"
     error message.

 INTERPRET  ( -- )                                     S FIG

     Successively interpret forth text from the input stream until
     exhausted, compiling or executing depending upon STATE.  If an
     exception occurs the process aborts with an error message.

 IS  ( xt "name" -- )                                  I S

     Used in the form:
              ' ccc IS name
     where "name" is a deferred word and ccc defines the new behaviour.

     See: DEFER

 NOOP  ( -- )                                          A

     No operation.  Typically used to set a null action e.g.

              ' NOOP IS XXX

     where XXX is a DEFERed word.

 OF  ( x1 x2 -- )                                      I S 94

     Mark the start of an OF ENDOF pair.  If x1 = x2, discard both
     values and perform the sequence between OF and ENDOF.  Execution
     continues after ENDCASE.  If x1 <> x2, discard x2 and continue
     after the corresponding ENDOF.

     See CASE ENDOF ENDCASE.

 PAUSE  ( -- )                                         A

     Provides support for multitasking applications.  When the
     multitasker is loaded and enabled, PAUSE passes control to the next
     task.  Refer to the multitasking documentation for further details.

     Note: PAUSE is automatically executed by KEY? KEY EMIT .

 R0  ( -- a-addr )                                     A FIG

     A USER variable that contains the address of the top of the return
     stack.

 RETURN  ( x -- )                                      A

     Restore the initial drive path and video mode.  Return to DOS with
     exit code x.  Open files are not closed.

     See: BYE

 RP!  ( addr -- )                                      A

     Set the return stack pointer to addr.

 RP@  ( -- addr )                                      A FIG

     Return the address of the current return stack pointer.

 S0  ( -- a-addr )                                     A FIG

     A USER variable that contains the address of the top of the
     data stack.

 SAVE  ( "filename[.COM]" -- )                         S

     Save the current forth system image to disk including any new
     definitions created.

     See: TURNKEY TURNKEY-SYSTEM

 SP!  ( addr -- )                                      A

     Set the data stack pointer to addr.

 SP@  ( -- addr )                                      A FIG

     Return the address of the current data stack pointer.

 TURNKEY  ( "bootword" "filename[.EXE]" -- )           S

     Save a standalone application to disk using the specified filename.
     When the application is subsequently run, execution begins with
     bootword and ends with  0 RETURN  if successful, or  1 RETURN  if
     ABORT , ABORT" or an uncaught exception was encountered.

     Note: The System dictionary and word headers are not saved and are
     therefore unavailable to the application.

     See: SAVE TURNKEY-SYSTEM

 TURNKEY-SYSTEM  ( "bootword" "filename[.EXE]" -- )    S

     Save a standalone application including the System dictionary to
     disk using the specified filename.  When the application is
     subsequently run, execution begins with bootword and ends with
     0 RETURN  if successful, or  1 RETURN  if ABORT , ABORT" or an
     uncaught exception was encountered.

     TURNKEY-SYSTEM is provided for applications that require access
     to words in the System dictionary.

     See: SAVE TURNKEY

 UNNEST  ( -- ) ( R: nest-sys -- )                     A

    Discard the calling definition specified by nest-sys.  Before
    exiting the current definition, a program shall remove any
    parameters the calling definition had placed on the return stack.
    An ambiguous condition exists if the current or calling definition
    uses locals.

 UNUSED  ( -- u )                                      A 94

     Return the amount of space in bytes remaining in the region
     addressed by HERE.

     Note: The calculation includes a 255 byte safety margin.
     Applications should take into account the regions used by the
     pictured numeric string buffer and PAD.

 UP  ( -- a-addr )                                     A

     A VARIABLE that contains the base address of the current USER
     area.

 USER  ( +n "name" -- )                                S FIG

     A defining word used in the form:
              +n USER name
     which creates a USER variable "name".  +n is the offset within
     the user area where the value for "name" is stored.  Executing
     "name" leaves the address of the variable in the user area.

     USER variables with offsets 44 decimal and higher are available
     for use by applications (DX-Forth 1.2 for CP/M onwards).

     Note: Offsets numbers are subject to change.  When an offset
     is required by an application, it should be determined at
     compile-time e.g.  [ BASE UP @ - ] LITERAL  will return the
     offset for BASE .

 WITHIN  ( x1 x2 x3 -- flag )                          A 94

     Return true if x3 lies within the range x1 to x2-1, otherwise
     return false.  x may be signed or unsigned.

 Y/N  ( -- flag )                                      A

     Display '(y/n) N' and wait for a single console key.  Return
     true if the 'Y' or 'y' key was pressed or false otherwise.

 [CHAR]  ( -- c )                                      I S 94

     Parse the next word in the input stream and compile the ASCII
     value of the first character as a literal.

 [DEFINED]  ( "name" -- flag )                         I S

     Parse the next word in the input stream.  Return a true flag if
     word was defined in the dictionary.

 [IF]  [ELSE]  [THEN]                                  I S 94

     These are the equivalents of IF ELSE THEN but may be used outside
     a definition.

 [UNDEFINED]  ( "name" -- flag )                       I S

     Parse the next word in the input stream.  Return a true flag if
     word was not defined in the dictionary.

 \  ( -- )                                             I S 94

     Skip the rest of the line and resume interpretation at the
     beginning of the next line.

 \\  ( -- )                                            I S

     Parse and discard the remainder of the parse area.  If the source
     is a text file the remainder of the file is discarded.


12. Floating Point
------------------
By default DX-Forth uses single precision software floating point.
A real number occupies two cells (4 bytes) with a maximum precision
of 7 digits and a dynamic range of 5E-39 to 1E38.

The forth interpreter recognizes a number as floating point if it is
in decimal mode and contains an exponent identifier 'E' e.g.  1.0E
3.141952E  1e-12

DX-Forth for CP/M uses the data stack for floating point operations
(aka common stack model).

Notes:

- In the common stack model, variables FS0 and FSP are dummies.  Their
  contents are initialized as for S0 but are otherwise unused.

- Floating point display words and their primitives use the pictured
  numeric string buffer.

- Display words that specify the number of places after the decimal
  point may use the value -1 to force compact display mode.


 (F.)  ( r n -- c-addr u )                             A

     Convert real number r to string c-addr u in fixed-point notation
     with n places to the right of the decimal point.  Primitive used
     by F. F.R

 (FE.)  ( r n -- c-addr u )                            A

     Convert real number r to string c-addr u in engineering notation
     with n places right of the decimal point.  Primitive used by FE.
     FE.R

 (FS.)  ( r n -- c-addr u )                            A

     Convert real number r to string c-addr u in scientific notation
     with n places right of the decimal point.  Primitive used by FS.
     FS.R

 (G.)  ( r n -- c-addr u )                             A

     Convert real number r to string c-addr u with n places right of the
     decimal point.  Fixed-point is used if the exponent is in the range
     -4 to 5 otherwise use scientific notation.  Primitive used by G.R
     G.

 >FLOAT  ( c-addr u -- r true | false )                A 94

     Convert the string c-addr u to a real number.  If successful,
     return the real number r and true or false otherwise.

     Note: A zero length string or a string with leading blanks will
     return the real number 0.0E and true.

 D>F  ( d -- r )                                       A 94

     Convert the double number to its real number equivalent.

 F,  ( r -- )                                          S

     Reserve one floating-point cell of data space and store r in the
     cell.

 F.  ( r -- )                                          A

     Display r in floating-point notation followed by a space.  Non-
     essential zeros and signs are removed.

 F.R  ( n u -- ) or ( r n u -- )                       A

     Display r in fixed-point notation right-justified in a field width
     u with n places right of the decimal point.

 F!  ( r f-addr --  )                                  A 94

     Store r at f-addr.

 F*  ( r1 r2 -- r3 )                                   A 94

     Multiply r1 by r2, giving the product r3.

 F**  ( r1 r2 -- r3 )                                  A 94

     Raise r1 to the power r2.

 F+  ( r1 r2 -- r3 )                                   A 94

     Add r1 to r2, giving the sum r3.

 F-  ( r1 r2 -- r3 )                                   A 94

     Subtract r2 from r1, giving the difference r3.

 F.  ( r -- )                                          A

     Display r in floating-point notation followed by a space.  Non-
     essential zeros and signs are removed.

 F.R  ( n u -- ) or ( r n u -- )                       A

     Display r in fixed-point notation right-justified in a field width
     u with n places right of the decimal point.

 F/  ( r1 r2 -- r3 )                                   A 94

     Divide r1 by r2, giving the quotient r3.

 F0<  ( r -- flag )                                    A 94

     Return true if r is less than zero, or false otherwise.

 F0=  ( r -- flag )                                    A 94

     Return true if r is equal to zero, or false otherwise.

 F<  ( r1 r2 -- flag )                                 A 94

     Return true if r1 is less than r2, or false otherwise.

 F>D  ( r -- d )                                       A 94

     Convert the integer part of r to its double number equivalent.

 F@  ( f-addr -- r )                                   A 94

     Return the value of the real number stored at f-addr.

 FABS  ( r1 -- r2 )                                    A 94

     Return the absolute value of r1.

 FATAN  ( r1 -- r2 )                                   A 94

     r2 is the radian angle whose tangent is r1.

 FCONSTANT  ( r -- ) compilation                       A 94
            ( -- r ) run-time

     Define a floating point constant having the value r.

 FCOS  ( r1 -- r2 )                                    A 94

     r2 is the cosine of the radian angle r1.

 FDP  ( -- a-addr )                                    A

     A VARIABLE that controls floating decimal point display.  If zero
     then trailing decimal points are not shown; if non-zero a decimal
     point is always shown.  Default is FDP ON.

 FDROP  ( r --  )                                      A 94

     Remove r from the stack.

 FDUP  ( r -- r r )                                    A 94

     Duplicate r.

 FE.  ( r -- )                                         A

     Display r in engineering notation followed by a space.  Non-
     essential zeros and signs are removed.

 FE.R  ( r n u -- )                                    A

     Display r in engineering notation right-justified in a field width
     u with n places to the right of the decimal point.

 FEXP  ( r1 -- r2 )                                    A 94

     Raise e to the power r1, giving r2.

 FLITERAL  ( r -- ) compilation                        A 94
           ( -- r ) run-time

     Compile r into the dictionary.  When later executed r is left on
     the stack.

 FLN  ( r1 -- r2 )                                     A 94

     r2 is the natural logarithm of r1.

 FLOOR  ( r1 -- r2 )                                   A 94

     Round r1 to an integral value using the "round toward negative
     infinity" rule, giving r2.

 FMAX  ( r1 r2 -- r3 )                                 A 94

     r3 is the maximum of r1 and r2.

 FMIN  ( r1 r2 -- r3 )                                 A 94

     r3 is the minimum of r1 and r2.

 FNEGATE  ( r1 -- r2 )                                 A 94

     Negate r1, giving r2.

 FOVER  ( r1 r2 -- r1 r2 r1 )                          A 94

     Place a copy of r1 on top of the stack.

 FRANDOM  ( r1 -- r2 )                                 A

     If r1 is a positive non-zero number, return a psuedo-random number
     r2 uniformly distributed in the range 0.0E to (but not including)
     1.0E.  If r1 is zero, return the last random number generated.  If
     r1 is negative, r1 is used to re-seed the random number generator.

 FROT  ( r1 r2 r3 -- r2 r3 r1 )                        A 94

     Rotate r1 to the top of the stack.

 FROUND  ( r1 -- r2 )                                  A 94

     Round r1 to an integral value using the "round to nearest" rule,
     giving r2.

 FS.  ( r -- )                                         A

     Display r in scientific notation followed by a space.  Non-
     essential zeros and signs are removed.

 FS.R  ( r n u -- )                                    A

     Display r in scientific notation right-justified in a field width
     u with n places to the right of the decimal point.

 FS0  ( -- a-addr )                                    A

     A USER variable that contains the address of the top of the
     separate floating point stack.

     Note: Has no function in the common stack floating point model

 FSIN  ( r1 -- r2 )                                    A 94

     r2 is the sine of the radian angle r1.

 FSP  ( -- a-addr )                                    A

     A VARIABLE that returns the address of the current separate
     floating point stack pointer.

     Note: Has no function in the common stack model

 FSQRT  ( r1 -- r2 )                                   A 94

     r2 is the square root of r1.

 FSWAP  ( r1 r2 -- r2 r1 )                             A 94

     Exchange the top two floating point numbers.

 FVARIABLE  ( -- ) compilation                         A 94
            ( -- f-addr ) run-time

     Define a floating point variable.

 G.  ( r -- )                                          A

     Display real number r in floating point notation followed by a
     space.  If the exponent is outside the range -4 to 5 then
     scientific notation is used.  Non-essential zeros and signs are
     removed.

 G.R  ( r n u -- )                                     A

     Display real number r followed by a space.  Floating-point is used
     if the exponent is in the range -4 to 5 otherwise use scientific
     notation.  Non-essential zeros and signs are removed.

 MAX-PRECISION  ( -- u )                               A

     A CONSTANT returning the implementation-defined maximum PRECISION.

     See: SET-PRECISION

 PI  ( -- r )                                          A

     An FCONSTANT that returns the value for "pi" (3.141593..)

 PRECISION  ( -- u )                                   A 94

     Return the number of significat digits currently used by F. F.R
     FS. FS.R

 REPRESENT  ( r c-addr n1 -- n2 flag1 flag2 )          A 94

     DX-Forth uses an enhanced REPRESENT.  It follows the Forth-94
     definition with the following extensions:

     - if n1 is zero the entire significand of r is rounded to one or
       zero following the system's rounding rule; if n1 is negative
       then r is rounded to zero.
     - the buffer size allocated at c-addr shall be the greater of n1
       or MAX-PRECISION.

     See:
     ftp://ftp.taygeta.com/pub/Forth/Applications/ANS/Represent_30.txt

 SET-PRECISION  ( u -- )                               A 94

     Set the number of significant digits currently used by F. F.R FS.
     FS.R.  In DX-Forth, the number of significant digits is limited
     to MAX-PRECISION.


13. Compiler Security
---------------------

 !CSP  ( -- )                                          S FIG

     Save the current data stack position.

     See: ?CSP

 +BAL  ( -- )                                          S

     Increment the current control structure balance level.

 -BAL  ( -- )                                          S

     Decrement the current control structure balance level.

 ?BAL  ( flag -- )                                     S

     Issue an error message 'definition unbalanced' and abort if flag
     is true and CHECKING is not zero.

     See: CHECKING

 ?CSP  ( -- )                                          S FIG

     Issue an error message 'definition unbalanced' and abort if the
     current data stack position does not match the value saved by !CSP
     and CHECKING is not zero.

     See: CHECKING

 ?COMP  ( -- )                                         S FIG

     Issue an error message 'compilation only' and abort if not
     compiling.

 ?EXEC  ( -- )                                         S FIG

     Issue an error message 'execution only' and abort if not
     executing.

 ?STACK  ( -- )                                        S FIG

     Issue an error message and abort if a stack underflow or overflow
     occurs.  Data, return and floating point stack (if present) are
     tested.

     Note: A non-System version of ?STACK is provided in MISC.SCR for
     turnkey applications requiring run-time stack checking.

 CHECKING  ( -- a-addr )                               S

     A VARIABLE that controls compiler security - including control
     structure balance, data stack level and protected dictionary.
     If the contents are zero, checking is disabled.  Default is
     CHECKING ON.

     See: ?BAL ?CSP BEHEAD FORGET

 CSP  ( -- a-addr )                                    S FIG

     A VARIABLE containing the current data stack position saved by
     !CSP .

 SMUDGE  ( -- )                                        S FIG

     Toggle the 'smudge' bit in the header of the last defined word.
     If the smudge bit is set, the definition will not be found during
     a dictionary search.


14. Control Flow Stack
----------------------

In DX-Forth the control-flow stack is implemented on the data stack.
COND ... THENS is from Wil Baden.  CS-DROP CS-PUSH CS-POP CS-MARK
CS-TEST are available when the 'cfs' equate in the kernel source is
enabled.  See MISER.SCR for example of use.

 <MARK  ( C: -- dest )                                 S 83

     This function is not provided.  In DX-Forth use  POSTPONE BEGIN
     instead.

 <RESOLVE  ( C: dest -- )                              S 83

     Compile a backward branch address in the dictionary using the
     location left by BEGIN .  Formerly named BACK .

 >MARK  ( C: -- orig )                                 S 83

     Reserve space in the dictionary for a forward branch address
     to be later resolved by THEN .  Formerly named FORWARD .

 >RESOLVE  ( C: orig -- )                              S 83

     This function is not provided.  In DX-Forth use  POSTPONE THEN
     instead.

 AHEAD  ( C: -- orig )                                 S 94

     Put the location of a new unresolved forward reference orig
     onto the control flow stack.  Similar to IF but compiles an
     unconditional forward branch.

 COND  ( C: -- mark )                                  I S

     Place a marker on the control-flow stack.  The semantics are
     incomplete until the structure is resolved, e.g., by THENS .

     See: THENS

 CS-PICK  ( C: xu..x0 -- xu..x0 xu ) ( S: u -- )       S 94

     Remove u.  Place a copy of item xu on top of the control-flow
     stack.

 CS-ROLL  ( C: xu..x0 -- xu-1..x0 xu ) ( S: u --  )    S 94

     Remove u.  Rotate item xu to the top of the control-flow stack.

 CS-DROP  ( C: x -- )                                  S

     Remove the top item from the control-flow stack.

 CS-PUSH  ( C: xu..x1 x0 -- x0 xu..x1 )                S

     Rotate items on the control-flow stack such that the top item
     becomes the bottom.  An ambiguous condition exists if the control-
     flow stack is empty before CS-PUSH is executed.

 CS-POP  ( C: xu xu-1..x0 -- xu-1..x0 xu )             S

     Rotate items on the control-flow stack such that the bottom item
     becomes the top.  An ambiguous condition exists if the control-
     flow stack is empty before CS-POP is executed.

 CS-MARK  ( C: -- x )                                  S

     Place a marker on the control-flow stack.  A marker occupies the
     same width as an orig|dest but is distinguishable using CS-TEST.

 CS-TEST  ( C: x -- x ) ( S: -- flag )                 S

     Return a true flag if x is an orig|dest, or false if a marker.
     x is not altered or removed.

     If the control-flow stack is implemented using the data stack,
     flag shall be the topmost item on the data stack.

 THENS  ( C: mark orig0 -- )                           I S

     Resolve zero or more orig references on the control-flow stack
     using THEN.  A marker terminates the process and is itself
     consumed.  Typically used with COND.

     See: COND

