Fig-Forth v2 bears a close relationship between procedures, subroutines and operational functions, due to the nature of the internal engine and the code produced by the compiler. Because of this relationship Fig-Forth begins operation in the execution mode; processing and running any token list or kernel code as their symbols are parsed from the input stream, creating and operating upon the parameters supplied by the system console. As functions are added to the dictionary space or executed by the user, each function forms a subroutine within the virtual machine's operation, which may or may not return to the Forth command process at the end of its execution cycle.
Due to this multiple subroutine oriented process of operation, Fig-Forth v2 recognizes precisely two types of program code. The first type is that of direct machine instructions, compiled as individual code fragments within the dictionary space or kernel segments. Each fragment of such code must be preceded or pointed to by a token value that causes the kernel to execute it, and has a collection of restrictions and limitations as outlined in Appendix C.
The second type of recognized code is that form most commonly constructed by the compiler, or the token lists of threaded functions outlined briefly in Chapter 1. Each of the tokens in such lists use double indirection addressing to locate their corresponding machine code or token list sub-entries, hence all functions to be executed must have a valid dictionary pointer within the user space. When such a token list is being processed by the internal engine each token or sub-list location is pushed upon the return stack in sequence, thereby becoming an operational subroutine to the master control loop.
Given this overview of Fig-Forth's internal structure both inside the dictionary space and without, it is clear that the dictionary is paramount in controlling kernel operations. To this end Fig-Forth contains a number of operations and functions, based upon the following definitions;
Because Fig-Forth can contain any number of words or vocabularies within the user definition space, it is essential that all symbol searches be performed in an orderly manner. Over and above the need to avoid conflicts with multiple occurrences of any single word alias or function symbol, Fig-Forth's compiler is programmed to use only the first encountered match with such a symbol in the latest definition. Due to the manner in which symbols are added to the dictionary the compiler always starts this process at the current dictionary tail and proceeds backward, until the current symbol is found or the symbol list is exhausted.
When at the end of a symbol list Fig-Forth examines the contents of the Search Order Buffer for any subsequent threads to continue the search, repeating this process before declaring a mismatch. For the purposes of Fig-Forth's operation the Search Order Buffer is defined as 10 units deep, meaning the search can pass through ten vocabulary strings before a failed match is declared. To control this search pattern Fig-Forth v2 contains the ALSO-ONLY concept of Forth83 Standards, using the following words to manipulate the contents of the Search Order Buffer;
This is the first of the word search operations available in Fig-Forth, which empties the Search Order Buffer and forces a return to the ROOT vocabulary. The ROOT word is the default member of any vocabulary list created or defined by the user, because this vocabulary contains the search order control words, vocabulary list functions, and the basic system and file controls.
This search order word causes a duplication of the top entry in the Search Order Buffer, rolling all other entries down one location. Similar to the DUP Forth word for controlling a value upon the Parameter Stack, this function will make a copy of the current search entry and place it first in the search chain. One should note however that this function will not push any search entry out of the bottom of the Search Order Buffer, as the new entry replaces the top item in the search buffer.
This function performs the opposite operation of ALSO, pulling the top search item out of the Search Order Buffer and discarding it. All other entries will be rolled up one location in the search order, until the buffer contains but a single item. Similar to ALSO this function will not empty the Search Order Buffer beyond a single search entry, such that the ROOT vocabulary may always be accessed.
The ORDER word will list the contents of the Search Order Buffer, displaying the vocabulary names in the sequence Forth is using them to find alias symbols. In addition this function also displays the name of the vocabulary into which new definitions are being placed, such that the compilation process may be controlled.
This word copies the top entry in the Search Order Buffer into the Compilation Dictionary Pointer, making the uppermost vocabulary in the search order the location where new functions are compiled. Please note that the compilation vocabulary is searched before the entries in the Search Order Buffer.
This word will list the contents of all vocabularies in the current Search Order Buffer, separating vocabulary entries by a title header. Words or vocabularies which have been declared as IMMEDIATE (see below) are printed in red letters, and any failed definitions will appear in violet ink. For the purpose of long lists this function will pause at the screen end or bottom, where any key except Enter may be pressed to continue the listing. Pressing Enter will abort the listing at the current location. (This function is called WORDS in Forth83 and higher.)
Example 1.
When a Fig-Forth session is begun the compiler executes an ONLY ALSO FORTH DEFINITIONS sequence, meaning that precisely two vocabularies are contained in the current search order when the kernel turns control over to the user. These vocabularies contain the basic Forth Language and the ROOT definitions, such that new definitions or simple Forth operations may be performed. For an explanation as to why both the ROOT and FORTH vocabularies are selected you may perform the following example;
80386 fig-FORTH v2.31
Implemented 04/09/03 by MB
ORDER
SEARCH ORDER: FORTH ROOT
NEW WORDS: FORTH
OK.
ONLY OK.
ORDER
SEARCH ORDER: ROOT
NEW WORDS: ROOT
OK.
FORTH DEFINITIONS OK.
ORDER ORDER? Huh?
VLIST VLIST? Huh?
Doing this we have now removed the ROOT words from the Search Order Buffer, meaning that file opening, creating application vocabularies, even listing the contents of FORTH are unknown functions. You will find you cannot even leave the Forth environment by using the exit word BYE in this arrangement, for it too is contained in the minimum search path of ROOT. However, this is not a disastrous condition because the ROOT vocabulary is always the default member of any created definition list, so control can be regained by the following;
ROOT OK.
ORDER
SEARCH ORDER: ROOT
NEW WORDS: FORTH
OK.
Now the search control words and other ROOT definitions are once more available, allowing the addition of other vocabularies to the search chain and other functions. To reestablish the start-up arrangement follow with the next statement;
ALSO FORTH OK.
ORDER
SEARCH ORDER: FORTH ROOT
NEW WORDS: FORTH
OK.
This example is presented in the event that an accidental use of the above word combination takes place, and to show how to regain control of the package in that case. In the example the ALSO word should be used as shown, to insure the root is part of the search chain. (See example 2 and Starting An Application.)
Example 2.
This example demonstrates the reason for the ONLY word, as vocabularies are added to the search chain at random or by on-the-fly conceived need. (And how the ALSO word is used improperly to do so.)
80386 fig-FORTH v2.31
Implemented 04/09/03 by MB
ORDER
SEARCH ORDER: FORTH ROOT
NEW WORDS: FORTH
OK.
ALSO VIDEO ALSO MOUSE ALSO FORTH OK.
( other operations performed when a need is seen)
ALSO SOUND ALSO FORTH OK.
ORDER
SEARCH ORDER: FORTH SOUND FORTH MOUSE VIDEO FORTH ROOT
NEW WORDS: FORTH
OK.
As can be seen, the FORTH vocabulary is being searched multiple times in this example, as the various vocabularies have been added to the chain. While this is not a disastrous condition, if continued the Search Buffer could overflow and prevent the addition of subsequent vocabularies in the search process. Since we now stand at 7 entries we are close to filling the buffer, with any entries beyond 3 additional ones over-writing the top. In addition, multiple repeated searches can influence system response particularly when loading from a file input, so by using ORDER and the other words we can examine and clean up the search path;
ORDER
SEARCH ORDER: FORTH SOUND FORTH MOUSE VIDEO FORTH ROOT
NEW WORDS: FORTH
OK.
ONLY ALSO VIDEO ALSO MOUSE ALSO SOUND ALSO FORTH OK.
ORDER
SEARCH ORDER: FORTH SOUND MOUSE VIDEO ROOT
NEW WORDS: FORTH
OK.
This condition can also be avoided by following the standard vocabulary set up mentioned below, in that the targeted vocabulary to add is processed before the ALSO word;
80386 fig-FORTH v2.31
Implemented 04/09/03 by MB
ORDER
SEARCH ORDER: FORTH ROOT
NEW WORDS: FORTH
OK.
VIDEO ALSO MOUSE ALSO FORTH OK.
( other operations performed when a need is seen)
SOUND ALSO FORTH OK.
ORDER
SEARCH ORDER: FORTH SOUND MOUSE VIDEO ROOT
NEW WORDS: FORTH
OK.
This requires that your targeted vocabulary is always the last specified in the command;
80386 fig-FORTH v2.31
Implemented 04/09/03 by MB
VOCABULARY MYTASK IMMEDIATE OK.
FORTH ALSO VIDEO ALSO MOUSE ALSO OK.
MYTASK DEFINITIONS OK.
ORDER
SEARCH ORDER: MYTASK MOUSE VIDEO FORTH ROOT
NEW WORDS: MYTASK
OK.
( other operations performed)
SOUND ALSO MYTASK OK.
ORDER
SEARCH ORDER: MYTASK SOUND MOUSE VIDEO FORTH ROOT
NEW WORDS: MYTASK
OK.
Although the definition of any word or sub-library can be placed into any vocabulary within the user space, it is convention to isolate specifically related functions from other, more general ones. While the level of isolation is purely up to the programmer and the task currently at hand, convention dictates that any application be isolated first to itself, then from the other areas of the system. This arrangement also means that the words listing produced by VLIST will correspond to the area of the application the programmer is currently working in, while other words which may prove distracting are not displayed. Given the nature of the Search Order Buffer and the word commands that control this list, this implementation also results in a very natural one so long as each application belongs to a vocabulary of its own. An example;
80386 fig-FORTH v2.31
Implemented 04/09/03 by MB
ONLY VOCABULARY MYTASK OK.
FORTH ALSO OK.
MYTASK DEFINITIONS OK.
ORDER
SEARCH ORDER: MYTASK FORTH ROOT
NEW WORDS: MYTASK
OK.
This sequence of steps creates a new vocabulary of MYTASK as an off-shoot of the ROOT order, caused by using the ONLY word as the first control function. Please note that the word VOCABULARY does an implicit ALSO function when it is executed, thus allowing the addition of the FORTH and MYTASK vocabularies within the context of English meanings.
In simple terms, this means that when MYTASK is created it duplicates the ROOT order in the search buffer, then the word FORTH adds the Forth language replacing ROOT as the top item in the search list. When ALSO is executed the FORTH entry is then duplicated, and the copy is replaced by MYTASK in the next line. When DEFINITIONS is executed the top Search Order Buffer item is made the compilation target, in this case MYTASK because it was the last accessed list. A complete, step-by-step examination of this process appears below;
80386 fig-FORTH v2.31
Implemented 04/09/03 by MB
ONLY OK.
ORDER
SEARCH ORDER: ROOT
NEW WORDS: ROOT
OK.
VOCABULARY MYTASK OK.
ORDER
SEARCH ORDER: ROOT ROOT
NEW WORDS: ROOT
OK.
FORTH OK.
ORDER
SEARCH ORDER: FORTH ROOT
NEW WORDS: ROOT
OK.
ALSO OK.
ORDER
SEARCH ORDER: FORTH FORTH ROOT
NEW WORDS: ROOT
OK.
MYTASK OK.
ORDER
SEARCH ORDER: MYTASK FORTH ROOT
NEW WORDS: ROOT
OK.
DEFINITIONS OK.
ORDER
SEARCH ORDER: MYTASK FORTH ROOT
NEW WORDS: MYTASK
OK.
This creates a very easy interface to remember. Subsequent vocabulary references, such as calling upon a function within the VIDEO library, will replace the top entry of MYTASK in the Search Buffer as shown below;
VIDEO OK.
ORDER
SEARCH ORDER: VIDEO FORTH ROOT
NEW WORDS: MYTASK
OK.
VID @ 1K . ( get screen location )
MYTASK 1K.
ORDER
SEARCH ORDER: MYTASK FORTH ROOT
NEW WORDS: MYTASK
1K.
Since the compilation vocabulary is always the first searched in each list, the temporary replacement of MYTASK in the top Search Order Buffer location is harmless in this instance. As shown below however, the permanent addition of the VIDEO vocabulary may be achieved in the same manner as the Forth language as in;
80386 fig-FORTH v2.31
Implemented 04/09/03 by MB
ONLY VOCABULARY MYTASK OK.
FORTH ALSO OK.
MYTASK DEFINITIONS OK.
(set up the condition listed previously)
VIDEO ALSO MYTASK OK.
ORDER
SEARCH ORDER: MYTASK VIDEO FORTH ROOT
NEW WORDS: MYTASK
OK.
In the previous examples the MYTASK vocabulary was to be part of the ROOT search order system, but this is not always preferable or desired. To make the MYTASK vocabulary a part of the FORTH system for example, one must only ensure that FORTH is the active vocabulary when MYTASK is created. In this case, the ONLY word is omitted in the command;
80386 fig-FORTH v2.31
Implemented 04/09/03 by MB
VOCABULARY MYTASK OK.
MYTASK DEFINITIONS OK.
ORDER
SEARCH ORDER: MYTASK FORTH ROOT
NEW WORDS: MYTASK
OK.
Now the MYTASK word list is part of the FORTH vocabulary, because that library of functions was active at the time of the vocabulary's creation. As before, additional vocabulary lists may be added as shown above;
80386 fig-FORTH v2.31
Implemented 04/09/03 by MB
VOCABULARY MYTASK OK.
VIDEO ALSO OK.
SOUND ALSO OK.
MYTASK DEFINITIONS OK.
ORDER
SEARCH ORDER: MYTASK SOUND VIDEO FORTH ROOT
NEW WORDS: MYTASK
OK.
This creates a very simple multiple vocabulary interface, requiring a bit of thought but a very English styled result. Please note however that if the compilation vocabulary is not the top Search Order Buffer item or the last vocabulary referenced, any attempts at using FORGET to remove word entries will be met with an error. (See Controlling the Dictionary Space under Forget.)
As was seen in the prior examples the creation of a new vocabulary is exceedingly easy, though deciding where they should be located can be a complex process. In addition, a vocabulary like any word defined within the address space can optionally be "immediate," or acted upon by the compiler the moment it is parsed from the input stream. When this quality is applied to vocabularies it allows for on-the-fly search order changes, but only to the extent of the top Search Order Buffer item. As an example;
80386 fig-FORTH v2.31
Implemented 04/09/03 by MB
VOCABULARY MYTASK IMMEDIATE OK.
MYTASK DEFINITIONS OK.
: NEW-WORD 9 0 DO I . LOOP ; OK.
PREVIOUS DEFINITIONS OK.
: TEST-WORD ." HI!" CR NEW-WORD CR ; NEW-WORD? Huh?
: TEST-WORD ." HI!" CR MYTASK NEW-WORD FORTH CR ; OK.
Examine the last two user lines carefully. The first line failed because the MYTASK vocabulary was removed from the search order by the PREVIOUS DEFINITIONS line before defining TEST-WORD, while the second line succeeded because the MYTASK word in the line forced the temporary replacement of the top search item within the listing. On the other hand if the MYTASK vocabulary is not made immediate, the following will occur;
80386 fig-FORTH v2.31
Implemented 04/09/03 by MB
VOCABULARY MYTASK OK.
MYTASK DEFINITIONS OK.
: NEW-WORD 9 0 DO I . LOOP ; OK.
PREVIOUS DEFINITIONS OK.
: TEST-WORD ." HI!" CR NEW-WORD CR ; NEW-WORD? Huh?
: TEST-WORD ." HI!" CR MYTASK NEW-WORD FORTH CR ; NEW-WORD? Huh?
In this case the compiler has added the token address of the MYTASK vocabulary word to the TEST-WORD list rather than executing the vocabulary function to change the search order. If such a reference is desired without making the target vocabulary immediate there are two options; 1) add the vocabulary to the search order given in the methods mentioned earlier, or 2) manually execute the referenced vocabulary as in the following definition;
: TEST-WORD ." HI!" CR [ MYTASK ] NEW-WORD FORTH CR ;
Whether or not a vocabulary is made immediate is optional depending upon its intended use, such as in the case in where the vocabulary which forms complete subroutine and is not expected to have many references to it by outside programs. (Such as the EDITOR which has a single entry point, and two references which are added to the root path.)
If a vocabulary is not immediate as in the prior example, this allows Forth to change the active search order to meet the specified task. An example would be in a case where the user is expected to enter data containing highly different search parameters, such as typing the names of automobiles in one case and those of baseball stars in another. If both vocabularies are not made immediate and the user switches between search programs, this allows that the compiler can actively change the search order between the two functions;
: SWITCH VOC 1 TOGGLE VOC @ IF AUTOMOBILE ELSE BASEBALL THEN ;
Such a statement will change the current search order from within an application, using a single variable to hold notice of the change as the operation continues.
The unmodified Fig-Forth v2 contains a number of vocabularies, of which the available ROOT and FORTH lists are a part. In the interest of clarity each vocabulary contains definitions associated with their title, isolating functions of equal type together and those which may cause the novice programmer difficulty. Assignment to any location is arbitrary. These vocabularies and their purposes are outlined briefly in table 6-1.
vocabulary | contents |
ROOT | Contains all other vocabularies, the search order functions, file opening and loading, system exit, vocabulary list, creation and forgetting. |
HIDDEN | This vocabulary contains all low-order compiler tokens; syntactical and system stack checks, search and compile operations, plus the system debugger link. |
FORTH | Contains the basic Forth Language and file streaming functions, and is the only vocabulary capable of adding new definitions. |
MOUSE | Contains the operational functions for driving the system mouse, arrow and hour glass bitmaps, plus the rudimentary modem connections. (See Advanced Input Output.) |
SOUND | Contains operations for simple Sound and Music support. (See Advanced Input Output.) |
VIDEO | Contains all the operations required to control the system video screen, including multiple graphic modes and functions. (See Advanced Input Output.) |
Once the vocabulary for an application is established and selected as the target of the compiler process, the programmer's task falls to the definition of operational subroutines to meet the application's functions. As outlined briefly in the Overview section, these subroutine lists are constructed by executing the CREATE word, or any compiler function which calls CREATE. Some of these processes are the VARIABLE, CONSTANT and their multi-word counterparts, as well as CODE, <BUILDS, ARRAY and several other functions. In most cases however, the CREATE function is initiated by the execution of the colon character or word, followed by the text name of what the new function is to be called;
: NEWWORD -- This builds the start of a token subroutine list.
Function names can contain 1 to 31 characters in total, and may be case sensitive given the value stored in the CASELOCK variable. Subsequent token values in the definition are added to the list in the order in which they are received, foregoing any compiler directives such as IF, THEN, etc. or the BEGIN and DO loop functions. When these words are encountered the compiler actions described in Chapter 5 are enabled, placing within the current list the proper tokens required for the type of change desired. Thus;
: NEWWORD ( f -- ) IF ." That value was true." ELSE ." That value was false." THEN ;
This example demonstrates a typical case of creating a test report function, one which takes a value from the stack and prints a message of its logical condition. Once the header of NEWWORD has been added to the current dictionary, the IF compiler directive is added to the list, followed by the ." and the first enclosed string. Next the ELSE word adds its branch function and closes the relative jump created by IF, followed by a second ." and the second string. Finally, THEN closes the ELSE relative jump followed with an end of list token ; added by the semi-colon.
When the token list contained above is executed a single value is required on the parameter stack, or a stack under-flow error will be generated after the NEWWORD has completed execution. This causes the following results when the word is run;
0 NEWWORD That value was false! OK.
1 NEWWORD That value was true! OK.
NEWWORD That value was true! NEWWORD? Stack empty!
Once the NEWWORD list is created without compilation errors the symbol becomes part of the active vocabulary, in that it may be run as shown above or used in a subsequent definition as a subroutine as shown below;
: TEST 5 0 DO I 3 = NEWWORD CR LOOP ; -- Sample of use
This new list of TEST will create the following output when run;
TEST That value was false! -- The loop is at 0
That value was false! -- The loop is at 1
That value was false! -- The loop is at 2
That value was true! -- The loop is at 3
That value was false! OK. -- The loop is at 4 & ends
One of the advantages of this extensibility of the defining vocabulary is that Forth allows the programmer to construct a set of functions intended to meet the current application, whatever it may be at the time. Such an example is presented below for the purpose of moving a robotic arm;
: ARM-ON 1 &4CF PC! ; -- turn on arm servo port
: ARM-OFF 0 &4CF PC! ; -- turn off arm motor port
: ARM-TICK &4CF PC@ 2 AND ; -- detect arm position tick
: WAIT-ARM BEGIN ARM-TICK UNTIL ; -- wait for an arm position tick
: MOVE-ARM ARM-ON 0 DO -- turn on motor and start loop
WAIT-ARM LOOP ARM-OFF ; -- wait for n arm ticks & shut down
10 MOVE-ARM OK. -- move arm 10 ticks.
Finally, as discussed briefly in Chapter 2 Variables and Math, Syntax and Type, Fig-Forth's input processor allows the construction and operation of "dotted" functions. This input process allows for the use of source embedded object oriented operations, with either tight or loose bonding as is desired;
: .PH ( ADR -- ) 2@ <# # # # # 45 HOLD # # # #> TYPE ; -- print phone number
150 ARRAY CUSTOMER -- data area
35 +OFF .ADDRESS -- address location
43 +OFF .CITY -- city location
30 +OFF .ZIP -- Zip Code location
10 +OFF .PHONE -- phone number location
CUSTOMER.PHONE.PH 347-1121 OK. -- print phone number
The resulting construction of this use of the dotted input processor would be equivalent to calling each function and sub-function in order, or entered in the source code as follows;
CUSTOMER .PHONE .PH
Care however must be employed in this use of the input processor, in that the words are not confused with their non-dotted equivalents;
MINE.R -- will look for a word named MINE and then execute a .R operation.
As stated in Chapter 2, these "dotted" access words use the character held in the system variable NAE+2 to separate terms, and the +OFF word cannot be used unless the first character in the symbol name matches the character in that location.
As shown above all parameters to a definition are intermixed upon the Parameter Stack, and it is the programmer's responsibility to maintain the order of these values with their expected type. Parameters may be placed upon the stack before operation or as part of the definition, or can be processed from the modem, keyboard, mouse or file type device. To re-order the values on the stack, see the Stack Operation words in Chapter 4.
Fig-Forth v2 utilizes three highly different file types for programming source and overlay generation, all of which are available at any time. The three file types are Text, Compiled Overlay and Binary Executable, of which the last forms the Fig-Forth package itself. Compiled Overlay files come in two distinct varieties, those created by users and those created as program patches to the kernel itself. The user is not expected to create or apply the techniques of the patch variety of these files, but may freely use the overlay version. (See Advanced Procedures and Functions for description.) The final file format is that of Text Similar files, 16 lines of 64 characters each.
This word attempts to open a file using the MS-DOS system call located at interrupt 21 hex, following the standard 8 and 3 character format of such files. A single value is required on the stack at the time of execution, and the word requires the file name to follow OPEN up to the next space. Therefore, spaces can not be part of the file name to be opened;
20 OPEN MYFILE.DAT -- opens "myfile.dat"
This word will attempt to read the input from the Disk Block Number given it, interpreting the text or overlay format file as required. Though LOAD is intended for program source screens which require an explicit Arrow (-->) to move from block to block, if a properly formatted overlay file is detected Fig-Forth will process the overlay until the end is found.
20 LOAD -- begins the load process at block 20.
This word is similar to LOAD except that only overlay files will be processed, and if such a file is not formatted correctly those portions of invalid construction will be skipped. Note that overlays must reside in the same memory location where they were compiled, and the dictionary links they call must be in the same state as when the overlay was created. (See Advanced Procedures and Functions.)
20 LINK -- read overlay at block 20.
This word performs the functions of OPEN and LOAD at the same instant, offering a convenient method for adding functions to the dictionary. Like both LOAD and LINK, this word requires a block screen number as the start of the function, and as with OPEN requires a file name to follow the word. In addition, if an overlay file is the target of the GO function the last word to be linked into the dictionary space will be executed upon completion of the link, creating a self-executing subroutine.
1 GO MYFILE.4TH -- read source file "myfile.4th" starting at block 1.
As in other disk primitive versions of Forth, Fig-Forth v2 uses Block Screens for all file input, output and program source material. These screens are defined as 1024 bytes each, consisting of 16 lines by 64 characters. However, rather than utilizing direct drive access Fig-Forth v2 applies this definition to MS-DOS styled file access, this type of interface being used for a variety of reasons. Of chief concern to the programmer is the development of program source text, for which a special text editor must be employed. This editor must be one that can manage the blocking and de-blocking of program source lines without carriage returns or other control characters, to mimic the keyboard input and meet the specification stated earlier.
Such an editor is included with the package, in the file named EDIT.4TH of the main directory. It is recommended that it be loaded immediately upon starting a Forth session, and can optionally be saved as a part of the system executable as desired. A typical line to cause the editor to load is;
1 GO EDIT.4TH
For those who may have earlier renditions of this package the Editor has gone through quite a few changes recently, several functions of which operate differently depending on the mode selected from previous versions of the package. The new package can perform all of the functions of the prior version plus many new operations, so the screen display has been altered significantly to identify the new program. A help menu is also provided, as is this text.
The Advanced Block Editor program is constructed as part of the ROOT vocabulary when it is loaded, comprising a word list that is hidden from the user and 3 entry points within the default search path. Each of these entry points may be typed at the keyboard to begin the editing function, providing a file has been opened for that purpose. To open a file use a line similar to the one below;
20 OPEN MYTASK.4TH OK.
Please note that the file must already be present on the disk drive, or an error will be generated. In the event a new file is required Fig-Forth can call the DOS shell to create it, as in the line which follows;
CMD" COPY OLDFILE.EXT NEWFILE.4TH" OK.
This line will call DOS and make a copy of an old file that exists in the Forth directory, calling it by the new name. Then you can open the new file as shown in the above example, where Forth will assign it an address location and read the current length for subsequent review. Once the file is opened the editor can be started in a similar manner, giving the command of;
20 EDIT
At this time the screen will be forced to a text mode if not currently in it, all text will be erased and the editor screen will appear;
Scr# 20 MYTASK.4TH ---------------------------------------------------------- | cuts=0 | | ( repeated 12 more times ) | | | ---------------------------------------------------------- | 0 | | Press F1 for help....
The upper window in the above diagram is the text area contained in the file, while the lower window is a "wrap buffer" composed of 4 lines and is explained below. By convention, the first line of any block is intended to contain a Forth comment, typically the name of the task, the date of writing, the author's initials and a comment about what the block contains. The other 15 lines are used for source text.
One of the first discoveries you may make is that the editor unilaterally prints all ASCII values into the text area, even those that make up carriage return, line feed, backspace and others. In doing this the editor allows that files of other types may be edited as well as source screens, and that text files may be edited to form source blocks. In addition, this allows the input of characters not available from the keyboard, such as foreign symbols and graphic characters. (See special editor functions below.)
For the purposes of debugging a compilation the Editor has two additional entry points, the VIEW and REDIT words. REDIT is used to return to the last block viewed or edited by the user, while VIEW is used to point out the location of where an error occurred. For example;
20 LOAD THEN? Check Pairs! 2K.
The above line and result indicates an error has occurred within the compiling process, in this case a THEN that is not properly nested with an IF word. To find this error we have two options available to us, the first of which is to call for a words listing using VLIST. The definition where the error occurred will be listed in violet ink, wherein we can start the Editor and hunt through the file for it. However, Fig-Forth has provided us with two values on the stack, the block number and location where the error was detected. Typing VIEW will then start the Editor and show us precisely where the compiler located the fault, which saves time.
In addition to the above entry points the Editor file also contains two shortcut routines, GG and HH. These are designed to make editing multiple files easier. The GG word takes the location of two block files then starts the editor, swapping between the two files by pressing <Esc> twice. HH does the same function but switches between 3 block files, or any 3 locations within a single file. Both HH and GG use values on the stack for this switching operation, and will remember the values as changed while editing. To exit either of these functions press <Esc> and <Enter>, which forms an Editor exit command and an end of edit signal to these words.
The Editor has a number of keys that navigate over the source file, of which the keyboard arrows are an obvious collection. Page Up will move from the current screen to a lower numbered one, while Page Down will move to the next higher. Note that if any screen is changed it will be updated internally, causing Forth to write the block to disk the next time it attempts to use that buffer. Thus in the event of accidental change the editor should be exited immediately by pressing <Esc>, then the word EMPTY-BUFFERS should be executed. As Fig-Forth currently contains 4 disk buffers in the user space, this must be done within 3 page-up or page-down operations.
The keyboard End key functions as one would expect, moving the cursor to the end of the current line or to the far right of the display area. Home performs the opposite function of End, moving the cursor to the start of the current line. If Home is pressed while the cursor is already in the zero column, the cursor is moved to the top of the screen block.
Control Left Arrow and Control Right Arrow are used to skip from word to word on the current screen, in the direction of the arrow shown on the key top. This function will catch any non-space character even if it has no apparent screen image, such as the graphic block character which turns all pixels off.
Finally, the Editor contains a single bookmark and Home function, which can be used to return to any screen within the current file. Pressing Alt-M will mark the location to be saved and Alt-G will return to it, without passing through the screens contained in the interim. Pressing Alt-H is the file Home key, which moves to the first screen within the current file being edited. Note this function does not span files, simply returning to the first block in the current file of focus. (See also HH and GG above.)
The editor program operates in one of three distinct modes, as displayed above the count of cuts made to the Line Buffer. The default mode is the Over-Write function, which accepts characters from the keyboard and replaces those on the Block with the input. This mode is signaled by having no notice above the "cuts=" entry, and does not use the Wrap Buffers. Character deletes will roll characters right of the cursor to the left, for the current screen line where the cursor appears.
The second edit mode is that of Insert, in which keyboarded text is inserted at the location of the cursor. All characters to the right of the cursor will be rolled towards the right edge, while any characters reaching the far right will be lost on the next roll. As above, character deletes will roll characters right of the cursor to the left on the current line.
The final edit mode is that of Wrap, which is a super-extended version of the Insert mode. As before characters will be inserted into the text at the point of the cursor location, but in Wrap mode the entire block of data will be rolled down one location for each keystroke. This mode does use the Wrap Buffer located at the bottom of the screen, as characters reaching the end of the last text line are transferred into the hold space. This same extended roll applies to character deletes, giving the work space an additional four lines for text editing.
The Wrap Mode also updates the number displayed beside the wrap window, which indicates how many characters are saved in the buffer. This value is used by the wrap command defined under the Alt-W key sequence described below, as well as any insert or delete operation that is performed. Note that characters from the text window will not be transferred to the wrap buffer unless the following conditions are valid;
1) The Editor is operating in Wrap Mode and,
2) the Wrap Buffer contains valid characters as indicated by the value,
3) or the 15th line of the Text Window contains non-blank characters.
For all of the various modes the Editor contains several function keys, similar to the Alt-M, Alt-G and Alt-H functions listed above. Some of these functions change their definitions according to the edit mode selected.
<Enter>
In all modes this keystroke will break the current line at the location of the cursor, rolling any remaining characters down one line and placing the text to the right of the cursor in column zero. If the mode selected is over-write or insert lines reaching the bottom of the text area are lost, while in wrap mode they are transferred to the wrap buffer.
Function F1
This brings up the editor help menu, replacing the current text area for review. Any key pressed after this display will return to the editing function.
Function Alt-F1
This key combination will will scan the current file for the word symbol that the cursor sits on, allowing you to find any prior instances of the word in the file up to the screen you are editing. The search will stop and display "Found..." with the cursor after the word located, then will wait for an <Enter> key to return to the screen being edited or a <Space> which will search for the word again until the editing screen is reached. The search buffer data (described below) is destroyed by this operation.
Function F2
This is the Editor Search text function, locating a given string upon the current screen block. If the string is not found the cursor will be deposited at the end of the screen.
Function Alt-F2
This key asks for the string to be found using the F2 operation, which is placed into a separate buffer so the search can be repeated. Please note that all searches in the editor are case insensitive, to allow for searches covering wider file types.
Function F3
This is the Editor text Replace function, replacing the word found with F2 with the one saved below. Please note that this function will take place wherever the cursor currently resides, deleting the number of characters contained in the search buffer and inserting its replacement string. As in other functions calling delete or insert, this key will use the wrap buffer in the wrap mode.
Function Alt-F3
This key asks for the replacement string to the one found in the F2 operation, placing itself into a separate buffer so the operation can be repeated. Note that the string is replaced immediately after entry, at the current cursor location. (So search first!)
Function F5
The F5 key is used to delete the line the cursor currently sits on, rolling all other lines up one location. If in wrap mode lines from the wrap buffer are pulled as well, filling in the gap caused by the deleted line.
Function F6
This key has two similar but different definitions behind it, depending on the type of mode selected. The first of these functions is to "join lines" at the current cursor location, or roll characters from the next line to the current. In over-write and insert modes this joining comprises only the line directly beneath the cursor, and the key cannot be used on line 15. In the wrap mode however this key functions as a "delete all spaces" operation, gobbling up white space at the cursor's location until a non-blank is found. Because this operation uses the delete character operation, lines are rolled out of the wrap buffer as needed to meet this function.
Functions Alt-F5 and Alt-F6
These two keys perform the opposite function of their non-Alt counterparts, inserting a line of 64 spaces when the editor is in wrap mode. While it is possible to create space between two lines by pressing ENTER in all of the editor modes, these functions will create a hole the length of one line automatically starting with the current cursor location. As with all wrap operations this function uses the wrap buffers. The cursor will be returned to the point where the insert was made, or the end of the current screen minus one line whichever is less.
Function F7
This key will "cut" or copy the line the cursor is presently on into a Nth line buffer, advancing the "cuts=" count and moving down to the next line. All lines thus copied go into the free ram between PAD and SP@, minus the 512 characters reserved to preserve the system memory. If insufficient ram exists to make any cut, the system console will issue an error beep. Note: because the area between PAD and SP@ is used, lines cannot be preserved if a compilation operation takes place between the use of F7 and F8.
Function Alt-F7
This key combination will copy the entire screen of 16 editor lines into the Nth line buffer and advance to the next screen, updating the "cuts=" count as above. Note that if insufficient memory is present the system will issue an error beep for each line attempted yet the function will still perform a Page Down operation. As with all Nth cuts, lines saved cannot be preserved if a compilation operation takes place between the use of F7 and F8.
Function F8
This key performs the opposite function of F7, pulling out the saved lines in the order they were cut. Lines pulled in this fashion replace the line where the cursor resides.
Function Alt-F8
This key combination will "pull" an entire screen of 16 editor lines from the Nth line buffer and advance to the next screen, updating the "cuts=" count as above. Should the line buffer become empty this operation is equivalent to a Page Down operation. Note that both Alt-F7 and Alt-F8 assume the current editing position is at the top of the screen, such that improper placement may cause incorrect operation.
Function F9
This operation allows the setting of a maximum limit to the search operation, such as the end of the current file. While F2 searches a single screen using this key and F10 below allows the whole file to be searched, or any portion of it.
Function F10
This is the extended search function made available by F2. This key will repeat the last search until the block number entered by F9 is reached or the string is found, displaying the point at where the search ended. All searches begin at the current location of the cursor, and proceed to higher numbered blocks.
Function F12
This function of the Editor is a macro operation, echoing keystrokes to the editor as recorded down below. Most functions of the Editor are available for use within macros, with the exceptions of the search string input, the replace string input, the maximum search block number input and the Alt-P printer codes. Even GG and HH can be executed within a macro, as well as navigation and mode change keys.
Function Alt-F12
This function will record keystrokes made inside the Editor, up to the limit of 255 operations. Should the macro overflow the first characters saved will be over written. As stated above only those operations that call interpret are not supported in macro, namely text search and replace input operations, and that of printer codes. Recording is stopped by pressing this key combination a second time, and the display will indicate the number of characters saved in the buffer.
Alt-Z
This key combination will erase the wrap buffers and fill them with spaces, then update the screen.
Alt-X
This function will erase the current block and the wrap buffers, essentially starting out with a fresh block of the file. Note however that this function does not set the update flag of the block erased, so it maybe recovered before any editing is performed by exiting the editor, using EMPTY-BUFFERS and REDIT to restore the text. The contents of the wrap buffers cannot be recovered.
Alt-O
This is the Editor Open Block command. The function will scan forward in the file for the distance of 250 block entries, attempting to locate a screen that contains only ASCII spaces. If such a block is located all blocks between the current one and the empty location are rolled down one slot, leaving a copy of the current screen which can be modified without loss of the text. If no such block of spaces can be found the key generates a system error beep and displays the words, "Empty not found."
Alt-W
This is the Editor Wrap Blocks function, which moves the text contained in the Wrap Buffer onto the next screen. Like Alt-O this function pre-scans the file to locate an empty block before operation, then proceeds to roll text from the Wrap Buffer onto the next screen, and then the next, etc., until either the empty block is located or the Wrap Buffer becomes empty. (As in having 3 lines saved in the wrap buffer and two lines available on the next block, with one available line on the block after that. The function will halt on the third screen.) The insertion point for this operation is on program line #1 of the convention mentioned above, or the second line to appear in the text window. This allows the function to move program source without disturbing any title comments. This function operates only in the Wrap Mode, and inserts all characters contained in the wrap buffer even if they are spaces, so long as a valid character remains in the buffer.
Alt-P
This function is used to enter Printer or other display codes into a screen block, by asking for the ASCII value of the character to be inserted at the cursor location. The number entered should be in decimal, to which base the editor defaults.
Alt-1 through Alt-8
These last key functions of the Editor set or reset individual bits of the character where the cursor now resides, bits numbered 1 to 8 as the keys themselves. Again, this is for the entry of printer and other codes, but may be used for graphics or other functions.
The Editor is exited by pressing the <Esc> key, then optionally hitting <Enter> if the HH or GG word is run. At this point all changed blocks have been updated internally by Fig-Forth, which can be forced to the disk drive by saying FLUSH. If the edits are not desired say EMPTY-BUFFERS before any disk access is attempted, because Fig-Forth will write out the changes as each buffer is rotated in the use list. When the editor is exited a line stating the last screen edited will be printed at the bottom of the screen, because the title value rolls off.
The current version of the Editor is 1.7, which includes four additional functions inside the default build of the source code. Two of these operations have long memory equivalents on the screen block following the Editor source text, plus a function to adapt older styled Fig-Forth source to the current environment. These functions are listed below;
.M
This operation will display 112 bytes of user RAM starting at the address given it, returning the address of the next location to be displayed on the stack. The numeric base is changed to Hexadecimal for both addresses and values in the display, and the screen characters represented by the bytes will appear to the right of the values.
.B
This word performs the same task as .M above, but returns the starting address of the displayed RAM block as unchanged. (I.e.; a DUP .M DROP sequence.)
L.M and L.B
These operations perform as .M and .B above but require both an Offset and Segment location for the portion of RAM displayed. Note that none of these functions will span segments, wrapping around to address 0000 from FFFF hex. The long memory versions must be loaded manually before use.
LOWER-BLOCKS
When this function is called with an Ending Block Number plus one and a Starting Block Number, it will scan the block range specified and change all uppercase ASCII characters to their lowercase equivalents. This function must be manually loaded from the screen where L.M and L.B appears.
?? and SEE
These two words form a very simple decompiler for Fig-Forth dictionary words, attempting to display the source text from which the definition was constructed. The process is begun by using the SEE word followed by the definition desired to be examined;
SEE EDIT
0 1561
DUP 234
...etc.
As shown above, on each subsequent line the SEE word will attempt to display the Fig-Forth source word and the address it represents in decimal. The function will stop and wait for an input from the console before displaying the next value, for which the <Enter> key will halt the process and returns the next address to be processed.
Because of the simplicity in the above routine the programmer must interpret the output for proper comprehension, as in the following sequence which forms the start of a DO-LOOP with the values of 10 to 15.
LIT 238
TVbG 15
LIT 238
*-?> 10
(DO)
Note that the values after the LIT lines are the constants used by the code sequence, such that the SEE word cannot find a suitable dictionary entry for the value and a random string of characters appears. The same type of operation can occur when displaying string constants, as in a typical output of below;
SEE EDD
...
(.") 8234
{_______ -23451
*^{yU 767
EDIT -34
As so on. While it is the interpretation of such contained strings as tokens that is the source of this error, with the results as shown above, this particular error may be avoided by proper use of the other functions;
SEE EDD
...
(.") 8234 1K. -- user types Enter to exit
.B -- string is displayed in memory dump
COUNT + -- adjust address to skip over string
?? -- restart decompile function
DUP 131 -- next word appears.
Note that most user defined dictionary functions end with the word (;S) which forms the Forth "return to caller" operation.
This Editor is based upon my own and Frank Sergeant's Pygmy Editor source code, using many ideas from Frank plus the extra functions of my Fig-Forth Editor written in the 80's. The source screens for the Editor are available to you in the file EDIT.4TH, but I'm not going to discuss this file because the screens are very busy and space compressed. (I tend to like the Editor to take up less than 20 blocks, so my program files can start at 20.) Write me if you feel you have any suggestions for the Editor.
Fig-Forth v2 contains several words for the purposes of controlling the dictionary space and its search order, however only 4 of these words are useful to the user. (The others will be discussed in Advanced Procedures and Functions.) The first word is the HERE function which returns the address of the current dictionary tail, into which all parsed input passes during compiler operation. The second function is that of PAD which returns an address 88 bytes beyond the point of HERE, and is used by Forth for number printing routines. The third word is the FORGET function, which removes definitions from the user space.
The FORGET word discards all definitions made after and up to the word that follows the command itself. Thus if NEWWORD is the highest function to be forgotten as well as all functions beyond it, the command string would appear as;
: NEWWORD .... ; OK.
: MYLIST .... ; OK.
: LOOKHERE ... ; OK.
FORGET NEWORD OK.
At this point all words after NEWWORD have been removed from the dictionary space, including their token lists. In the event of an error in compilation this same method can be applied, retyping the definition of the word prior to the one causing the error;
: LOOKHERE ." Bytes Used: " HERE . ; OK.
: NOTTHIS ." I'm at: " TETO ? ; TETO? Huh?
At this point you can FORGET LOOKHERE and recompile both LOOKHERE and NOTTHIS, but the NOTTHIS word cannot be forgotten because it contains an error;
FORGET NOTTHIS NOTTHIS? Huh?
This brings us to the 4th and final word for controlling the dictionary space, SMUDGE. SMUDGE is the function the compiler uses to mark that a definition has been completed properly, or at least has managed to compile without errors. Words that have not been smudged or are smudged a second time are marked as invalid, appearing in violet ink on a VLIST. So when an error occurs during direct keyboard input use SMUDGE and FORGET to remove the bad word;
: NOTTHIS ." I'm at: " TETO ? ; TETO? Huh?
SMUDGE OK.
FORGET NOTTHIS OK.
Note that SMUDGE will only operate upon the last definition in the dictionary, and cannot be used with parameters. Finally, when using FORGET on vocabularies the host vocabulary must be the active, top order vocabulary before the FORGET word, or an incorrect search path may result and lock up the system;
80386 fig-FORTH v2.31
Implemented 04/09/03 by MB
VOCABULARY MYTASK IMMEDIATE OK.
MYTASK DEFINITIONS OK.
: NEW-WORD 9 0 DO I . LOOP ; OK.
: TEST-WORD ." HI!" CR NEW-WORD CR ; OK.
FORGET MYTASK OK.
: TRYTHIS ." HI!" CR 9 0 DO I . LOOP CR ; (system no longer responds)
The only cure for this situation is to shutdown the package or computer and re-start Fig-Forth, because the search order has been irreparably damaged. However, had the search order been properly re-established before the FORGET the lock-up can be avoided;
80386 fig-FORTH v2.31
Implemented 04/09/03 by MB
VOCABULARY MYTASK IMMEDIATE OK.
MYTASK DEFINITIONS OK.
: NEW-WORD 9 0 DO I . LOOP ; OK.
: TEST-WORD ." HI!" CR NEW-WORD CR ; OK.
PREVIOUS DEFINITIONS OK.
FORGET MYTASK OK.
: TRYTHIS ." HI!" CR 9 0 DO I . LOOP CR ; OK.
The easiest way to avoid this condition and any possible confusion over the number of ways it can arise is to follow the convention of always placing your application vocabulary inside the ROOT or FORTH vocabularies, as shown in the earlier sections and using the process of forgetting displayed up above.
Fig-Forth v2 contains many words for the purposes of controlling the compiler operation, only the most basic of which have been examined in previous chapters. While the use of these operations is relatively safe for the beginning programmer in the operation of Fig-Forth, a brief overview of these functions is outlined in the following table;
word |
stack/parms |
function |
[ |
-- |
Turn compiler off, run the words that follow. |
] |
-- |
Turn compiler on, compile token list that follows. |
' |
(-- name) |
return PFA address of word which follows |
['] |
(-- name) |
return PFA address of immediate word which follows |
CFA |
adr -- adr |
adjust PFA address to CFA address. |
[COMPILE] |
(--name) |
Compile the immediate directive word which follows |
HERE |
-- adr |
return address of first free dictionary byte. |
IMMEDIATE |
-- |
mark last defined word as run only. |
LATEST |
-- adr |
returns the address of the last definition. |
LFA |
pfa -- adr |
point to Link Field Address |
NFA |
pfa -- adr |
point to Name Field Address |
PFA |
adr -- adr |
point to Parameter Field Address |
SMUDGE |
-- |
Set completion flag of last definition |
See Advanced Procedures and Functions for a description of these words and others similar to them.
As of version 2.26, the Fig-Forth compiler now supports library files of source text blocks and compiled program overlays. The default file, FIGFORTH.LIB, is expected to be a part of the current Forth directory or path, and may be constructed within the editor or from the operational kernel using a free-form format defined by the programmer. The package you receive may or may not contain such a file. Two words are defined to access this compiler feature, the first being the LIBRARY operation;
LIBRARY C:\FORTH\MYTASK.LIB -- specifies the file spec of the current library
This word sets up the library for later access, parsing the given file name and path from the input stream and adding it to the end of the current dictionary. Note that the file specified need not be open at the time of executing the LIBRARY word, and is not checked for validity. The file will remain closed until a reference is requested as shown below. When the LIBRARY word is run an internal constant is set to point to the given string, which may be modified by executing a ' LIBRARY ! sequence after placing a counted string address on the stack. e.g.;
," C:\FORTH\NEW.LIB" ' LIBRARY ! -- change the library file
The default file name location is two bytes beyond the LIBRARY definition, such that the following sequence resets the operation to its default state;
' LIBRARY DUP 2+ SWAP ! -- select standard file FIGFORTH.LIB
A zero saved into the Library pointer disables the operation, and all reference requests will generate an error. References to the library specified are made with the NEEDS word, followed by the name of the function or block header requested;
NEEDS EDITOR -- loads the editor from the library file.
When NEEDS is executed the next space delimited word is parsed from the input device, then the compiler scans for the targeted word in the current Search Order. If the word is already a part of the dictionary search path no operation takes place and the NEEDS word exits. If the word has not been created or loaded the library file is opened or found within the file control area, then scanned for the string given in the NEEDS command. If the library file fails to open or the word is not found, an error is generated. When the targeted word is located inside the library file Fig-Forth begins to LOAD the file from the block on which the word was found, until the loading process is complete or another error occurs. Note that in the case of compiled overlays contained in library files, all specifications relevant to the LINK process remain in effect. (See Advanced Procedures.)
Notes: The file search process used by the NEEDS operation is not counted, such that a library match can be declared on the word EDITOR if the parameter of EDIT is given the NEEDS function. (But the match won't occur in the search of the dictionary unless the word EDIT actually exists.) Also, the letter case of the word sought must match the case appearing in the file, such that lower case tags in the library may be used to hide symbols from the search if the compiler is running case insensitive mode. (CASELOCK=0) Finally, upon completion of the NEEDS operation the library file is automatically closed unless it was opened prior, as in editing the library while at the same time requesting references from it.
Fig-Forth v2 allows the creation of end user applications in a very direct fashion, using the SAVE word to make a copy of the user dictionary and system kernel at the time of operation;
SAVE MYPOG.EXE -- save current machine state in executable myprog.exe
This image will contain all data used by the programmer, including open file name and data paths, values saved in variables or arrays, and all definitions. In addition, this word will establish the cold start values of all Fig-Forth vocabularies, such that the pointers may be properly re-established upon start-up.
However, because the cold start values have been modified by the above process, any application that modifies the dictionary space below the point of the saved image must not execute the COLD operation after such modification, or an incorrect search path may result. This includes any detectable error that results in the calling of COLD such as Return Stack imbalance, Parameter Stack over or under run, or re-initialization of the package by calling the boot vector. User executables may discard, link or load additional definitions within the dictionary space at will, but executing the operations of COLD beyond initial start-up may result in an invalid search chain.
SAVE also performs an internal ONLY operation upon execution, emptying the Search Order Buffer when creating the target file. The target file will perform the same operation as the standard Fig-Forth package, an ONLY ALSO FORTH DEFINITIONS process upon start-up, yet if the programmer wishes to save the machine state and continue working, or return to the work thus far saved, they must re-establish the search order after using SAVE.
Programs created by SAVE may be made self-executable through the operation of the START word vector, which is called by Fig-Forth after the processing of COLD and before the command interpreter loop;
: MAIN .... -- the word which starts the application code
' MAIN CFA ' START ! -- set the start-up vector
SAVE MYPROG.EXE -- save the file
This process will cause a branch by the internal engine to the user routine of MAIN immediately after setting up the COLD start values, executing the desired operation as a command line sequence. Such start-up or main loop word does not have to be in the deferred or cold start search order path of Fig-Forth, as the engine will execute the token list blindly as they are fetched from user memory. Programs requiring the original search chain must perform the same operations of the creation set-up, to stabilize the state of the machine and its interface with DOS;
VOCABULARY MY-TASK IMMEDIATE -- set up user vocab
: MAIN -- the start up operation
ALSO [COMPILE] MY-TASK -- add vocabulary MY-TASK to the search order
DEFINITIONS -- make MY-TASK the compilation vocabulary
.... -- other start-up operations
The above process will add the application vocabulary to the search order just as its keyboarded or file loaded equivalent, in the event the application code requires access to the search chain for modification, command routing or other purposes. This is especially the case when using overlays or INTERPRET command strings, which require that the search order be completely intact.
In addition, if the executable contains open files at the time of the SAVE they must be re-opened, by the execution of the OPEN-FILES operation. Such an open files command does not require any parameters, for it will call upon the file control block system for the required data. However, if a file fails to open the user will be left at the Forth command prompt unless the proper error correction has been implemented, (Chapter 9) so application programs should be prepared to handle this or open all files by direct DOS access. Applications without files or bearing such direct access may close all active files before saving, resetting the file system by executing RESET-FILES.
The user application code should also make the same checks as to peripheral devices, calling MOK? for the mouse and SOUND? and so on at start-up. Note that it is not necessary to have the vocabularies for these operations in the search path upon application start-up, only that the vocabularies were present or called upon at the moment of building the application;
: MAIN MOUSE MOK? 0= IF ." NO MOUSE DETECTED!" BYE THEN
SOUND SOUND? 0= IF ." NO SOUNDCARD!" BYE THEN ....
Doing this allows the MAIN routine to call upon the operational checks required by the devices before any subsequent use, initializing the interface between Fig-Forth and the machine hardware.
Finally, the application code should expect the screen display to be in a TEXT mode at the time of execution, and ideally should check the EMJ+1024 pointer value and the VESA buffer listed in Chapter 10 for a compatible video card before making mode change calls. If the video card is incompatible the system may suffer a complete lock-up, forcing the user to re-boot the machine.
When such a saved application is run the command line parameters are echoed through the standard KEY operation, serving as the initial input from the system user;
C:\>MYPROG MY LIFE -- words "MY LIFE" will be sent as the first keyboarded input.
Secondarily, because Fig-Forth uses the standard DOS input handle, input text may come from a batch file if required by the application.
And finally, when such a user executable is preparing to shut down all peripheral interface routines should be informed, (QUIET, MCLR, etc.) the screen should be returned to a text mode and all files flushed and closed before the calling of BYE.
To leave the Fig-Forth development environment execute the root system word of BYE, after closing all files with a FLUSH RESET-FILES sequence. In the event of accidental exit caused by system lock-up or major error crash, particularly when extending files by writing to points past their previous physical end, it is recommended that MS-SCANDISK or equivalent be executed upon the target hardware to repair any missing or lost clusters on the disk drive.
Return to Contents. Next Chapter. Previous Chapter.