Reclaim.bns 1.7 User Documentation

January, 2000

Introduction

	Reclaim is a program for changing unusable, deleted file storage space in the flash memory of a Blazie Engineering note-taker back into useable memory. When Reclaim is run, the program scans flash memory for "dirty" areas and "reclaims them" so they are again useable. 

How It Works

	To understand what Reclaim does, one must first understand how flash memory is setup. In this example, the two megabyte memory of a BNS or BLT 2000 will be used. A simple analogy will help us explain the concept of Reclaim.   One can think of the memory like a large, 32 story hotel. All 32 floors of the hotel are identical, and each floor has 128 identical rooms. When a file is stored in flash, it takes up one or more of the rooms. The bigger the file, the more rooms in the hotel it requires. 

Now the management of the hotel is very particular about how the files are stored. If a file needs 15 rooms, the management will put it in the first set of 15 clean rooms that it can find that are all next to each other. So, if the hotel has 7 clean rooms on the third floor and 8 more clean rooms on the fifth floor, it won't use these rooms. It will look for 15 clean rooms all together. If it cannot find 15 clean rooms all together, then it does not let the file stay in the hotel! This is why it is possible to have 200 k free space in flash memory, but still get a "flash error 5, not enough room" message when trying to move a 50 k file to flash. There is 50 k available, but not all together in one continuous block. When a file is deleted from flash memory, it leaves the hotel, and of course, this creates dirty rooms. 

The housekeeping staff is also very particular about when it works cleaning rooms. Housekeeping only cleans an entire floor at a time. It waits until all 128 rooms on a floor have been used and vacated before it cleans any rooms on the floor. And when it does clean them, it cleans all 128 rooms at once. This can cause problems. As an example, imagine a floor with 4 files. File one uses 60 rooms. File 2 uses 30 rooms. File three uses 20 rooms, and file four uses 18 rooms. If files one, two and three are deleted, the floor will have 110 dirty rooms and 18 occupied rooms. However, none of the rooms will be cleaned until file four is also deleted, thus making all 128 rooms dirty.
Until this occurs, the 110 dirty rooms sit unoccupied. New files are not placed in dirty rooms.

So reclaim is a program that makes previously used flash space available once again.  It does this by moving files around squeezing them together to create larger blocks of free space for new files.  Each block holds 1/2 k, or 512 bytes.)

How Reclaim Helps

When Reclaim is run, it scans each floor of the hotel looking for dirty rooms. If it finds even one dirty room on a floor, it cleans it so it can be used again. How does it do this? First, Reclaim moves the files in the occupied rooms on the floor to the RAM memory hotel--a completely different  hotel). Next, with the floor now completely empty, the housekeeping staff is called to clean the entire floor. Finally, the files which had been temporarily move to the RAM hotel are moved back into their same rooms. Reclaim continues this process until all 32 floors of the flash memory hotel have been scanned. 

Reclaim actually does quite a number of other "housekeeping" tasks when run. It checks the system for errors, cleans up the flash table of contents, and does a general check to make sure all is in order.

Reclaim is not Defrag 

Although use of Reclaim will greatly enhance the usefulness of flash memory in Blazie Engineering note-takers, it is not a defrag program. Reclaim simply cleans the dirty rooms of the hotel so they can be used again. However, even if all the dirty rooms in the hotel get cleaned, another potential problem exists. Recall in the above example that the hotel management will only let a file stay in the hotel if it has enough rooms all together for the file. If a file requires 15 clean rooms, and there are seven clean on the third floor and eight more clean on the fifth floor, the file cannot use these rooms. The 15 rooms must be together side by side. Defrag is the process of taking all the occupied rooms and all the clean rooms and separating them into two areas. When defrag is done, all the occupied rooms will be together on the lowest floors of the hotel and all the unoccupied, clean rooms will be together in one large block at the top of the hotel. Blazie Engineering expects to release a defrag program in the near future.

System Requirements

Reclaim will run on any Blazie Engineering note-taker that contains super flash memory and has a November 1999 or later revision installed. A bug in the firmware prior to November 1999 prevents Reclaim from running safely in earlier revisions of  Blazie Engineering firmware. 

Additionally, Reclaim requires 24 free pages of RAM memory to load and run successfully. The program itself only takes seven RAM pages, but it uses 17 additional pages when running. When running Reclaim from Ram, make sure 17 free RAM pages are available. When running Reclaim from flash, make sure 24 RAM pages are free.

Reclaim does not store any user settings, so it may be run from flash as a "quick load" program. Programs, by default are all set to "quick load," so one need do nothing to make Reclaim run as "quick Load."

Running Reclaim

Like all external programs for Blazie Engineering note-takers, Reclaim must be loaded into either RAM or flash memory from disk. This may be the Blazie Engineering Disk Drive Accessory, or a drive on a PC. For detailed instructions on loading a program from disk, consult Appendix A at the end of this documentation. 

	Reclaim may safely run from either RAM or flash memory. For a detailed description of how to run an external program, consult Appendix B at the end of this document. When reclaim is run, it first speaks the message, "Reclaim flash version 1.7." It then pauses momentarily to scan the flash memory. After the pause it gives the message, "xx k flash can be reclaimed. Continue? Y or N." Simply answer y to continue or n to abort the program. All other keystrokes are ignored and the prompt is repeated. Incidentally, flash files can be as small as 1/2 k, so it will be common for a message like, "32 and a half k can be reclaimed."

If yes is typed, the program gives the message, "Warning, do not power off before program completes," and then begins to reclaim deleted space. It will click periodically to alert the user that reclaim is in progress. The actual reclaim operation can take anywhere from a few seconds to half a minute or longer. When done, Reclaim reports, "No flash can be reclaimed." 

Reclaim can finish in one of two ways. If the flash table of contents was rewritten during the reclaim, the system must be restarted. If this is necessary, Reclaim will report, "Restarting system," and then the note-taker will restart just if it had been turned off and back on. If no rewriting of the flash table of contents was needed during the reclaim, Reclaim reports, "System restart is not required," and then ends.

Additional Uses and Options for Reclaim

The job Reclaim performs is very straightforward and requires little to no documentation for the user interface. There is one additional use for Reclaim which may be useful for some users. Reclaim can be used to initialize and completely erase flash memory. If it is necessary to initialize flash and completely erase all files in flash, Reclaim can be run with the letter I option on the command line to accomplish this. The advantage of this method is that it precludes the need to perform  a cold, or hard, reset on the unit and thus, reset all user settings. Because this option will completely and utterly erase all files in flash memory, it must be used with caution. Reclaim warns the user very clearly that this will be the result. To access this option, run Reclaim from the command line or use the x command from the files menu. If running from the command line, then at the prompt, "Enter program to execute:" type the line
Reclaim I
And press enter or e-chord. Reclaim will sign on and then ask for a confirmation. 

	The only other Reclaim option is one to skip the confirmation question when a normal reclaim session is executed. Thus, if you do not want to be asked, "xx k can be reclaimed. Continue? Y or N," then use the command line option y. If at the command line prompt to, "Enter program to execute:" you type
Reclaim y
Then Reclaim will not pause to ask this question. This may be helpful if running Reclaim in a macro.

Please send all technical questions regarding the use of this product to the address
Support@blazie.com.
Or contact Blazie Engineering Technical Support with the following contact information.
Blazie Engineering
105 E. Jarrettsville Rd.
Baltimore, MD 21050
Voice (410) 893-9333
Fax (410) 836-5040

Appendix A 
Loading Reclaim From Disk


Blazie note-takers may run two different types of programs, internal and external. Programs, or features as they are more commonly called, which are always available and cannot be removed from the note-taker are internal programs. All Blazie note-takers include the same internal programs--scientific calculator, word processor, stopwatch, etc. External programs, on the other hand, are optional. They do not exist in the note-taker as a program until they are added by the user. Additionally, once in the note-taker, they may be deleted at any time. External programs reside in the user memory and appear as files with an extension of .bns. Reclaim is an external program. One must first load it into user memory before using it. External programs are stored on disk, and so one must have access to a disk drive to load them into a note-taker. A Blazie Engineering disk drive accessory may be used, or alternatively, the disk drive on a PC also works.


Loading from a Blazie Disk Drive or PC Disk

Follow these steps to load Reclaim into a Blazie note-taker from either the disk drive accessory or from a PC running PC Disk.

1. With the disk drive and note-taker turned on and cabled together, type s-chord from any open file. Unit responds, "storage." Type either F8 or Alt + s on a TNS to issue this command.
2. Type the letter y. Unit responds, "enter s to send or r to receive."
3. Type the letter r. Unit responds, "enter filename."
4. Type reclaim.bns followed by e-chord, or enter on a TNS. Use computer braille notation for the period by typing dots 46. After about two seconds, the note-taker will repeat the name of the file and several seconds after that the drive will beep and the note-taker will reply either "ok" or "transfer complete." 
5. Ensure the files loaded correctly by entering the file menu. Locate the file Reclaim.bns and check to make sure it has a file size of greater than one page. 
6. If the file is there but is only one page long, delete Reclaim.bns . Then delete or move enough files out of RAM memory so that at least seven free pages are available in RAM memory. The number of free RAM pages available is given by pressing the letter f from the files menu.
7. Reclaim may also be loaded into flash memory if desired. Finally, repeat steps one through six again, but instead of loading Reclaim.bns, load reclaim.txt. This is the program documentation file.


Loading the Program from a PC

The following steps are intended for persons already generally familiar with the process of using a telecommunications program on the PC. They may be followed to load the program into a Blazie Engineering notetaker. Using Windows 95 or 98, HyperTerminal works well. Under DOS, one may use Telex, Commo, Pro Comm or any of a variety of other DOS-based terminal programs.

1. On the PC, start the telecommunications program. 
2. Ensure the serial port parameters in the program match those of the note-taker and connect the note-taker to the PC with the supplied serial cable. Use the supplied adapters if necessary to match the cable to fit the appropriate gender and size of the PC serial port. 
3. Issue the command in the telecommunications program to begin a file send, also known as an upload.
4. When prompted to select a sending protocol, choose y-modem. This is different than y-modem g. 
5. Place the Reclaim program disk in floppy drive a.
6. When prompted to select files to send or upload, type a:*.*, but do not press enter yet to begin the transfer. If Reclaim resides elsewhere on the PC, specify the appropriate drive and folder here instead of A:. 
7. On the note-taker, from any file, enter the files menu with o-chord followed by the letter f. The unit responds, "enter file command." Type F1 on the TNS to issue this command.
8. Type t-chord. The unit responds, "enter s to send or r to receive." Type either the print screen key or Alt + t on the TNS to issue this command.
9. Type the letter r. Unit responds, "enter x for x modem, y for y modem or g for y modem g."
10. Type the letter y, the unit responds, "start the transfer."
11. On the PC, begin the transfer by pressing enter. The note-taker should respond shortly by stating the names of the files as they are sent from the PC. When all files have been received, the note-taker will respond, "ok."



Appendix B
Running an External Program

	An external program must be executed before it can be used. Two methods exist for starting an external program. The first method utilizes the options menu as follows.

1. From any file in the note-taker, type o-chord. Unit responds, "option." Type either the F9 key or Alt + o on the TNS to issue this command.
2.  type the letter x. Unit responds, "enter program to execute."
3. Type the program name reclaim followed by e-chord, or enter on the TNS. Unit responds by pausing for a moment then issuing the sign on message for the Reclaim program.

	If the program cannot load successfully, one of three error messages will occur. Receiving either "file is not a program" or "program is corrupted, please reload from disk" means the file is no longer in its original condition and must be deleted from the unit and reloaded from disk. 

	Receiving the message "not enough room" occurs when the program is stored in flash memory and not enough RAM memory is available to hold a copy of the program when running. Resolve this problem by deleting or moving files from RAM to free up at least 24 free RAM pages. Then run the program again from the options menu.


External programs may also be started while in the files menu. To do so, do the following.

1. From any file, enter the files menu by typing o-chord, then f. Unit responds, "enter file command." Type F1 on a TNS to issue this command.
2. Locate the file Reclaim.bns in the files menu.
3. Type x-chord. Unit responds by pausing for a moment then issuing the sign on message for the Reclaim program.

	If the program cannot load successfully, one of three error messages will occur. Receiving either "file is not a program" or "program is corrupted, please reload from disk" means the file is no longer in its original condition and must be deleted from the unit and reloaded from disk. 

	Receiving the message "not enough room" occurs when the program is stored in flash memory and not enough RAM memory is available to hold a copy of the program when running. Resolve this problem by deleting or moving files from RAM to free up at least 14 free RAM pages. Then run the program again from the files menu.


 


