901 lines
33 KiB
Plaintext
901 lines
33 KiB
Plaintext
DX-Forth for MS-DOS
|
|
-------------------
|
|
|
|
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 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 Key codes
|
|
|
|
|
|
1. Introduction
|
|
|
|
1.1 Overview
|
|
|
|
DX-Forth is a Forth language compiler and development system
|
|
for MS-DOS 2.x and compatible disk operating systems. It is
|
|
intended to be a complete, easy to use, programming tool for
|
|
the creation of DOS 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
|
|
- 8086/87 Forth assembler for CODE words
|
|
- Full source code included
|
|
|
|
* 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
|
|
|
|
Not applicable to the MS-DOS version of DX-Forth.
|
|
|
|
|
|
1.6 Getting started
|
|
|
|
Several versions of the DX-Forth compiler are available:
|
|
|
|
FORTH.EXE The forth compiler kernel. It includes everything
|
|
required to load and compile forth source files.
|
|
|
|
FORTH-F.EXE Same as FORTH.EXE but includes software floating point
|
|
and trigonometric functions. These increase the size
|
|
of the kernel by approximately 3K bytes.
|
|
|
|
DX.EXE FORTH-F.EXE with full-screen editor loaded.
|
|
|
|
FORTH-C.EXE Same as FORTH-F.EXE but uses "common stack" model
|
|
i.e. floating point items are placed on the data stack
|
|
rather than on a separate stack.
|
|
|
|
Note: FORTH-C.EXE is not in the distribution but can
|
|
be generated by rebuilding the system with FMAKE.BAT
|
|
|
|
First, enter forth by executing FORTH.EXE (or FORTH-F.EXE or DX.EXE)
|
|
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.EXE
|
|
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
|
|
|
|
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.
|
|
|
|
The bold attribute (normally blue) indicates the word resides in the
|
|
SYSTEM dictionary. All other words reside in the APPLICATION
|
|
dictionary. If the brightness attribute is on, it indicates the word
|
|
is IMMEDIATE. Attributes are accumulative. Thus a word that appears
|
|
in bold and has the brightness toggled is both a SYSTEM word and
|
|
IMMEDIATE.
|
|
|
|
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> key 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 *.EXE you should see HELLO.EXE 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.EXE executable is considerably smaller in
|
|
size than the FORTH.EXE 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 SED.SCR. The editor is automatically
|
|
loaded and run by FORTH.EXE or FORTH-F.EXE 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.
|
|
|
|
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.EXE ( if no filetype is given .EXE is assumed )
|
|
|
|
Note: DX-Forth comes supplied with DX.EXE 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.
|
|
|
|
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 type the following:
|
|
|
|
CHECKING OFF FORGET -TOOLS CHECKING ON
|
|
|
|
Note: As of DX-Forth 3.3, word headers are stored in their own segment
|
|
rather than in the System dictionary. Consequently there is now much
|
|
less need to conserve System dictionary space.
|
|
|
|
|
|
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.
|
|
|
|
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.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.
|
|
|
|
|
|
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 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.
|
|
|
|
- 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.
|
|
|
|
|
|
2.4 No Warm-Boot option
|
|
|
|
Not applicable to the MS-DOS version of DX-Forth.
|
|
|
|
|
|
2.5 User patch area
|
|
|
|
Not applicable to the MS-DOS version of DX-Forth.
|
|
|
|
|
|
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 .
|
|
|
|
BEEP FIND MS PAUSE REFILL ACCEPT 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 setting variable CHECKING
|
|
to false (i.e. zero).
|
|
|
|
|
|
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
|
|
-510 2 file not found
|
|
-509 3 path not found
|
|
-508 4 too many open files
|
|
-507 5 access denied
|
|
-506 6 invalid handle
|
|
-505 7 memory control block destroyed
|
|
-504 8 insufficient memory
|
|
-503 9 memory block address invalid
|
|
-502 10 environment invalid
|
|
-501 11 format invalid
|
|
-499 12 access code invalid
|
|
-498 13 data invalid
|
|
-497 14 reserved
|
|
-496 15 invalid drive
|
|
-495 16 attempted to remove current directory
|
|
-494 17 not same device
|
|
-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 Key codes
|
|
|
|
DX-Forth supports IBM-PC extended keystrokes and enhanced keyboards.
|
|
For ease of use, two-byte extended keystrokes are returned as single
|
|
values. The codes below are for an enhanced 101-key US keyboard.
|
|
Ascii codes 32-126 are not shown.
|
|
|
|
Key Code Key Code Key Code
|
|
---- ----- ---- ----- ---- ------
|
|
00 0 Alt F A1 161 Ctrl F7 E4 228
|
|
Ctrl A 01 1 Alt G A2 162 Ctrl F8 E5 229
|
|
Ctrl B 02 2 Alt H A3 163 Ctrl F9 E6 230
|
|
Ctrl C 03 3 Alt J A4 164 Ctrl F10 E7 231
|
|
Ctrl D 04 4 Alt K A5 165 Alt F1 E8 232
|
|
Ctrl E 05 5 Alt L A6 166 Alt F2 E9 233
|
|
Ctrl F 06 6 Alt ; A7 167 Alt F3 EA 234
|
|
Ctrl G 07 7 Alt ' A8 168 Alt F4 EB 235
|
|
Ctrl H 08 8 Alt ` A9 169 Alt F5 EC 236
|
|
Ctrl I 09 9 AA 170 Alt F6 ED 237
|
|
Ctrl J 0A 10 Alt \ AB 171 Alt F7 EE 238
|
|
Ctrl K 0B 11 Alt Z AC 172 Alt F8 EF 239
|
|
Ctrl L 0C 12 Alt X AD 173 Alt F9 F0 240
|
|
Ctrl M 0D 13 Alt C AE 174 Alt F10 F1 241
|
|
Ctrl N 0E 14 Alt V AF 175 Ctrl Prtsc F2 242
|
|
Ctrl O 0F 15 Alt B B0 176 Ctrl Left F3 243
|
|
Ctrl P 10 16 Alt N B1 177 Ctrl Right F4 244
|
|
Ctrl Q 11 17 Alt M B2 178 Ctrl End F5 245
|
|
Ctrl R 12 18 Alt , B3 179 Ctrl PgDn F6 246
|
|
Ctrl S 13 19 Alt . B4 180 Ctrl Home F7 247
|
|
Ctrl T 14 20 Alt / B5 181 Alt 1 F8 248
|
|
Ctrl U 15 21 B6 182 Alt 2 F9 249
|
|
Ctrl V 16 22 * Alt * B7 183 Alt 3 FA 250
|
|
Ctrl W 17 23 B8 184 Alt 4 FB 251
|
|
Ctrl X 18 24 B9 185 Alt 5 FC 252
|
|
Ctrl Y 19 25 BA 186 Alt 6 FD 253
|
|
Ctrl Z 1A 26 F1 BB 187 Alt 7 FE 254
|
|
Ctrl [ 1B 27 F2 BC 188 Alt 8 FF 255
|
|
Ctrl \ 1C 28 F3 BD 189 Alt 9 100 256
|
|
Ctrl ] 1D 29 F4 BE 190 Alt 0 101 257
|
|
Ctrl ^ 1E 30 F5 BF 191 Alt - 102 258
|
|
Ctrl _ 1F 31 F6 C0 192 Alt = 103 259
|
|
F7 C1 193 Ctrl PgUp 104 260
|
|
Ctrl <- 7F 127 F8 C2 194 F11 105 261
|
|
80 128 F9 C3 195 F12 106 262
|
|
Alt Esc 81 129 F10 C4 196 Shift F11 107 263
|
|
82 130 C5 197 Shift F12 108 264
|
|
83 131 C6 198 Ctrl F11 109 265
|
|
84 132 Home C7 199 Ctrl F12 10A 266
|
|
85 133 Up C8 200 Alt F11 10B 267
|
|
86 134 PgUp C9 201 Alt F12 10C 268
|
|
87 135 * Alt - CA 202 Ctrl Up 10D 269
|
|
88 136 Left CB 203 * Ctrl - 10E 270
|
|
89 137 * 5 CC 204 * Ctrl _ 10F 271
|
|
8A 138 Right CD 205 110 272
|
|
8B 139 * Alt + CE 206 Ctrl Down 111 273
|
|
8C 140 End CF 207 Ctrl Ins 112 274
|
|
8D 141 Down D0 208 Ctrl Del 113 275
|
|
Alt <- 8E 142 PgDn D1 209 Ctrl Tab 114 276
|
|
Shift Tab 8F 143 Ins D2 210 Ctrl / 115 277
|
|
Alt Q 90 144 Del D3 211 * Ctrl * 116 278
|
|
Alt W 91 145 Shift F1 D4 212 Alt Home 117 279
|
|
Alt E 92 146 Shift F2 D5 213 Alt Up 118 280
|
|
Alt R 93 147 Shift F3 D6 214 Alt PgUp 119 281
|
|
Alt T 94 148 Shift F4 D7 215 11A 282
|
|
Alt Y 95 149 Shift F5 D8 216 Alt Left 11B 283
|
|
Alt U 96 150 Shift F6 D9 217 11C 284
|
|
Alt I 97 151 Shift F7 DA 218 Alt Right 11D 285
|
|
Alt O 98 152 Shift F8 DB 219 11E 286
|
|
Alt P 99 153 Shift F9 DC 220 Alt End 11F 287
|
|
Alt [ 9A 154 Shift F10 DD 221 Alt Down 120 288
|
|
Alt ] 9B 155 Ctrl F1 DE 222 Alt PgDn 121 289
|
|
Alt Enter 9C 156 Ctrl F2 DF 223 Alt Ins 122 290
|
|
9D 157 Ctrl F3 E0 224 Alt Del 123 291
|
|
Alt A 9E 158 Ctrl F4 E1 225 * Alt / 124 292
|
|
Alt S 9F 159 Ctrl F5 E2 226 Alt Tab 125 293
|
|
Alt D A0 160 Ctrl F6 E3 227 * Alt Enter 126 294
|
|
|
|
(*) on keypad
|
|
|
|
Note:
|
|
|
|
- Codes 261 and above are only available on AT-class machines
|
|
fitted with an enhanced keyboard
|
|
|
|
- DOS versions prior to 4.0 do not support enhanced keys
|
|
irrespective of the hardware
|
|
|