\documentstyle[11pt]{article}

\newcommand{\vault}{{\em The Vault}}

\title{Release Notes for The Vault version 3.00 Beta}

\author{Robert Fischer}
\date{January 18, 1991}

\begin{document}

\maketitle

{\sf

This manual and the programs it describes are copyright \copyright
1987--1991 by Robert P. Fischer.  Permission is granted to reproduce
this document in any form.  It may not be changed except to alter its
layout for printing.  When distributing this document, you must
distribute the original TeX form of the document along with it.  No
copy of this document, in machine-readable or other format, may be
sold for profit, but it may copied freely for non-commercial purposes. 

The programs that this manual describes are also copyright \copyright
1987--1991.  They may be given away under certain conditions.  Run the
programs for more details.

This manual and the programs it describes are distributed in the hope
that they will be useful, but WITHOUT ANY WARRANTY; without even the
implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.  In particular, no warranty is made about the accuracy of
this manual.  You assume all risks of using these products.  The
author is not responsible for damages arising from use of this manual
or the programs it describes, whether caused by negligence or other
fault on the part of the author, or by any other cause. 
}


\vspace{2 cm}

I originally wrote \vault\ in Pascal for a number of reasons: OSS/CCD
Personal Pascal works well even on a 520 ST with floppy, which is what
I originally worked on to develop {\em Mi-Print}, my first large
program.  On a 1040, it can all fit on a RAMdisk, making compiling
quick.  Once the compiler loads, it compiles its code quickly,
shortening the edit-compile-debug cycle.  And at that time, I only had
the Alcyon C compiler available, which left much to be desired.  Finally, if I
{\em really} needed something in C, I could write it in C and include
it in my Pascal program. 

But in time, for a variety of reasons, I started writing all my
programs in C.  Mark Williams C with the CSD source debugger, an
invaluable tool not available with Pascal, had come out.  I found that
because of the restrictions in Pascal, I was writing lengthy code to
do what I could do in a couple of statements in C, slowing down my
Pascal programs and making them longer.  Pascal didn't allow global
variables which are visible from only one module, making global
variables rather messy.  Pascal doesn't allow initialized arrays or
variables.  Pascal doesn't allow computed constants.  There's no way
to tell Pascal a default include directory, nor can Pascal include a
file from inside an include file.  Therefore, I started writing many
programs in C, but \vault\ remained in Pascal. 

I eventually started having problems including my C code in \vault.  I
had originally just compiled it with the Alcyon compiler, but Mark
Williams C used a different object file format and I wanted to get
Alcyon C off my hard disk because it took up space.  Converting
everything to Mark Williams format didn't work, and I couldn't convert
it all to Alcyon/Pascal format because there's no program to do that.
I eventually compiled into Alcyon format with Mark Williams C plus the
MADmac assembler, a less than perfect combination.  But I realized
that if I ever wanted to release the source code, few people would be
able to compile it because few people have Pascal, Mark Williams C and
MADmac. 

Finally, I started to come across C code which I wanted to include in
\vault\ but couldn't because it did something fancy --- it's next to
impossible to include C code which uses any C library calls
(especially {\tt malloc()}) or GEM.  Often, I would have to hand
translate from C to Pascal and end up with two versions of everything.
One large window module which I wrote in C I couldn't include in
\vault\ at all (I still haven't, but I plan to some day). 

Personal Pascal 2.0 came as the final blow because it used a different
object file format.  I couldn't develop my LynxLib in Pascal with it
because I had no librarian for the new format.  Then OSS went out of
business.  I realized that I was stuck with Pascal version 1 as it
stood.

Therefore, I decided to convert \vault\ to C.  I didn't like any of
the Pascal to C translators I saw because they made an ugly C program
which couldn't easily be modified, and didn't account for vast changes
in code like a change in string formats.  I thought of converting one
module at a time to C, but rejected that because converting one module
requires a lot of work interfacing the new code with Pascal, which is
esssentially wasted if you plan to convert the entire program to C
eventually.  Therefore, I converted the whole program, tested each
module bottom-up and put them together to get a program which worked
almost exactly like \vault\ 2.01.  I then added many improvements I
had wanted to add to end up with the \vault\ 3.00.

%  But beware,
%because \vault\ 3.00 is 100\% new code it could easily have some bugs
%not found in \vault\ 2.01. 

\section{Changes in The Vault 3.00}

\begin{enumerate}

\item As already stated, it's written in C instead of Pascal.  This
makes \vault\ run faster and smaller: \vault\ 2.01 was over 90,000
bytes long, while \vault\ 3.00 before its new features was just over
half that.  Even the Beta release is under 70,000 bytes.  \vault\ 3.00
should also use less memory for data storage because, thanks to the C
language, it allocates only what it needs.  All this means that
\vault\ 3.00 can run in even less memory than \vault\ 2.01. 

\vault\ 2.01 had a problem that it would often bomb and mess up the
system after it exited.  This was something to do with Pascal and GEM,
and was not the fault of \vault.  Needless to say, because \vault\
3.00 uses C instead of Pascal, this bug is gone.

\item When you first run it, you should notice that \vault\ 3.00 loads
its help much faster.  In addition, the help is now where you need it
--- every dialog box has a button labelled ``Help'', and selecting
that button brings up an appropriate help screen.  Many help screens
have been removed from the main menu and moved to the ``Help'' button
in a dialog box where they belong, and the remaining ones are now
organized logically. 

Help screens are also cross-referenced, so you can view relevant help
screens with buttons at the bottom of each help screen.  To go to the
help screen you came from, press ``Previous'' at the bottom of the
screen.  If you press ``OK'' and go back into the help system with the
``Help'' button again, you will end up on the same screen as you left
the help system from, as if the help system were a book which you left
open. 

\item When looking for the help file VAULT.HLP, \vault\ now looks for
it in a folder specified in the environment variable VAULTDIR. 

\item The licensing agreement which you see when you click on ``Terms''
after selecting ``About The Vault'' now uses the standard help box
form and comes in readable-size type.

\item The dialog box you see when you click on a Backup or Copy action
in the ``File'' menu is brand new.  In order to back up multiple hard
disk partitions on one backup set, it now lets you select many
starting folders, each with its own list of folder patterns.  When
\vault\ runs a backup, it backs up each of these starting folders
separately into a different output folder on the backup set. 

The way you select your starting folder and folder patterns is now
entirely mouse-based.  \vault\ displays two windows on the screen: one
of the starting folders and the other of the folder patterns for the
selected starting folder in the first window.

When you have the starting folder window selected as the current one,
the buttons in the middle (``Add'', ``Clear'', ``Insert'', ``Delete'',
``Edit'') let you manipulate the starting folders in obvious ways.
``Add'' adds another starting folder to the end of the list of
starting folders displayed in the window and gives you a files
selector to choose it.  ``Clear'' clears everything from the currently
selected window.  ``Insert'' inserts a new starting folder immediately
before the currently selected item.  ``Edit'' lets you change the
currently selected item using the file selector, and ``Delete''
deletes it. 

Similarly, when the folder patterns window is current, you can insert
and delete new folder patterns.  In this window, though, when you're
given the file selector to select a pattern, you start at the
currently selected starting folder and are not allowed to select a
folder not included in the starting folder.  \vault\ takes the folder
you select and removes the starting folder from the beginning of it,
to give a folder pattern like you would type in \vault\ 2.01.  For
example, if the selected starting folder were ``E:\verb|\|R\verb|\|''
and you selected ``E:\verb|\|R\verb|\|PROGRAMS\verb|\|'' with the file
selector, you would get PROGRAMS\verb|\| as the folder pattern.  To
set or unset the ``Files Only'' and ``Exclude'' switch (`\#' and `!'
in \vault\ 2.01), click on the appropriate buttons, and you'll see it
happen on the screen. 

Often, a starting folder or folder pattern will become too line to fit
in the window.  Then, you can use the scroll arrows next to each line
to scroll the line left and write in the window.

Because one backup can now have many starting folders and each one
requires its own output folder, \vault\ no longer lets you choose
the output folder on a Backup, but rather generates it automatically
from each starting folder.  It takes the device name the folder is on
as the first letter of the output folder, and then appends up to 7
letters of the input folder name.  For example, from an input folder
named ``C:\verb|\|TMP\verb|\|PROGRAMS'', \vault\ would generate
``CPROGRAM'' as the output folder.  Another example,  \vault\ would
generate ``E'' as an output folder from the starting folder
``E:\verb|\|''.  If \vault\ runs into a conflict
between output folder names, it uses a different letter as the last
letter of the output folder name until the conflict is resolved.  For
example, if it had to back up ``C:\verb|\|TMP\verb|\|PROGRAMS'' and
``C:\verb|\|REAL\verb|\|PROGRAMS'' on the same backup set, it would
name the first output folder ``CPROGRAM'' and the second one
``CPROGRAA''.

On a copy, (Full Copy or Incremental Copy), you {\em do} get to
choose the output folder, but you may not use more than one starting
folder.  If you do, \vault\ will copy from the first and complain
about the rest.

\vault\ 3.00 now lets you select the full pathname of the backup
history, on a line at the bottom of the screen.  You can either type
it in, or select it using the ``Select Backup History'' button.  No
matter what file you select, \vault\ forces its extension to ``.HST'',
and will write a ``.HST'' and ``.CTL'' file from it.  For example, if
you select ``C:\verb|\|FOO.C'', \vault\ will write ``FOO.HST'' for its
backup history and ``FOO.CTL'' for its control file. 

At the bottom of the screen, you now have two lines of space instead
of one to give \vault\ wildcard patterns. 

\item \vault\ now formats skewed disks (more commonly known as
Twisted) on TOS 1.2 or later if you like.  It didn't do this in
version 2.01 because I prefer FastFlop, which is faster than Twister
and doesn't require that you format your disks specially. 

You can also format your disks up to 83 tracks, if you like.  I
don't reccomend this.

\item While \vault\ is actually doing its work, the screen is much
improved to show you more information about what \vault\ is doing
internally.  At the top of the screen are the parameters you entered
in.  If they are too long to fit on the line, they are truncated, but
only when displayed the screen; \vault\ still remembers them
all. 

In the middle of the screen, \vault\ tells you which folder it's
scanning, and which file it's reading.  It can't scan and read at once,
so one line is always blank.  These two lines are easier to
follow because, unlike in \vault\ 2.01, they are not centered on the
screen and therefore do not jump about as their lengths change.

Most useful, at the bottom of the screen \vault\ displays
``thermometer bars'' which show \vault 's approximate progress on the
current disk.  Internally, \vault\ has always worked in three phases:
first it scans the hard disk, planning what it will write on the
floppy.  When it's filled up the floppy in this {\em packing} phase,
it starts to actually copy the files.  But since \vault\ has put its
own floppy disk cache in the right place, \vault\ actually only reads
data from the hard disk during this phase.  When the cache fills up
(usually at the end of the disk for a Mega 2 or 4, or somewhere in the
middle on a 1040 or 520), \vault\ actually writes this data out to
disk. 

The three thermometer bars at the bottom show how much of each
phase \vault\ has completed.  They start out showing how much of the
disk is already full, and end up at approximately the same place.
Just from a glance, you can tell useful information from these bars.
For example, if the ``Scanning'' thermometer has filled up partway and
\vault\ is on to copying, you know immediately that this is the last
disk because \vault\ left empty space at the end, and you know
approximately how long this disk will take based on how full \vault\
has packed it.

The ``Writing'' thermometer bar poses a special problem to \vault.
While \vault\ is writing to the disk, there is no good way to update
the thermometer bar.  Every time \vault\ updates that thermometer bar,
depending on which format floppy you're using and whether you're using
FastFlop, it loses up to .2 seconds.  I made a compromise and made
\vault\ update the thermometer bar every eight tracks it writes,
costing up to 2 seconds per disk, which I feel is almost
insignificant.  Using the option ``Set Miscellaneous'' in the
``Options'' menu, you can set the number of tracks \vault\ will write
before it updates the thermometer bar.  If you're using non-skewed
disks without FastFlop, you should set this to 1 because \vault\
doesn't lose any time on these disks in updating the thermometer bar.
If you format your disks in some way to accelerate them, chances are
updating the thermometer bar will slow down \vault, so you'll want to
set Max Tracks to a compromise like 8.  The only way to tell for sure
if using a smaller Max Tracks number slows down \vault\ is to try it. 

When \vault\ finishes, it now leaves the status box on the screen so
that you can tell at a glance how much of the disk is full.

\item When \vault\ finishes with a disk, it now rings a bell
periodically, in order to alert you that it's ready for a new disk.
It also rings the bell when it's finished with the backup.  You can
set the Ring Interval (the interval between two rings in 1/200ths of a
second) using ``Set Miscellaneous'' under the ``Options'' menu. 

\item All data files of \vault\ now use a different format, although
except for the help file, \vault\ 3.00 is upwardly compatible with
\vault\ 2.01 data files. 

\begin{itemize}

\item

The help file (VAULT.HLP) is now flexible in format and allows you to
edit it easily, and even add additional help screens without changing
\vault.  To begin a help screen, start the title line with a tilda
character (`\verb|~|') and the help screen's name.  On the same line, give
the names of the help screens you want to cross reference this one
with, separated by colons.  For example, if this help screen is named
``Foo'' and you want cross references to ``Bar'' and ``Neat Bar'', the
title line of Foo should be: ``{\tt \verb|~|Foo:Bar:Neat Bar}''

All lines between the title line and the next title line are part of
the named help screen.  The first line after the title line will be
centered and is good for giving a title which the user will see at the
top of the help screen.  You may use up to 18 lines, not including the
title, for the help screen.  If you use fewer, \vault\ will fill the
rest of the lines with blank space.  If you use more, \vault\ will cut
your help screen short, but will not crash.  Currently, \vault\
supports up to 35 help screens, althought that is arbitrary and it
{\em could} support as many as you have energy to write. 

\item

The .VDF file format is also more robust.  Each line consists of the
name of the option, a colon, and the value of the option.  A
dollar-sign preceding the value indicates that it's a hexadecimal
number.  Options may be missing, in which case \vault\ does not change
that option when it loads the .VDF file.  Options may also be in any
order, although \vault\ writes them in alphabetical order.  If \vault\
finds an option which it does not recognize, it will tell you and
continue. 

With the new .VDF file format, any version of \vault\ will be able to
read any .VDF file created by any previous (or even future) version
and make sense out of it, even though different .VDF files may have
different options.  For the experienced user, the .VDF file should now
be easier to edit with a text editor because it's clear what every
option is and how to change it.  Of course, \vault\ still reads help
files from \vault\ 2.01 automatically.

\item

The backup history format is also more robust, allowing \vault\ to be
compatible with previous and future formats of this file.  If \vault\ 3.00
is allowed to write a new backup history, it will leave a lot of
blankspace on each line of the header with a semicolon terminating relevant data.
This is room for expansion.  On old backup history files, \vault\ 3.00
works just fine.

Since \vault\ picks the backup folder automatically, the line ``Last
Backup Folder'' has been changed to ``Last Incremental Number'', and
\vault\ now only writes a number on that line.  Thus, when using
\vault\ 3.00 for the first time, you may see a bit of garbage on the
line {\em after} the semicolon.  For example, in a history file with
the line ``{\tt Last Backup Folder: EBACK.004}'', after running an
incremental backup with \vault\ 3.00, you will see ``{\tt Last Backup
Folder: 005;K.004}''.  Don't worry about the garbage after the
semicolon; \vault\ ignores it and will work just fine. 

\end{itemize}

\item You can now halt \vault\ at any time while it is backing up by
holding down Control-(left)Shift-Alternate-Undo until it halts.
Unfortunately, \vault\ cannot give an alert box to confirm this but
halts immediately, so halt \vault\ with caution.  While \vault\ is
actually writing to the floppy disk, it cannot ``see'' that you've
halted it until it pauses to update the ``Writing'' thermometer bar,
so it may respond sluggishly. 

Since \vault\ halts immediately upon seeing your request without even
dumping any caches, the disk it writes may or may not be a consistent
TOS-format disk.  If \vault\ didn't start the ``Writing'' phase or
spin the disk during either of the other phases, chances are that the
disk is OK. 

\item \vault\ now takes command line arguments.  When given the name
of a {\tt .VDF} file on the command line, \vault\ will load the given
file instead of {\tt VAULT.VDF} when it starts up.  This way, you can
use the {\em Install Application} feature of the Desktop to start
\vault\ with the {\tt .VDF} file of your choice.  To do this, click on
the icon for \vault, select {\em Install Application} under the {\em
Options} menu, and enter {\tt VDF} as the document type.  Then, when
you double-click on a {\tt .VDF file}, \vault\ will run with your
selected file pre-loaded. 

\end{enumerate}

\section{Bugs and Pitfalls in The Vault}

The following are known bugs or problems with \vault\ 3.00.  They {\em
all} existed in previous versions of \vault. 

\begin{enumerate}

\item Do not back up from a floppy disk to itself.

\item Do not use dual mode on a single-floppy system.

\item Do not format disks in dual mode.

\item Be careful of {\em Archive Bit} backups.  In order to make
subsequent Cleanup Incrementals work correctly, \vault\ must change
the date on files which were too old to be backed up because of their
date but were backed up anyway because their archive bit was set.
There is {\em no} way to avoid this problem, because TOS really needs
two archive bits -- one which you clear when you make an incremental
backup and one which you clear on a full backup. 

\end{enumerate}

\section{The Key}

{\em The Key} has not changed since the previous release of \vault.
\vault\ 3.00 is completely compatible with the old version
of {\em The Key}. 

\end{document}