CACHEnnn, by Ken Badertscher
Copyright 1989, Atari Corp.

A program to add cache buffers to Rainbow TOS, and make your hard disk
scream...

Why cache?
==========
The advantage of having cache memory available for Rainbow TOS is that
it means that the OS doesn't have to look on the disk every time it
needs to know where to go to find a file or a bit of data.  It keeps as
much information as it can in the cache memory you give it, so that
frequently used directories and data can be quickly accessed.  Some
caches use a method called "deferred writes" to keep even more stuff
around in memory, but TOS does not do that.  The TOS cache is a "write
through" cache, which means that there is never anything in the cache
which isn't also on the disk.  Thus, CACHEnnn is both fast and safe.
How fast?  CACHEnnn can increase the performance (read: decrease file
access time) by as much as TEN TIMES what it would be without the cache.

Running CACHEnnn
================
You can use CACHEnnn in several ways.  The easiest is to change its name
and put it in your auto folder (or run it from the desktop).  It works
like FOLDR100, in that its filename determines how much cache you get. 
Technically, there are two kinds of cache buffers - one kind holds File
Allocation Tables and root directories (we'll call these "F buffers")
and the other kind holds data and subdirectories ("D buffers").  When
you rename CACHEnnn, you tell it how many of each kind of buffer you
want.  For example, if you rename CACHE.TTP to CACHE90.PRG, it will add
90 F buffers and 90 D buffers that TOS can use as a cache after it runs.

Command line usage
==================
CACHEnnn can also be used from a command line (after all, it is called
CACHE.TTP if you don't rename it...).  If you use a command line shell,
and type CACHE -H, you will see a message similar to the following:

Usage:	cache [D]nnn [Fnnn] (nnn = 1 to 999)
	D=Data/Dir buffers
	F=FAT/Root Dir buffers
	no letter=nnn of each
`cache d10 F 20' adds 10 D, 20 F buffers.

Or, rename to CACHEnnn.PRG and run (equivalent to `cache nnn').
CACHEnnn Copyright 1989, Atari Corp.

What all that means is that you have three ways of specifying on the
command line what kind and how many cache buffers you want to add.  If
you just give it a three digit numerical argument, it will add that
many F _and_ D buffers.  This is the same as renaming it to
CACHEnnn.PRG and running it from the desktop or auto folder. 
Alternatively, you can specify how many F buffers and how many D
buffers you want, by using the Fnnn and Dnnn arguments.  The letter
part of these arguments can be in upper or lower case, and may be
separated from the digits by spaces.  Any digits past the third are
ignored, so if you say CACHE F1234, you'll only get 123 F buffers
added.

How many buffers?
=================
I personally find it easiest to just put CACHEnnn in my auto folder,
but performance nuts might want to tweak just the right buffer numbers
for their setups.  90 each of F and D buffers seems to be a good number
for a 20 megabyte hard disk (CACHE90.PRG in the auto folder).  You may
want more if you have more storage.  Also, depending on how you set up
your directory structure, you may want more F or D buffers.  Generally,
if you have a lot of deeply nested subdirectories, you'll want more D
buffers for optimum cache performance.  If you keep everything in the
root directories on your hard disk partitions, you'll want a lot of F
buffers.  The amount of memory taken up by cache buffers is another
consideration.  Normally, each cache buffer (F or D) uses a little over
512 bytes, so if you're running CACHE90.PRG, you'll get about 90K of
cache buffers.  If you are using AHDI 3.01, and have any partitions
bigger than 16 megabytes, the cache buffers will be bigger (1K or more
each).  CACHEnnn tells you the approximate amount of memory it uses for
cache buffers when you run it, so you'll know if you're using an
outrageous amount of cache memory. Experiment with different numbers -
you won't hurt anything.

Error handling...
=================
CACHEnnn will abort with an informative error message if you give it no
arguments and it is unable to find itself in the current directory or in
the auto folder on your boot disk.  It will also check to make sure you
aren't trying to add too many cache buffers, and it will refuse to add
buffers if they leave less than 256K of free memory.  All that cache
memory isn't going to help you much if you don't have any memory left to
run programs!

CACHEnnn Caveats
================
CACHEnnn is most useful on a system which has TOS version 1.4 (Rainbow
TOS) or later, with a hard disk.  Cacheing will help with floppies too,
but the performance increase is much more dramatic on a hard disk
system.  Usually on a floppy based system, you're popping disks in and
out frequently, and that invalidates the information in the cache. 
Hard disks, on the other hand, are removed much less frequently, so
information cached from hard disks is valid as long as your system is
turned on.  You can use CACHEnnn with TOS versions previous to Rainbow
TOS, but there isn't much point.  Older TOS versions will use the cache,
but they will often ignore it and go to the disk instead of reading
valid information from the cache.  If you don't have Rainbow TOS, you
will see very little, if any, performance improvement using CACHEnnn.

Technical stuff
===============
An earlier version of this cache program was distributed with early Beta
releases of TOS 1.4.  THAT PROGRAM CAN NOT BE USED WITH AHDI 3.01!  The
reason for this is that AHDI 3.01 (unreleased at the time the original
cache program was written) requires variable size cache buffers.  This
official release of CACHEnnn handles variable size buffers correctly.

If you're concerned about how much memory this program is wasting (after
all, it is a whopping 1051 bytes long), don't be.  The program uses a
psychotic method of installing itself which only leaves 128 bytes more
than the actual cache memory requested after the program terminates.  I
would have gotten rid of that 128 bytes if I could, but GEMDOS won't let me.

Developers who are interested in the technique of adding cache buffers
to GEMDOS are referred to the Rainbow TOS release notes, where the
subject is covered thoroughly.  All in all, it's just easier to use 
CACHEnnn.

