12 Block IO

TurboForth supports disk blocks for storing program code and data (or indeed, anything you wish to store) on disk. Blocks are fully described in the sections below.

12.1 What are blocks?

Blocks are simply 1024 byte 'blocks' that can hold any kind of data. Programs, program data, your shopping list, anything. TurboForth contains a built-in block editor that can be used to edit blocks. On screen, a block is 16 lines of 64 horizontal characters. However, Forth itself sees a block as one 1024 character long 'single line'.

It is possible to load a block, by simply typing a block number and then the word LOAD. LOAD causes a block to be loaded into memory from disk, and then interpreted or compiled just as if the blocks' contents were actually typed in via the keyboard. Using this method, it is possible to store Forth programs in source code form. It is not required (though it is possible) to store them in pre-compiled binary form, as we do on other systems or operating systems (e.g. exe files etc).

A program can also write data into blocks at run-time, thus using them to store run-time generated data, such as names and addresses, high-scores, graphics data etc.

Above: The built-in block editor, shown here in 80 column mode (Classic99, TI994W, MESS, and 4A consoles with a 9938 or F18A VDP)

12.2 The Block Buffer System

The block system in TurboForth uses buffers to hold the blocks coming in from/going to disk. Working very much like a disk cache, when a block is requested, the in-memory buffers (cache) are first searched to see if the requested block is already in memory. If not, the block is brought in from disk into one of the buffers, and the address of the buffer is returned, allowing the programmer or the Forth system itself direct access to the contents of the buffer.

If a block's contents is changed, it is possible to mark it as 'dirty'. A dirty block will eventually be flushed from the cache back to the appropriate place on the disk. This happens when the buffer space is needed for another block. For example, changing the contents of a block using the editor causes it to be marked as dirty, so that it will be later flushed back to disk.

When working with floppy disk based systems, this can be a very useful time saver; pertinent blocks can be brought into memory and worked on much faster (at normal memory access speeds, rather than floppy disk I/O speeds) and flushed back to disk when no longer needed.

12.3 Creating Blocks Files For Your Own Use

TurboForth stores its files on disk/hard disk/CF7 etc in DF128 files (that is, display format, with each fixed record being 128 bytes in length). You must create a file and size it according to your needs before you can store anything in the block file. TurboForth has a utility built into it that can do this for you, called MKBLK.

Example:

TurboForth up to V1.1	TurboForth Version 1.2
MKBLK DSK1.MYBLOCKS 40	40 MKBLK DSK1.MYBLOCKS

The above creates a blocks file on DSK1 called MYBLOCKS of 40K in size - enough for exactly 40 Forth disk blocks.

Having created a blocks file, you need to tell TurboForth to USE it, for example:

    S" DSK1.MYBLOCKS" USE

The above tells TurboForth that all future block related disk I/O shall be to/from DSK1.MYBLOCKS. Note the space after the " in S" - it is important!

Note that when USE is executed, any blocks currently in memory are expunged. They are NOT flushed. Therefore, if you have any edited blocks in memory, you must FLUSH them yourself, prior to changing blocks files with USE.

12.3.1 Auto Booting

Note: When TurboForth starts, its default action is look on DSK1 for a file called BLOCKS. If it finds it, it will load block 1 and execute/obey whatever it finds in there. If no such file is found, TurboForth will simply drop out to the command line (flashing cursor). Thus you can make your own auto-load disk (which perhaps customises the Forth environment to your individual needs/preferences and loads some additional useful words or libraries) very easily.

12.3.2 Overriding Auto Boot Behaviour

The automatic loading of disks can be bypassed by simply holding down the ENTER key as TurboForth starts up (after selecting TurboForth from the startup screen, quickly press and hold the ENTER key). TurboForth will simply drop out to the command line and not attempt to boot from any device.

Alternatively, pressing and holding any other key will attempt to boot from DSKx.BLOCKS where x is the key that you are holding down. For example, if you have a RAM disk configured as DSK9 then holding down 9 as TurboForth starts will cause it to look on DSK9 for the blocks file, and load it if it finds it.

12.4 Editing Blocks and Code with the Built-in Editor

To edit a block using the editor, simply type the block number you wish to edit, and then the word EDIT. You must already be USEing a block file (see section 12.3, above).

For example:

1 EDIT

This will invoke the built-in (in ROM) editor, and your block (block 1) will be displayed. Let's try it from the beginning. We'll create a blocks file for testing purposes, and edit some code:

First, reset the system with COLD and hold the ENTER key down to defeat auto-booting. When you see the cursor, make sure you have a new floppy disk in DSK1 and type the following:

TurboForth up to V1.1	TurboForth Version 1.2
MKBLK DSK1.MYBLOCKS 40	40 MKBLK DSK1.MYBLOCKS

You'll see some activity on DSK1 as the file is created. Next, type:

S" DSK1.MYBLOCKS" USE

From this point on, all disk-block-related activity is directed to the file MYBLOCKS on DSK1.

Now, type 1 EDIT - the editor will load, and you'll see disk activity as the block is fetched in from the disk.

Your screen will look like this:

40 Column Video Mode	80 Column Video Mode (F18A or V9938/58 equipped systems only)

The editor is a 64 column editor. If you are running a standard TI-99/4A then the system can only display 40 columns horizontally. In this case, the editor uses a windowing technique to display the 64 columns. As the cursor moves across to the right, you will notice the editor moves across to display the latter part of 64-columns. When you move left, the editor moves back again:

If you are using an 80 column system then you can run the editor in 80 column mode, and the windowing system is not necessary. To enable 80 column mode, just ensure that TurboForth is running in 80 column mode (exit the editor using FCTN = and then type 2 GMODE).

Now, let's enter some code into the block. Type the following on the top line:

: TEST 100 0 DO I . LOOP ;

You can use the cursor keys (FCTN with E, S, D or X) to move the cursor around. Also you can use insert mode or overwrite mode (press FCTN 2).

When you have entered the code above into the editor, exit the editor by pressing FCTN 9.

We have exited the editor, but notice that the block was not saved back to disk. It is currently sitting in the memory of the computer. Let's try editing the block again. Type 1 EDIT and press ENTER. You are taken back into the editor, and there is the code that you wrote. But notice that there was no disk activity.

Let's now force the system to save the block back to disk. Simply type FLUSH and press enter. You will see disk activity as the block is flushed onto the floppy drive. When the block buffers are flushed to disk they are effectively emptied (the system forgets what is stored in them). So, if you now type 1 EDIT, you will notice that the system actually loads it from disk.

So how do we execute the code that we have put in the block? Well, before it can be executed, it must be LOADed with the LOAD command. Simply type 1 LOAD and the block will be "loaded" from the block and compiled. If the block is already in a buffer then you will not see any disk activity. If it is not in a buffer then the system will put it in from disk into a block buffer and then compile it from there.

Now your code is compiled and ready. Simply type TEST and press enter, and voila!

Note that in most Forth systems, TurboForth included, code is generally saved in source code form, directly in the editor. In most languages we are used to compiling our code, and we get back some of file; maybe an executable file (.EXE) or some other sort of file (.JAR etc). This is not the case in Forth. In Forth, code is stored in source code form. It's not necessary (though it is possible) to store code in compiled form - the code is simply compiled at load time.

12.5 Using Blocks to Store Data

Just as we use blocks to store source code, we can use them to store data. You don't have to restrict the contents of blocks to source code. For example, you might have a Pacman game where each level (the maze) is stored in a block file, and your code can simply load it in at run-time (using the word BLOCK) and display it directly, or you might have raw-binary data in a block that you load and interpret yourself in your own code.

Blocks can be thought of as a kind of virtual memory. Each block is exactly 1K in size. By loading one, or a few blocks into memory at a time, it is possible to acutally work on data-sets that are much larger than the physical memory size (or available memory size) of the computer.

Let's take a look at a program that will:

Load a block from memory
Using that block, fill it with random data
Set the status of the block to dirty
Flush it to disk

We'll then use the editor to verify that the program worked.

Here's the program:

S" DSK1.MYBLOCKS" USE : make-data ( -- ) 2 BLOCK \ ( -- addr ) get block two in from disk 1024 0 DO \ loop 1024 times 256 RND OVER I + V! \ write a random number into a byte in the buffer LOOP DROP \ now we'll force the buffer's status to 'dirty' 2 BUF? \ ( -- buffer vdp_address ) DROP \ drop vdp address, we don't need it DIRTY \ force the buffer's status to dirty FLUSH \ now FLUSH will see it and flush it to disk ;

Now, execute the above program (by typing MAKE-DATA). You'll see some disk activity as the block is read from disk, then the block (in memory) is filled with random numbers, then the block is written back to disk.

We can verify this with the editor. First, type 1 EDIT and check that the code you entered in section 12.4 is still there. Now, press CTRL and P to move to block 2. You'll see it is full of random gibberish that was put there by our program. Now press CTRL P again to move to block 3. Note that it is empty.

12.6 Saving Pre-compiled Code into Blocks with BSAVE

TO DO :-)

12.7 Block Related Words

A list, with descriptions, of all disk block I/O related words is available from the on-line language reference database. The Block I/O section is here.