Binary Save - saves a block of memory to the current blocks file.

When saving Forth or assembly code, the address of the LINK field of the first word you want to save is required as the start address.

Given the following code:

: TEST ( -- ) 200 0 DO I . LOOP ;

To save the above using BSAVE, first obtain the Link Field Address (LFA) of the word, by first obtaining the Code Field Address (CFA) via the word ' (pronounced tick) and passing that to >LINK (pronounced 'to link') to get the LFA:

' TEST >LINK

At this point, the LFA (Link Field Address) of the word TEST is at the top of the stack. It is now only necessary to supply a starting block number to the stack:

10

Now, the word BSAVE can be executed:

BSAVE

Note, all of the above can be entered on a single line:

' TEST >LINK 10 BSAVE

At this point, the word TEST shall be saved to block 10 in binary format. Because the amount of data saved to disk is small, only one block is required, therefore the value left on the stack upon completion shall be 11, as 11 is the next block after block 10.

A more useful example is to take an application such as the Assembler, which starts on block 9 of the utilities disk, and save it to a different block file in binary format. When the assembler is loaded from disk using LOAD, it takes approximately 15 seconds to load and compile (on an emulated system, or a TI with a ramdisk). When loading using BLOAD it takes less than one second, because it is simply loading a pre-compiled program in the exact address it was saved from.

Assuming a freshly booted system, load the assembler from block 9 of the UTILS disk:

9 LOAD

This will load and compile the assembler. Now create a new blocks file on DSK3 called ASSM, with a capacity of 20 blocks:

20 MKBLK DSK3.ASSM

Note that MKBLK automatically sets the new file as the currently USEd blocks file.

Now, it is possible to save the already compiled assembler to the disk. First, we must ensure that we save from the very first word of the assembler program. The first word in the assembler is called R0, so we tick R0 and obtain its LFA, and use this in the BSAVE command:

' R0 >LINK 1 BSAVE

The assembler is now saved to the new blocks file in binary format.

It is essential to realise that BSAVE simply saves from the address that you give it, to the address pointed to by the word HERE. This means the memory saved to disk is the memory starting at the start address that you specify, up to and including the last definition or data compiled to memory.

Also note, when loading a BSAVEd block of memory with BLOAD, it loads the binary saved data starting at the exact same address it was saved from and will overwrite anything that was occupying the memory space prior to loading.

Usually used to save already compiled Forth code, or already assembled machine code to a disk block(s) in their compiled/assembled form. Loading a Binary Saved program from disk blocks is much faster than loading source code because the compilation step is missed - it was already performed prior to using BSAVE.

Saves CPU memory from start to HERE to the block beginning at block and continuing for as many blocks as are required to hold the contents of memory. Upon completion, the stack contains the next block number (nb) (i.e. the last block used by BSAVE+1). For example, if you save an area of memory starting at block 10, and three blocks are required, then BSAVE shall write the data to blocks 10, 11, and 12, and the value 13 shall be placed on the stack upon completion of the command.

BSAVEd blocks have the following format: