Editing the TCS Forth system

June 18, 1999

Jim Harwood

 

The Forth file system uses named files with a dot and extension organized in a directory, but other than that, there is nothing remotely like DOS or UNIX.

Do not attempt to apply DOS conventions or standards to any operation with Forth.

Forth has both line and screen editors. You can do everything you need to do with the screen editor. You deal with blocks of text, 64 characters by 16 lines. A file consists of a number of these blocks, and you edit the source code block by block. A file starts with Block 1. Most files are a dozen blocks or less. Most everything is upper case. Do not mix up cases. Forth is case sensitive.

The basic Forth operating system is not part of the directory. The source code is in absolute block numbers. The only practical difference is that you call up the editor with a different command for editing absolute numbered blocks (0-999).

You have to switch to the UTILS vocabulary to do editing. If you need to go back to what you were doing rather than going right into compiling, type PROG to access the TCS commands.

Editing is done with the text in memory. You have to type FLUSH to get it back on the medium.

 

How to Edit

Type UTILS unless you already are in the UTILS vocabulary.

Editing TCS source files

The directory and all the named files are on Disk 1. You edit block numbers relative to the start of the file.

  1. Do you want to see the directory? .FILES will display in alphabetical order the files and the absolute block number of their starting block (rarely needed). Include the leading dot in the command.
  2. To start editing a text block, type F-EDIT [filename] for example:
    F-EDIT CORR.TCS
    You get the message, ENTER HEADING!
  3. For the first time in a session, you need to enter today's date that will be placed in the date field of the block header line. You don't have to do this for every edit. Type-
    HEADING 22 JUL 1999
    Try to keep a fixed format. For example, for a single digit day number, type-
    HEADING 3 AUG 1999 (Two spaces after HEADING, not one.)
    Note that months are always three characters and years are 4 digits. After the heading is entered, the header line will be displayed. If there is something wrong, repeat the entry.
  4. Continue to Step 5 below.

    5. Editing Forth system blocks

    The system blocks are on Drive 0, from 18 to the end of the disk, Block 499. The major part of the Forth system source is up to B. 109, with some special purpose blocks higher up.

    Type SYS-EDIT

    The message, ENTER HEADING does not appear here as it does with file editing, so you have to remember to enter the heading the first time. A blank heading contains non-printable characters which will stall the load at compile time, so make sure there is a heading before doing any editing. See step 3 above.

  5. Bring up the block you want to edit. Type the block number (relative or absolute) and the following 2-character command:
    6 #N
    (    A shortcut for displaying the first block of the file is B).
  6. The block will be displayed. What you do next depends on what terminal or terminal emulation you are working at. For Wyse terminals, type SCREEN . For VT-102, ANSI, and Xterm terminals, type XTERM . The block will be displayed in screen mode, with intelligent cursor control. The word "Overlay" off to the right of the displayed block reminds you of the mode. Type <CTRL>-I to go into insert mode, <CTRL>-O for overlay. Use insert mode sparingly, as it is clumsy.
  7. Move the cursor around with the arrow keys. <CR> does not go in as text but drops the cursor down a line. The <TAB> key jumps the cursor over text words, convenient for quickly getting to the right side of the line. Only alphanumeric characters go into the block as text data. Control sequences and arrow keys are interpreted as cursor control.

<ESC> quits the screen editor, putting you back at the Forth command line, still in UTILS so you can do another editing operation. Type FLUSH to flush the changed block to the diskette.

IMPORTANT: Look at the block you just edited by typing L . Is the header OK? If the header contains a series of dashes it contains non-printing characters (nulls), which means a HEADING wasn't done and it won't compile. See step 3 above to enter a heading. Now edit the block again, and make some trivial change such as re-typing a space character, which causes the new heading to be used.

If you want to get back to the application vocabulary, type PROG .

 

Additional pointers:

  1. If compiling halts before a complete load is done, there is probably a bad header line in a recently edited block. Go back to what you just edited and redo the HEADING operation.
  2. During the Forth system load as started with the BOOT command during compiling, a beep occurs for every modulo ten block, starting with Block 30. The beep is from the BELL command toward the beginning of the block. If compiling stops because of some error, you can narrow down the location of the problem by counting beeps, which gets you within the right decade of block numbers. The most likely cause of an error is an editing mistake.
  3. Typing .RW shows the absolute numbers of the blocks currently in the memory block buffer. The block number 32767 means a free block buffer. A negative block number means a dirty block, which will overlay the block on diskette when FLUSH is typed. Type ERASE-CORE to zero out all the memory block buffers and forestall writing dirty blocks.
  4. When a Forth system error occurs, the last used block number is saved on the stack. To display this block number, type the period key, which is the command to print the top of the stack. The resulting number is probably the last used block number, depending on what was happening at the time. Printing the top of the stack will produce a "Stack Empty" message along with the number. This is harmless. If a failure occurred while compiling, the block number being compiled is probably the one that will be displayed.