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.


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   Command-line interface
 1.10  Machine code assembler
 1.11  Increasing System space
 1.12  Further suggestions
 1.13  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  Compiler security
 2.12  Exception handling
 2.13  Exception codes
 2.14  ZINS Routine


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.

DX-Forth's features include:

 - Forth-94 Standard (see below)
 - Fast direct-threaded code
 - Generate turnkey applications without compiler overhead
 - Video terminal functions, installable for most terminals
 - Fast floating point and trigonometric functions
 - Forth-94 Standard disk I/O
 - 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
 - Multitasking
 - Overlays for large applications
 - 8080/Z80 Forth assembler for CODE words
 - Full source code included

* DX-Forth currently lacks appropriate documentation to qualify for
  ANS FORTH compliance.  Some ANS optional wordset functions may also
  be missing.


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.  As a public domain work, no copyright
restrictions apply or may be subsequently imposed.

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 his or her own risk.


1.5  Installation

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

                           IMPORTANT

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

   PAGE  AT-XY  CLEAR-LINE  HIGHLIGHT  NORMAL  INSERT-LINE
   DELETE-LINE  INIT-VIDEO  EXIT-VIDEO
 
you MUST include INSTALL.COM and INSTALL.DTA with the
distribution otherwise users will be unable to customise the
application for their hardware.

As supplied DX-Forth is pre-configured for a Televideo 912/920/
925 terminal and 4 MHz Z80 CPU.  If this does not correspond to
your terminal/machine and you wish to change it, run install 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 including the
     Z-System TermCap currently defined in memory.

     If your terminal is not listed try another make of terminal.
     Often different manufacturers will 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 alternatives exist.

     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.

     2) CPU speed

     Enter the speed of the computer's CPU to the nearest MHz.
     This 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.

     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 suffice.

     4) Arrow 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 below should be used.

     NOTE: Currently DX-Forth makes no use of arrow key codes
     (though the full-screen editor will use them if defined).
     User applications can access the key codes at the following
     memory address locations:

     Address        Key            Default value
     -------        ---            -------------
     335 (014Fh)    Up arrow       05h (Ctrl-E)
     336 (0150h)    Down arrow     18h (Ctrl-X)
     337 (0151h)    Right arrow    04h (Ctrl-D)
     338 (0152h)    Left arrow     13h (Ctrl-S)

     It should be emphasized these codes do NOT move the terminal
     cursor or produce any other effect.  They represent the
     values returned when the "arrow keys" on the keyboard are
     struck.

     5) No Warm-Boot option

     DX-Forth and turnkey applications normally perform a warm-
     boot on exit.  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;
     but at a loss of 2k bytes of application memory space.

     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 2.5K.

DX.COM         FORTH-F.COM with the screenfile editor loaded.


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 all forth functions in the dictionary, type

     WORDS

Press any key to stop the display or <space> to pause.  If you want
to see only word names that contain the sequence '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.  <SPACE> may be used
to pause/resume the listing or <ESC> to stop.  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 need to enter a quote character '"' within a quote-
delimited string, this may be 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 to make sure that it works as
expected, save it to disk with

     TURNKEY HELLO-WORLD HELLO

If you now type  DIR  you should see HELLO.COM in the disk directory.
Note: you may optionally specify a filename with DIR.  Wildcards are
accepted e.g. DIR *.COM

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.  Each 'screen' (the name
given to blocks that hold forth text) represents 1024 bytes of data
organized as 16 lines of 64 characters each.  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.


1.8  Screen editor

Screen files require a special text editor.  DX-Forth includes such
an editor in the form of EDITOR.SCR.  The editor is automatically
loaded and run by FORTH.COM or FORTH-F.COM by typing

     n EDIT

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 EDITOR.SCR

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

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

     USING EDITOR

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 EDITOR.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

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

     0 QX

displays a 'quick index' of 60 screens starting at 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

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

(Note: The supplied executable DX.COM has the screen editor preloaded
so you may omit the above step.)

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


1.9  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.

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.10  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.11  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 type the following:

     CHECKING OFF  FORGET -TOOLS  CHECKING ON

1.12  Further suggestions

If you have worked your way through the previous sections - you now
know how to look around DX-Forth, 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 with which you are unfamiliar, find its
definition in the Forth-94 Standard (draft version freely available
on the internet) or the DX-Forth glossary if not a Standard word.

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.

NEWAPP.SCR is 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.13  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 header space"             Header dictionary full.
"stack?"                      Data stack under/overflow.
"r-stack?"                    Return stack under/overflow.
"f-stack?"                    Floating point stack under/overflow.

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.

"numeric buffer overflow"     The string being built in the pictured numeric
                              output buffer exceeded the buffer size.
"undefined vector"            A DEFERed word was defined but never
                              initialized with IS.
"exception = [n]"             Exception error code n was executed. See
                              section 2.12 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 used ANS FORTH disk file management.

The maximum number of open files is 10.  If more file handles are
needed the number may be increased as follows e.g.

          20 TO #FCB  COLD

This will change the maximum number of handles to 20.


2.2  Application and System words

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

The above implies that DX-Forth uses two dictionaries.  In actuality,
there is only 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 located in their own
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 bold attribute (usually blue), 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.  This part is executed only during compilation
- never when the application is run.

To disable 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.

 - The memory region at $5C and $80 (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 1) on exit.  The allows all the available TPA memory
to be used by the program but has the disadvantage that the CP/M
Console Command Processor 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.


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 including headers, 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.

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 on an as needs basis.
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 .

   BEEP  FIND  MS  PAUSE  REFILL  ACCEPT

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

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


2.11 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 setting variable CHECKING
to false (i.e. zero).


2.12  Exception handling

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

It is recommended 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.13  Exception codes

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

DX-Forth exception codes:

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

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

 Exception  MS-DOS
     0        0     no error
   -511       1     function number invalid (not used)
   -510       2     file not found
   -509       3     path not found
   -508       4     too many open files
   -507       5     access denied
   -506       6     invalid handle
    ...     ...
   -257     255     unspecified error

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


2.14  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.

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 only 450 or so bytes, it could be reduced even
further by using Z80 relative jumps.

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