DX-Forth for CP/M
-----------------

This is the documentation for DX-Forth.  It is divided into two parts:

- A walk-through that introduces new users (even those without
  previous Forth experience) to a few concepts and illustrates some of
  DX-Forth's special features.  However, no attempt is made to teach
  Forth - for this, get hold of an introductory text such as:

    "Forth Programmer's Handbook", Conklin & Rather
    "Programming Forth", Stephen Pelc
    "And so Forth...", J.L. Bezemer

- A technical section for prospective DX-Forth programmers.  It assumes
  the reader has some familiarity with the Forth language programming.

For a detailed listing of DX-Forth words and their use, see DXFORTH.GLO.


Contents:
---------

 1.  Introduction

  1.1  Overview
  1.2  Distribution files
  1.3  Acknowledgments
  1.4  Legal
  1.5  Installation
  1.6  Getting started
  1.7  Source files
  1.8  Screen editor
  1.9  Resident text file editor
 1.10  Command-line interface
 1.11  Machine code assembler
 1.12  Increasing System space
 1.13  Further suggestions
 1.14  Error messages

 2.  Programming reference

  2.1  File system
  2.2  Application and System words
  2.3  Executing applications
  2.4  No Warm-Boot option
  2.5  User Patch area
  2.6  Overlays
  2.7  Multitasking
  2.8  User variables
  2.9  System vectors
 2.10  Deferred words
 2.11  Search order
 2.12  Compiler security
 2.13  Exception handling
 2.14  Exception codes
 2.15  ZINS Routine

 3.  DX-Forth extensions

  3.1  END BREAK
  3.2  OF COND CONT
  3.3  BUILD


1.  Introduction

1.1  Overview

DX-Forth is a Forth language compiler and development system
for CP/M-80 and compatible disk operating systems including
Z-System.  It is intended to be a complete, easy to use,
programming tool for the creation of CP/M applications.

Features include:

 - ANS-FORTH Standard (FORTH-94) *
 - Fast direct-threaded code
 - Generate turnkey applications without compiler overhead
 - Fast floating point and trigonometric functions
 - Forth-94 file I/O
 - DOSLIB application library
 - Multitasking
 - ANS locals
 - Overlays for large applications
 - 8080/85/Z80 Forth assembler for CODE words
 - Full source code included
 - Video terminal functions, installable for most terminals
 - DU: style filenames for access to all CP/M user areas
 - Z-System (ZCPR) support through ZENV function
 - Program error return code for CP/M-3 and Z-System

* DX-FORTH 4 generally follows the FORTH-94 Standard but
  does not seek to be strictly compliant.


1.2  Distribution files

See FILES.TXT


1.3  Acknowledgments

No software is written in a vacuum; therefore the author wishes to
gratefully acknowledge all those in the CP/M and Forth communities who
have generously made their source code available for public scrutiny.
Without these to serve as a starting point and source for ideas,
DX-Forth would not have been written.


1.4  Legal

DX-Forth and all the files in this distribution (apart from excerpts
taken from the FORTH-83 and ANS-FORTH documents) are hereby placed into
the PUBLIC DOMAIN by the author.

DX-Forth is an experimental software and is provided without support or
warranty.  The author makes no guarantee as to fitness for purpose, nor
assumes liability for any error, omission, damage or loss caused by the
use of DX-Forth.  Anyone wishing to use this software does so entirely
at their own risk.


1.5  Installation

Installation customises DX-Forth or compiled turnkey applications
to suit the characteristics of the user's video terminal, machine
CPU speed and arrow keys.

                             IMPORTANT

When distributing a DX-Forth application that makes use of any of
the following functions:

   PAGE  AT-XY  CLEAR-LINE  BOLD  NORMAL  INSERT-LINE
   DELETE-LINE  INIT-VIDEO  EXIT-VIDEO  MS

you *must* include INSTALL.COM and INSTALL.DTA with the distribution
otherwise users will be unable to customise the application for
their hardware.

To install for your terminal/machine, run INSTALL.COM as follows.

     A> INSTALL FORTH.COM   (or other DX-Forth executable)

You will be presented with several options:

     1) Terminal selection

     Select from a number of video terminals, or if Z-System is
     present, the TermCap currently defined in memory.

     If your terminal is not listed try another make as manufacturers
     often use the same control codes.  If no definition works, you
     will need to create a custom definition for your terminal.  At
     present INSTALL.COM doesn't have this capability but there is a
     solution.

     DX-Forth terminal data file INSTALL.DTA is fully compatible
     with terminal data files from Borland Turbo Pascal/Modula2 and
     the public domain PD-GINST program.  Any of these can be used to
     create custom terminal definitions.  Refer to the instructions
     that came with Turbo Pascal/Modula2.  If using PD-GINST it
     should be run on itself i.e.

          A> PD-GINST  PD-GINST.COM

     Once the new terminal entry has been created, rename the data
     file to INSTALL.DTA and run DX-Forth INSTALL.COM as before.

     NOTE: If the terminal is changed, the CPU speed will be reset
     to 4 MHz (or the value defined by ZENV in the case of Z-System)
     and you will have the option to change it.

     2) CPU speed

     Enter the speed of the computer's CPU to the nearest MHz (1-8191).
     The value affects the accuracy of the MS function - which in turn
     is used by WORDS and other tools.  See MS in the glossary for
     further details.

     Address        Default value    Size
     -------        -------------    ----
     292 (0124h)    4                Word

     3) Time delays

     A delay is usually sent after a clear screen, cursor motion or
     clear to end-of-line sequence to ensure subsequent characters
     sent to the terminal from being lost.  Delays between 0 and 255
     milliseconds are available.  If a fast terminal or computer
     with memory mapped video is being used then all delays may be
     set to 0 mS.  Most terminals however will require a delay after
     a screen clear.  A value of 50 mS should be sufficient.

     NOTE: The CPU speed must be correctly set for the time delays
     to be accurate.

     4) Key codes

     Many keyboards have arrow keys (up, down, right, left) which
     produce a code when pressed.  This option allows the user to
     view or modify the arrow key codes to those corresponding to
     his/her keyboard.

     If arrow keys are not available or produce more than one code
     per keypress (e.g. ANSI terminals) then the default WordStar
     default values listed below should be used.

     Address      Key           Mnemonic   Default value   Size
     -------      ---           --------   -------------   ----
     334 (014Eh)  Backspace     BSIN       08h (Ctrl-H)    Byte
     335 (014Fh)  Up arrow                 05h (Ctrl-E)    Byte
     336 (0150h)  Down arrow               18h (Ctrl-X)    Byte
     337 (0151h)  Right arrow              04h (Ctrl-D)    Byte
     338 (0152h)  Left arrow               13h (Ctrl-S)    Byte

     It should be noted these codes do NOT move the terminal cursor
     or produce any other effect - they simply represent the values
     returned when the corresponding keys are struck.

     <BSIN> allows keyboards that do not have a dedicated <BACKSPACE>
     key to substitute another.  For example, AMSTRAD users can map
     the DEL key (ASCII code 127) to <BSIN> allowing it to be used
     in place of the <BACKSPACE> key by supporting applications.

     Current DX-Forth applications and functions that make use of
     the key code table include SED TED ACCEPT.

     5) No Warm-Boot option

     DX-Forth and turnkey applications normally perform a warm-boot
     on exit (JMP 0000).  In non-banked CP/M systems this results in
     reloading of the system tracks of the disk in drive A.

     This may be defeated by enabling the No Warm-Boot option.  It
     assumes the CCP resides below the BDOS and is no greater than
     2 Kbytes.

     6) Save changes and exit

     Saves the current installation settings to disk if requested
     and exits.


1.6  Getting started

Several versions of the DX-Forth compiler are available:

FORTH.COM      The forth compiler kernel.  It includes everything
               required to load and compile forth source files.

FORTH-F.COM    Same as FORTH.COM but includes software floating point
               and trigonometric functions.  These increase the size
               of the kernel by approximately 3K bytes.

DX.COM         FORTH-F.COM with full-screen editor loaded.  Note:
               DX.COM must be correctly installed before the screen
               editor can be used.

First enter forth by executing FORTH.COM (or FORTH-F.COM or DX.COM)
from the DOS prompt e.g.

     A> FORTH

You will be greeted with DX-Forth's start-up screen showing the
version number and compilation date.  If you executed FORTH-F.COM
you will also be informed that the floating point functions are
available.

Now type

     FYI

"For Your Information".  It displays information about the current
forth environment including dictionary size, vocabularies, logged
drive and open screenfiles.

To see the names of functions (Forth calls them "words") in the
dictionary, type

     WORDS

<SPACE> key is used to pause/resume the listing or <ESC> to stop.

If you want to see words that only contain 'MOD' then type

     WORDS: MOD

You will notice some words are accompanied by an attribute.

'#'  indicates the word is Immediate.

'|'  indicates the word resides in the System dictionary.

Forth users will be familiar with IMMEDIATE words.  SYSTEM words are
peculiar to DX-Forth and are explained in the programming section.

You can capture screen output to a printer e.g.

     PRINTER  WORDS

then restore output to the console with

     CONSOLE

Adding a new function to forth's dictionary is easy.  Let's try the
ubiquitous 'hello world' program.  Type the following paying
attention to the space between  ."  and  Hello .

     : HELLO-WORLD ." Hello world" ;

If you make a mistake entering text you may use the backspace key
<BS> to delete the previous character, or escape key <ESC> to erase
the entire line.

Spaces are important to forth as they distinguish elements within a
forth statement.  Forth syntax is very simple - a forth statement
consists of functions or numbers separated by one or more spaces.
In the example above  :  ."  ;  each represents a distinct forth
function.

You have just compiled a new function or 'word' called HELLO-WORLD.
Now type

     WORDS

This lists all words in the current vocabulary.  Note that
HELLO-WORLD appears at the top of the list since it was the most
recent addition to the dictionary.

Now execute HELLO-WORLD by typing its name.  It should display the
text

     Hello world

Should you wish to enter a quote character '"' within a quote-
delimited string, this is done by entering it twice e.g.

     S" this text includes ""quote"" marks" CR TYPE

produces

     this text includes "quote" marks

Removing a word from the dictionary is even easier.  Type

     FORGET HELLO-WORLD

This discards HELLO-WORLD ... and any forth word you defined after it!
Use WORDS to check that HELLO-WORLD was deleted.

Perhaps you would like to save HELLO-WORLD as your first turnkey DOS
application.  To do this, re-enter the HELLO-WORLD definition if you
discarded it.  Once you have tested it and made sure it works as
expected, save it to disk with

     TURNKEY HELLO-WORLD HELLO

If you now type  DIR *.COM  you should see HELLO.COM in the disk
directory.

Now - the most important thing you should know - how to get out of
forth and back to DOS.  Do this now by typing

     BYE

Now that you are back in DOS you may try out your new HELLO program.
You will note that HELLO.COM executable is considerably smaller in
size than the FORTH.COM used to create it.  This illustrates one of
DX-Forth's features - turnkey applications may be saved without the
compiler and word headers.  The benefit is that applications take
less disk space, are quicker to load, and have more free memory
available to them when they execute.


1.7  Source files

Forth has traditionally used 'blocks' for mass storage.  Blocks may
hold any type of data including text.  In DX-Forth, blocks are used
primarily to store forth program source.  By convention each
'screen' (the name given to a block that holds forth text) is 16
lines of 64 characters, or 1024 bytes of data.  Non-standard block
sizes are also supported (see B/BUF and C/L in the glossary).

DX-Forth screens are saved as conventional DOS disk files and are
distinguished by a .SCR filetype (some forths use .BLK as the
filetype).

DX-Forth also supports forth source in standard text files.  To load
and compile such a file, use:

     INCLUDE filename[.F]

If no filetype is given then .F is assumed.  Another form is:

     S" filename[.F]" INCLUDED  ( Forth-94 Standard )

Forth source files (text or screen) may be nested to the default
maximum of 6.  More than 6 are accommodated by changing nfd in the
kernel source in which case the return stack should be increased.


1.8  Screen editor

Screen files require a special text editor.  DX-Forth includes such
an editor in the form of SED.SCR.  SED supports machines with a
terminal display of at least 68 x 20 characters.  If yours is less,
e.g. 64 x 16, then use SED64.SCR instead.

The editor is automatically loaded and run by FORTH.COM or
FORTH-F.COM by typing

     n SED

where n is the screen number to be edited.  If n is omitted and the
data stack is empty then the editor will use the last LISTed, or if
an error occured, the screen that caused the error.

Note: The full-screen editor requires FORTH.COM (or FORTH-F.COM) be
properly installed for your terminal (see section 5) as it makes use
of the clear-screen, clear to end-of-line and cursor motion terminal
codes.

If you have a slow computer or are working from a floppy disk then
it will be convenient to save a version of forth where the editor is
permanently loaded.  Let's do this now.

From the DOS prompt, load forth and open SED.SCR

     A>FORTH-F SED  ( if no filetype is given .SCR is assumed )

Forth will boot-up with the message 'Using SED.SCR'.  Alternately,
open SED.SCR from within forth with

     USING SED

In DX-FORTH the most recently opened screenfile is termed the
'current' file and all screen and block commands operate on it.
CLOSE closes the 'current' screenfile.  SWAP-FILE permits users
to switch between two open screenfiles.

Once SED.SCR has been opened, you may view the contents of the
file with the LIST command.  0 LIST  displays screen 0,  1 LIST
displays screen 1 etc.  The following shortcuts are provided:

     L  ( -- )   (L)ist the current screen
     N  ( -- )   list the (N)ext screen
     B  ( -- )   list the previous screen i.e. (B)ack
     LS ( -- )   (S)wap screenfiles and (L)ist

Line 0 of each screen is called the index line and traditionally
contains a comment indicating the contents of the screen.  Typing

     0 QX

displays a 'quick index' of 60 screens beginning at screen 0.

To list screens to a printer one could use

     PRINTER  0 LIST  1 LIST  2 LIST  CONSOLE

or more simply

     0 2 SHOW

which prints screens 0 to 2 at three screens per page.

To print all the screens in a source file, type

     LISTING

Now compile the editor into the dictionary with

     1 LOAD

Once loading has completed, typing WORDS will show new commands have
been added to the dictionary.  In addition, FYI reveals some system
memory has been consumed and there is now a new vocabulary in addition
to FORTH - the EDITOR vocabulary.  If you are curious to see what is
in the EDITOR vocabulary, type

     EDITOR WORDS

Now that the editor has been loaded, let's make it permanent by saving
it and the current contents of the forth dictionary as a new executable.

But before doing that you may prefer to use the name EDIT instead of
SED.  That's easily done by creating a synonym e.g.

     AKA SED EDIT

You can now use either SED or EDIT to invoke the screen editor.

Let's finish saving our custom version of DX-Forth to disk.

     SAVE DX.COM  ( if no filetype is given .COM is assumed )

Note: DX-Forth comes supplied with DX.COM so you can omit the above
step if you wish.

For details on using the editor, refer to the SED.TXT documentation
file.


1.9  Resident text file editor

DX-Forth includes TED - a simple text file editor.  As with the screen
editor, text source files may be edited without leaving the forth
environment.  See TED.TXT for further information.


1.10  Command-line interface

DX-Forth allows file opening and command processing from the DOS command
line.  The syntax is:

     A:> FORTH  item1 item2 ... itemn

where:

   item1           filename to be opened (assumed suffix is .SCR)
   item2...itemn   forth command(s) to be executed

Once the command sequence is completed, the DX-Forth sign-on message
appears and control passes to the user.

To bypass file opening, replace item1 with a '-' character.  If no items
are specified then the default screenfile FORTH.SCR is opened if it
exists.

Including BYE at the end of the command sequence will cause an immediate
return to DOS.  This can be very useful and allows use of the forth
compiler within DOS batch files.


1.11  Machine code assembler

Although threaded-code forth generates code that is compact and quite
fast - up to 10 times faster than interpreted BASIC - there may be
occasion when the full speed of machine code is required.

The assembler provided with DX-Forth allows writing of forth 'code'
words.  Code words are simply machine language routines that end with
a jump to NEXT.  Documentation for the assembler may be found in the
file ASM.TXT.


1.12  Increasing System space

The FORTH and FORTH-F executables are supplied with tools and assembler
installed.  If either are not required, the System dictionary space may
be increased accordingly.  To facilitate this, two marker words are
provided:

 -TOOLS  removes the tools and all subsequent words.
 -ASM    removes the assembler and all subsequently defined words.

E.g. To remove TOOLS which is PROTECTed type the following:

     CHECKING OFF  FORGET -TOOLS  CHECKING ON


1.13  Further suggestions

If you have worked your way through the previous sections, you now
know your way around DX-Forth - how to list and compile forth screen
files, save new versions of forth and create turnkey applications.

If this is your first encounter with forth, I hope this brief tour
through DX-Forth will encourage you to look further.  Get a book on
forth and learn it - forth really is EASY!

The best way to learn forth (or any language) is by studying examples.
Several simple applications have been provided with DX-Forth.  When
you encounter a forth word which is unfamiliar, find its definition
in the Forth-94 Standard, or the DX-Forth glossary if not a Standard
word.  DX-Forth does some things a little differently from Forth-94
and this will be documented in the DX-Forth glossary.

A sample filecopy program FCOPY is provided in source form.  As well
as illustrating a complete forth application, it also serves as a
primer on using DX-Forth's file functions.  It will show you how to:

- get arguments from the DOS command line
- create file-handles and assign file-buffers
- open disk files
- read data from a disk file
- write data to a disk file
- close disk files
- handle errors

Routines may be extracted for your own use or the entire program can
serve as the basis for a more complex one.

To aid the creation of new command-line applications, we have supplied
NEWAPP.SCR - a skeletal program that allows users to quickly develop
DOS applications.  Using DOSLIB.SCR it provides access to DOS functions
and routine tasks such as command-line parsing and buffered I/O.  See
NEWAPP.TXT for details.


1.14  Error messages

Compiler error messages
-----------------------
"block out of range"        Attempt to access a block past end of
                            file.
"block r/w error"           Error encountered during a block read or
                            write operation.
"no file open"              File operation was requested but no file
                            was open.
"can't open file"           File not found or write-protected.
"can't create file"         Existing file write-protected or disk full.
"can't delete file"         File not found or write-protected.
"can't resize file"         File not found or write-protected.
"can't rename file"         File exists, not found or write-protected.
"can't save file"           Error occurred during save (probably disk
                            full).
"compilation only"          Use only during compilation.
"execution only"            Use only during execution.
"loading only"              Use only during loading.
"definition unbalanced"     Definition is not properly formed e.g.
                            conditional statements (IF ELSE THEN etc)
                            were incorrectly used or the data stack level
                            changed.
"is protected"              Word is located in PROTECTed dictionary.
"is alias"                  Operation on alias not allowed e.g. FORGET.
"invalid name"              Word name length outside the range 1 to 31
                            characters.
"specify filename"          A filename is required but none was given.
"too many files"            Exceeded maximum number of open source files.
"is redefined"              Definition with the same name already exists.
                            Note: this is a warning - not an error.
"is system"                 A System word is being compiled into the
                            Application dictionary. See section 2.2
                            Note: aliases will be displayed using the
                            primary name.
"is undefined"              Word could not be found in the dictionary
                            using the current search order, or was not
                            a valid number.
"no name space"             Header dictionary full.
"stack?"                    Data stack under/overflow.
"r-stack?"                  Return stack under/overflow.
"f-stack?"                  Floating point stack under/overflow.
"invalid chain"             Illegal CHAIN argument. See glossary.

Run-time error messages
-----------------------
Apart from those listed below, DX-Forth does not perform run-time error
checking.  It is the responsibility of the application programmer to
include error checking appropriate to the task.

"HOLD buffer overflow"      The string being built in the HOLD buffer
                            exceeded the maximum size.
"uninitiated DEFER"         A DEFERed word was defined but never
                            initialized with IS.
"exception = [n]"           Exception error code n was executed. See
                            section 2.14 for a list of system and DOS
                            codes. Application-defined error codes are
                            typically represented by a positive number.
"no data space"             Data space or dictionary full.
"not enough RAM"            Insufficient DOS memory.
"wrong DOS version"         Requires DOS version 2.x or later.

Assembler error messages
------------------------
"definition unbalanced"     Definition is not properly formed.
"duplicate label"           Label number was previously used.
"execution only"            Word may be used only during execution.
"invalid label"             Incorrect label number or too many labels
                            used.
"branch out of range"       Exceeded the range of a short relative
                            branch (128 bytes).
"too many references"       Exceeded the maximum number of forward
                            references to labels.
"unresolved reference"      A label was referenced but never defined.


2.  Programming reference

This section contains programming and technical information specific
to DX-Forth.


2.1  File system

DX-Forth uses FORTH-94 disk file management.

The following applies only to DX-Forth for CP/M.

- The maximum number of open files is 10.  If more file handles are
  needed the number may be increased.  See glossary entry #FCB for
  further details.

- FILE-SIZE returns a value that is a multiple of 128 bytes
  representing the physical size of a disk file stored under CP/M.
  Data written to a file by DX-Forth for CP/M is automatically padded
  with end-of-file character (1Ah) as needed.  READ-LINE treats a 1Ah
  character as physical end-of-file (the same as DX-Forth for DOS).

2.2  Application and System words

When a word is compiled into DX-Forth, it is added to either the
Application dictionary or the System dictionary.

The above suggests that DX-Forth uses two dictionaries.  In reality,
there is one dictionary physically divided into two parts.  It is this
physical partitioning that enables DX-Forth to generate small turnkey
applications, free of compiler overhead.

Executing the words APPLICATION or SYSTEM causes all subsequent
definitions to be compiled into the corresponding dictionary segment.
The word FYI shows the current compilation dictionary and statistics.

The 'application' dictionary contains words (less their headers) that
are available for use by either TURNKEY applications or by the forth
compiler.

The 'system' dictionary contains words that are used exclusively by the
forth compiler.  Headers of forth words are also located in the System
segment.  System words and headers are NOT saved during the generation
of TURNKEY applications.

To see which words are System or Application, type WORDS.  If the word
is displayed with a '|' attribute, then it resides in the System
dictionary otherwise it resides in the Application dictionary.

Compiling SYSTEM words

Under no circumstances should an application compiled with TURNKEY be
allowed to execute a System word.  Attempting to do so will result in
unpredictable behaviour and failure of the application.

To assist users from inadvertently compiling System words into TURNKEY
applications, DX-Forth will issue a warning message should this be
attempted (assuming WARNING has not been disabled).

Applications saved with TURNKEY-SYSTEM may safely ignore System warnings
as the entire forth dictionary including compiler and headers is saved.

Spurious SYSTEM warnings

It is possible to receive a System warning message that is neither an
error condition, nor results in failure of the turnkey application.
Typically it occurs during the compilation of defining words e.g.

   APPLICATION  WARNING ON

   : BYTE-CONSTANT
     CREATE C,  DOES> C@  ;

Compiling the above causes the following message to appear

   "CREATE is system  C, is system  (;CODE) is system"

DX-Forth is warning the user that words CREATE C, (;CODE) are System
words and are being compiled into the Application dictionary.

The reason this will *not* cause the application to fail is that the
words between CREATE and DOES> inclusive represent the "compiling" part
of the defining word.  As these words are typically never executed when
the application is run, their only impact is the application space they
consume.

To disable such spurious System warning messages one may use WARNING OFF
or precede the offending definition with -? which will turn off WARNING
for that definition only.

Tip: For an alternative way of creating defining words which avoids the
peculiarities of CREATE ... DOES> see BUILD in the glossary.


2.3  Executing applications

Applications can often be fully tested and debugged from within the
forth environment.  However when they are eventually TURNKEYed and
executed from the DOS command-line, there will be differences of which
the programmer should be aware:

 - The amount of unused memory available to an application will vary
   depending on whether it is run from within forth or from the DOS
   command-line.  UNUSED may be used by applications to determine how
   much free memory is currently available.

 - SET-LIMIT allows the programmer to specify a top-of-memory address
   or LIMIT for the application.  The effect of SET-LIMIT is postponed
   until the turnkey application is executed.

 - The memory region at 5Ch and 80h (DOS default FCB and DMA buffer) is
   overwritten by the forth compiler during DIR, RENAME, INCLUDE etc.
   Otherwise, this region is unaffected and may be used by turnkey
   applications to interrogate the DOS command-line.

 - Functions INIT-VIDEO and EXIT-VIDEO are not automatically executed
   by TURNKEY applications.


2.4  No Warm-Boot option

DX-Forth and turnkey applications automatically perform a warm-boot
(BDOS function 0) on exit.  This allows all the available TPA memory to
be used by the program but has the disadvantage that the CP/M Console
Command Processor (CCP) must be reloaded on exit.  If this is not
desired, the NO WARMBOOT option may be enabled by changing the byte at
address location 272 (0110h) to a non-zero value, or by using the
INSTALL program.

NOTE: Enabling NO WARMBOOT reduces the amount of free memory.  Turnkey
applications will have 2K bytes less free memory and the DX-Forth
compiler will have 2K bytes less System memory.  CCP greater than 2K
bytes are not currently supported.


2.5  User Patch area

A user patch area consisting of five bytes has been reserved
exclusively for use by applications.

User Patch     Address
----------     -------
    1          267 (010Bh)
    2          268 (010Ch)
    3          269 (010Dh)
    4          270 (010Eh)
    5          271 (010Fh)

This area may be used for any purpose by an application.  Possible
uses include:

  - hardwiring an application program's options or configuration.
  - contain the address of a user's D-A port address.


2.6  Overlays

As DX-Forth resides in a single 64K segment, there will be a limit on
the size of applications that may be compiled.  If larger applications
are needed this can often be achieved with overlays.

Using overlays will require a little more planning of the application.
Some important aspects the programmer must consider are listed below.

 - The resident part of the program must ensure that the correct overlay
   is in memory before executing an overlay word.

 - An overlay must not execute words that exist in other overlays.

 - An overlay must not execute words in the resident part, which in
   turn, execute words in a different overlay.

See OVERLAY.SCR for a demonstration of a simple overlay system.


2.7  Multitasking

A co-operative 'round robin' multi-tasker is provided with DX-Forth.
It permits an application to have several tasks run concurrently.

Refer to the multitasker documentation MULTI.TXT and the source file
MULTI.SCR for further details.


2.8  User variables

In common with most forth systems, DX-Forth has 'user' variables.  User
variables occupy a common region in memory.  They hold various system
and boot up values and are also used for multi-tasking applications.

In DX-Forth the default size of the user area is 128 bytes.  User
variables are defined as follows:

   44 USER VAR1
   46 USER VAR2
   50 USER VAR3 ...

The number preceding USER is the offset in bytes of the variable from
the user base address (given by the variable UP).  Offsets beginning
with 44 decimal are available to applications.  In the above example,
VAR1 occupies 2 bytes (1 cell) at offset 44, VAR2 occupies 4 bytes
(2 cells) at offset 46 etc.  See #USER in the glossary.

As with normal variables, executing the name of a user variable returns
its address.  Unlike normal variables, the literal value of the address
may differ at compile and run time.  In multi-tasking applications the
contents of a user variable may differ between tasks.

Predefined user variables in DX-Forth are:

S0  R0  DP  VOC-LINK  FS0  DPH  DPL  BASE  OUT  CATCHER


2.9  System vectors

SYS-VEC returns the address of the system vector and parameter table.
The table contains default values used by the system.  Applications
may alter the vectors and values in the table as needed.  Note that
some changes will not take effect until COLD is executed.  Refer to
SYS-VEC in the glossary document for details.


2.10  Deferred words

The following is a list of DX-Forth words built with DEFER IS .

   ACCEPT  BEEP  FIND  MS  PAUSE  REFILL  SOUND

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

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


2.11  Search order

The dictionary search order is CONTEXT CURRENT FORTH where each
represents a vocabulary or "wordlist".  Complex search orders are
possible using the CHAIN command.


2.12  Compiler security

DX-Forth includes compiler security to detect malformed definitions
and constructs e.g. failing to terminate an IF section with a THEN.

Compiler security words used by DX-Forth are listed in the glossary.
How and when to use them is a topic of its own and is not discussed
here (see the DX-Forth source files for examples of use).

It is sometimes useful to disable balance checking in high-level or
code definitions.  This may be done by temporarily setting variable
CHECKING to false (i.e. zero).  The same technique may be used to
FORGET previously PROTECTed words.  Disabling compiler security is
not without risk and should be undertaken with caution.


2.13  Exception handling

CATCH THROW provide a mechanism for handling errors conditions within
a program.

It is recommended that applications use only positive THROW codes.
Exception values in the range -1 to -4095 are reserved by ANS-FORTH
for use by the system.  See: "Exception codes"


2.14  Exception codes

DX-Forth implements only a subset of ANS-FORTH Standard exception
codes.  Codes in the range -257 to -511 are reserved for DOS related
errors.

DX-Forth exception codes:

   0             no error
  -1             ABORT
  -2             ABORT"
  -256           reserved
  -257 to -511   DOS error code

The correlation between DOS error code and DX-Forth exception code
is given below:

  Forth     DOS
      0       0     no error
   -511       1     invalid function number (not implemented for CP/M)
   -510       2     file not found
   -509       3     path not found
   -508       4     too many open files
   -507       5     access denied
   -506       6     invalid handle
    ...      ..
   -493      18     no more files
    ...     ...
   -257     255     unspecified error e.g. disk full

Note: To convert an exception code in the range -257 to -511 to its
corresponding DOS error code, use: 255 AND


2.15  ZINS Routine

The ZINS routine (see ZINS.SCR) performs automatic terminal
installation for DX-Forth or its applications when running Z-System
(ZCPR3, NZCOM etc).

ZINS may be used as part of a general terminal install program or
included in DX-Forth applications to dynamically adjust to the current
TermCap in memory if Z-System is found present.

NOTE: Due to the Turbo Pascal compatible install area used by DX-Forth,
certain Z-System cursor motion commands cannot be properly emulated.
The exceptions are handled as follows -

     '%>xy'    treated as '%.'
     '%D'      treated as '%2' if the number of screen columns is
               less than 100 or as '%3' otherwise.

If the currently installed CPU speed is greater than 255 MHz (the
maximum value supported by ZCPR TermCap) no change is made.

The command and stack effects for ZINS is simply -

     ZINS  ( -- )

If Z-System is found not to be present, nothing is changed.

While it is possible to use ZINS in an application and have it run
transparently as far as the end-user is concerned, some would regard
this as bad programming practice.  Users needs vary and there may be
instances where auto-installation may not be wanted.  A way around
this would be to enable/disable auto-installation according to a
command-line switch when the application is first executed. e.g.

     A>PROGNAME -Z

Lastly, assembly language programmers may find the code for ZINS
interesting.  With some small changes (leave out the arrow key patches
and include a check for a valid ZENV address) ZINS could be used to
install any Turbo Pascal generated program from Z-System's in-memory
TermCap.  Occupying approximately 450 bytes, it could be reduced
further using Z80 relative jumps.


3.  DX-Forth extensions

DX-Forth includes non-standard extensions and practices the author has
found beneficial.  Those more frequently used are summarized below.
Please refer to the DX-Forth glossary document for further information.

3.1  END BREAK

DX-Forth has introduced the macros END and BREAK.  These replace the
sequences EXIT THEN and LEAVE THEN respectively.

3.2  OF COND CONT

OF COND CONT is an alternative to Forth-94 CASE OF ENDOF ENDCASE that
avoids certain restrictions of the latter.

3.3  BUILD

An alternative to CREATE DOES>/;CODE that takes advantage of DX-Forth's
split dictionary organization.


