RAM File Handling
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.
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."
Key Rules 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."