RAM File Handling

Origin

This information comes from the NEC 8201A technical reference. The original is in broken english, and has some photocopy issues. I will fix what I can.

Overview

In this chapter, the techniques for managing RAM files is described. The main purpose is to create or delete a RAM file for RAM and Option ROM resident applications. If there is a violation of the rules of RAM file handling, the file you made, and possibly all files in the RAM may be lost upon entry to standard file management routines in the main ROM.

There are many useful routines the programmer may leverage to avoid breaking the file management rules. Unfortunately, heavily leveraging file management routines from the main ROM by a program operating from an Option ROM will incur a performance penalty. If you want to manipulate the RAM filesystem without the Main ROM, please make sure to follow the rules laid out in this chapter. Also refer to the sections on "Bookkeeping" and "Directory Structure."

Checklist for RAM File Handling

Make sure that there is enough free space

When a new file is opened, or new data is appended and inserted, investigate whether there are enough free bytes available. In particular, the free area required simply to create an empty file is sometimes overlooked. At least one byte is required to create a DO file. Six bytes are required for a CO files. Refer to "What is a RAM File" and the following sections.

You can find where the free space is in the figure "Bookkeeping Area." The difference between the pointer "STREND" and the value in the stack pointer indicates the free size. But don't forget that some area will be used for the stack operation in that free area. For instance, the make-room routine used in BASIC and TEXT recognizes that the current free space is less 120 bytes than that difference. In other words, 120 bytes is always maintained for the stack area when new data is stored. Refer to "MAKHOL" in "Useful Routines for RAM File Handling In the Main ROM."

Register the file name correctly

The contents of the directory is described in "Directory construction." Everyone seems to remember to register the filename in it. But often programmers will forget to set up the directory flag byte and the starting address of the file. If you don't set the directory flag, the file might be deleted by Menu or another operation. If you write a bad starting address in the address field, the implied (by pointer order) link between the directory entries and the corresponding files will be lost. The result of breaking that implied link is that the user cannot select a file in Menu mode, or the laptop hangs or crashes. Refer to "Directory Construction" and the following sections to avoid this outcome.

Maintain the order of the files

In order to maintain the order of the files, the starting address of the new file must be selected carefully. For a new DO file, we have to set ASCTAB - 1 as the starting address of that new file in the directory area. And for a new BA file, you have to register the ASCTAB - 1 in the "non-registered" file's directory area and insert double NUL there. That new BA file will be created at ASCTAB - 1 and will have the starting address, ASCTAB - 2. In making both a new DO file and a new BA file, LNKFIL should be executed before end of its process. Refer to "Useful Routines for RAM File Handling in the Main ROM" to understand the role and usage of LNKFIL.

Make and shrink a hole safely

The calculation of the free space is very important. And you have to maintain the stack area when you make room. One more important issue in the management of the pointers: The reason why many programs, Menu, BASIC, TEXT and so on can use the same RAM area safely is that they adjust the pointers for RAM every time they change the RAM configuration. For example, when BASIC deletes a BASIC program file, it changes many pointers: STREND, ARYTAB, VARTAB, BINTAB and ASCTAB. And, it turns off the "in-use" flag and the end of the operation to free the entry. Refer to MAKHOL and MASDEL in "Useful Routines for RAM File Handling in the Main ROM."

Insert the mandatory bytes in the file

When you open a DO file, you have to enter one byte of data at least. The data is Control-Z ($1A). This character marks the end of the file. A BA file must have a proper "next line" link structure, and have two NUL bytes at the end of the file. A CO file must at least have a 3 word (6 byte) header. Refer to "What is a RAM File" for more details.

Fix up starting addresses in the directory

When you change the RAM configuration, you have to care not only for the section pointers, but also the starting address for each file in the directory. Given the order of the sections, if you add a DO file, directory entries for all files above it, including DO, BA, and CO must have their start pointer corrected. Refer to "LNKFIL" in the "Useful Routines for RAM File Handling in the Main ROM."

Do not embed forbidden characters in DO files

Never store $00, or $08 characters in a DO file. Never store a $1A (Control-Z) character in a DO file except as the end of a file marker. Refer to the section "DO File"

How to make a new file

How to register a new file name

When creating a new file, the first thing you should do is register the file in the user's directory area. The user's directory area starts at USRDIR. Last byte of the directory area is a $FF byte, called the "Directory Terminator."

An in-use slot has a type byte greater than or equal to $80, that is, the high bit set. This makes it easy to identify a free slot. Refer to the sample program shown later.

It is important to ensure a file you wish to create does not already exist. Two files with the same name can cause serious problems. So, check for collisions, and offer the user the choice of deleting the old file or aborting the operation.

If you find a free slot, register a proper flags byte, a start address, and the filename. Refer to "Directory Construction."

How to make a DO file

If you have already registered the filename and directory flag at the slot in the directory area, the remaining information to store is the start address of the DO file. If you didn't read "How To Register A New File Name" and you have not set the filename and directory flag yet, read that section and fill those in first.

Usually the DO file is created just above the value of ASCTAB. ASCTAB holds a pointer to the start of the DO file section. Refer to the figure in "What is a RAM file." If you go with the standard rule which Menu, BASIC and others in the Main ROM use, you can store the result of [ASCTAB] - 1 as the starting address of the new file. Then the registration of the new DO file is completed. The reason why we have to use ASCTAB - 1 instead of ASCTAB is to maintain the order of the files.

The LNKFIL routine corrects the directory start pointers after changes to the RAM filesystem. It does this by walking all files in memory, pairing each subsequent file with the unprocessed entry in the directory having the lowest start pointer. If the temporary start address you choose for your new DO file is identical to an existing entry, the assignment of directory entry to file is ambiguous. If you just used [ASCTAB] as the address instead of [ASCTAB] - 1, that is exactly what would happen. Refer to "LNKFIL" in "Useful routine for RAM file handling in the Main ROM."

But there are still two more steps. First, you must insert the eof-of-file byte ($1A). The other is, you must make room for the data to be placed in the file (and correct the directory afterward).

There is no DO file whose size is zero, since every DO file must have a $1A terminator.

In order to make room for the new file, a convenient routine is in the Main ROM. Its name is MAKHOL, MAKe HOLe. This routine inserts spaces from the specified point and whose size is contains in the BC register. Refer to "MAKHOL" in "Useful routines for RAM file handling in the Main ROM." The concept of the MAKHOL operation is shown briefly in that section.

If there is no free area in RAM, and you cannot insert a $1A, you must clear the directory entry "in-use" flag.

Finally, to fixup the starting address in the directory area, the LNKFIL routine is available in the Main ROM. The flow diagram of that routine is shown in the "Useful routines for RAM file handling in the Main ROM." You can get information there to write your own LNKFIL routine as well.

If you succeed in inserting the $1A, and in setting a starting address, you can now save data to the new file using MAKHOL, and correct the directory table using LNKFIL. Refer to another section to determine how to Append, Insert, and Delete data. The sample program in the following section will show you how to make a new file and save data.

Summary:

1. Find a free slot in the directory. Give up if there are no free slots, or the file exists and it is not OK to delete it.
2. Register the filename and directory flag in the free slot.
3. Get [ASCTAB] - 1 and save it in the address field of the slot.
4. Make a one-byte hole at [ASCTAB]; free the directory entry and abort if cannot make a one-byte hole.
5. Set $1A in the one-byte hole.
6. Fixup the directory entry starting addresses using LNKFIL
7. Done.

How to make a BA file

There is a difference between how to make DO file and how to make a BASIC file. There is no differnce in the registration of the filename and the directory flag. The first difference is that you have to end the BASIC file with two NUL (0) characters instead of Control-Z in DO files. In order to understand what double NUL means, you have to be familiar with the function of the link pointer in Microsoft BASIC. But the basic concept of RAM file handling is exactly the same as for a DO file. That is, you register the file in the directory and make room for the file data.

The second difference is the new BA file is created just above the BA files which are already stored. In other words, the new BA ifle is inserted just below the lowest DO file. Refer to the section, "What is a RAM file?"

I will assume that if you are looking to create BASIC files in memory, that you already know how to build a tokenized BASIC program in RAM. The details of that are out of scope for this article.

How to create a new BA file:

1. Lookup the filename in the directory table. If found, delete the file or abort the operation.
2. Allocate a slot in the directory table. If no free slots exist, abort the operation. Otherwise, setup the directory flag and copy in the filename.
3. Copy ASCTAB -1 into NULDIR, the unsaved BASIC program's directory slot. Make a 2-byte hole and store the double NUL into the unsaved BASIC program.
4. Make a hole as large as possible at ASCTAB - 1.
5. If the size of the hole is too small for the new BA file, delete the hole, free the directory entry, and abort the operation.
6. Copy the BASIC program into the hole. Don't forget to ensure double NULs at the end of the program.
7. Fill in the start pointer into the directory entry. Normally, the address used is one byte less than the starting of address of the unsaved BASIC program.
8. Reduce the size of the hole to the minimum size possible if you overshot the size.
9. Adjust the section pointers ASCTAB, BINTAB, VARTAB, ARYTAB, and STREND. Fixup the starting addresses of all files in the directory. Refer to LNKFIL.
10. Done.