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 is 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.