CONVERTING FIG-FORTH TO ANS FORTH
If your program is on TDS9092 or is for a TDS2020 Forth before version 3.00, you will need to convert from the Fig-Forth implementation to American National Standard Forth. Follow these steps:
q Do the EASY SUBSTITUTIONS below using a word-processor's search-and-replace facility.
q Work slowly down the list of POINTS TO WATCH below using a word-processor's find facility to locate all occurrences of each item. Understand the software's action before deciding if a replacement is needed.
q Use only library programs starting with # . For example change $SHELTER.TDS to #SHELTER.TDS.
q Change interrupt vectors defined with +ORIGIN . Add +62 to each number used for the earlier Fig-Forth version of TDS2020, except the internal watchdog ( 1 +ORIGIN ) which remains unchanged. For example the A to D interrupt changes from -65 +ORIGIN to -3 +ORIGIN
Add another word at the end of your program to take care of error conditions. If you omit it, the program will abort to interactive Forth if it fails due to electrical noise or other error. With the extra layer it will restart or do anything else you want on an error. The simplest recommended structure for the highest level of your program is as follows. It is further explained in ERROR HANDLING, page 144. (Note: If your program uses the serial port arrange some other escape to Forth, for instance when a key on a parallel input is pressed.)
Example of program top-level structure:
: INITIALISE ( - ) \ Set direction of I/O ports,
\ zero all variables, including
\ any multitasker locks.
. initialisations . ;
: TRY ( - ) \ One pass through the main program loop
KEY? IF START THEN . rest of program . ;
: MAIN ( - ) \ Indefinite application loop
INITIALISE BEGIN TRY AGAIN ;
: WORK ( - ) \ Word executed at power-up
BEGIN ['] MAIN CATCH ERROR AGAIN ;
If there is anything not clear about ANS Forth, or you want assistance with part of your program, remember that we can advise you.
This is a table of principal exact equivalents. Here xxx represents any Forth word and '.' replaces a section of Forth code:
Updating a program to ANS Forth is a process that can be partially automatic. Some words just have new names but identical functions. Such replacement can be done easily in a word-processor with the search-and-replace mechanism. On the other hand, some differences will require a close look at how the original program achieves its function.
Here we consider only essential changes. Although some words such as [COMPILE] and EXPECT still exist in ANS Forth, their use is discouraged in favour of newer words, in this case POSTPONE and ACCEPT . In updating a program you can choose to ignore such advice if you wish. In the case of DOES> the use and function is unchanged but under ANS Forth the word is immediate during compilation and the internal operation is completely different, resulting in much faster execution times for defining words.
J must only be used to access the index of an outer DO . LOOP structure
from within a second DO . LOOP . It can not be used to get at an item left on the return
stack before a DO . LOOP started:
R@ replaces R but is not the same as I . Use R@ to get a copy of the top of the return
stack and I to
get the index of the current innermost loop.
DO in Fig-Forth should normally be replaced by ?DO in the
conversion to ANS Forth because, given two equal parameters, the
ANS Forth version of DO will loop 65536 times, not 0 times as the Fig-Forth version.
The structure DO . -1 +LOOP will loop one more time in ANS Forth
than in Fig-Forth. Search the Fig-Forth source code for all occurrences
of +LOOP and
make any adjustment necessary.
LEAVE is still used in a DO . LOOP to get out of the loop prematurely but
under ANS Forth you jump directly from the LEAVE to after the following LOOP or +LOOP without
executing the intervening code. For example:
The true Boolean flag returned by operations like = is -1
but in Fig-Forth it is +1. No change is necessary provided you have really
used this as a flag, to be consumed by IF or WHILE for example. However if you have mixed
types by using it as a numerical value, the program will need adjustment.
ANS Forth, like Fig-Forth, will accept any
value other than zero as a Boolean true flag. It is only the value provided
from operations returning a
flag that changes. New words TRUE and FALSE exist which are equivalent to -1 and 0 respectively.
The word ' returns a code field address in ANS Forth,
now renamed an execution token, and not the parameter field address.
In addition you need to use ['] instead of ' when compiling (see EASY SUBSTITUTIONS above).
For example, in an assembler definition when you want the address of
a subroutine xxx change ' xxx to ' xxx >BODY .
CREATE and <BUILDS are two words with separate functions in Fig-Forth.
The former is normally used to make look-up tables and the latter for
defining words. In ANS Forth the two jobs are combined and given
to CREATE .
See 'Forth Programmer's Handbook' for examples.
Look-up tables change. In the table itself omit the SMUDGE which
was used with Fig-Forth. In the place where the table is used omit the ' ('tick')
which found the address of the table. The SMUDGE is not needed because ANS Forth's CREATE does not make the table name unfindable, and the 'tick'
is not used because ANS Forth's CREATE makes a name which automatically returns
its own address when executed.
When using words , ALIGN ALIGNED ALLOT C, CREATE HERE UNUSED (see EASY SUBSTITUTIONS above)
make sure the intended data-space is active. Note however that VARIABLE and 2VARIABLE always
address the RAM. For example:
PICK and ROLL take arguments one less than in Fig-Forth. For example, 1 PICK is
the same as OVER in
ANS Forth, but equal to DUP in Fig-Forth. Arguments to these words
will need reducing
Millisecond delays using MS in ANS Forth can be longer but not
shorter than nominal. In TDS2020F ANS Forth MS is
accurate to within -0/+5% when running from the H8/532 microprocessor
(unless using the multitasker or interrupts). It is about twice as slow
when running from the TDS2020DV development piggyback. Add file #TIMING.TDS
to get accurate MS in all circumstances.
CASE is not Fig-Forth but earlier TDS2020s and TDS9092 have it.
Unlike these, ANS Forth does not keep the value being tested on
the return stack during the various OF . ENDOF clauses. Because it remains on the parameter stack you have
to be careful to keep it in the right place. Note the difference between
these two examples: