\documentstyle[11pt,titlepage]{article}

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

\title{The Vault and The Key}

\author{Robert Fischer}
\date{February 17, 1990}

\begin{document}

\pagenumbering{roman}

\maketitle

\vfill
{\sf
User's Guide for \vault\ version 2.01 and \key\ version 1.1.
Manual version 1.01.

This manual and the programs it describes are copyright \copyright
1987--1990 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.  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--1990.  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. 
}
\vfill
\newpage

\tableofcontents

\newpage

\section{Introduction}

\pagenumbering{arabic}

\vault, and \key\ are two programs which help you get
more out of your hard and floppy disks.  \vault\ backs up your
hard disk in almost no time at all, and \key\ restores your
hard disk in case of a crash. 

\section{\vault : A Hard Disk Backup Program}


\subsection{Introduction}

\vault\ has one purpose -- to protect your valuable 
programs and data on a hard disk from loss.  A hard disk must be 
backed up frequently because its files can be lost at any time 
without warning.  \vault\ automates and speeds up the backup 
process, reducing the chance for human error and making it easy 
for you to do on a regular basis.

\vault\ is special because of its advanced user interface 
and integrated floppy disk caching scheme which speeds up the 
writing of backup disks.  It is totally GEM-based and contains a 
comprehensive help system.  It is easy to use and guides you 
through correct operation of the program.  It creates ordinary TOS 
disks, complete with file directories, so that individual files 
can be examined or restored at will.  It has an incremental mode 
that automatically backs up only those files that have changed 
since the last backup.  If run regularly, incremental backups are 
generally very fast and offer the best possible protection for 
your data.
 
Some other special qualities of \vault\ are:

\begin{itemize}
\item
It doesn't require large amounts of memory and will run quite 
 satisfactorily on a 512K machine, even with desk accessories 
 and/or a moderate sized ramdisk in place.

  \item \vault\ can back up files that are too large to fit on a 
 single floppy.  Such files are split into as many pieces as 
 necessary and each piece written to a floppy.  The pieces 
 themselves are ordinary files and contain a header line that 
 allows the restore program to insure that all pieces are 
 reassembled in the proper order.

  \item \vault\ uses a clever disk packing algorithm which 
 minimizes the need to split files and can usually fill a disk      
 to within a few thousand bytes.  Often, it fills a disk 
 completely without splitting a single file!

  \item \vault\ does a significant amount of input error checking, 
 keeping you from accidently inserting the wrong disk or from 
 wiping out the data you are trying to protect.

  \item \vault\ maintains a history file on the hard disk that lets 
 you quickly locate which disk a file is backed up on and when 
 it was written.  It also uses the history file itself to make 
 incremental backups virtually automatic.

\item Best of all, \vault\ is {\em FAST}.  It writes files almost
as quickly as the floppy drive can move its read/write head.  This
speed makes it feasible for you to use \vault\ every day, not just
when you have a few hours to kill during special occasions.  Remember,
\vault\ will help you protect your valuable files, but only if you
use it! 

\end{itemize}

\subsection{Why Back Up a Hard Disk?}

A backup program takes care of copying files to backup disks, 
but you must take care of those disks and make sure that you don't 
inadvertently destroy data.  To do this effectively requires that 
you understand the kinds of things that can happen to your data 
and that you set up systematic procedures for managing your backup 
disks.  We suggest some procedures below, along with a description 
of some of the hazards to which your data is subject.

\subsubsection{How to Lose Data}
\label{losingdata}

Data can be lost in many ways.  The most common mishap is for 
you to accidentally delete one or more files you wanted to keep.  
This can happen to anyone in a distracted moment, through 
confusion, or because of bugs in the software you are using.  The 
damage from this kind of error is normally confined to a small 
number of files, but it can be quite devastating when it occurs.

Less frequent but far more catastrophic are errors that 
damage the entire disk.  Power surges or other power failures 
while the drive is in the middle of writing can cause this to 
happen.  Normally only the file you were writing will be lost, but 
if the allocation tables or directories become corrupted, other 
files files in the same folder or partition may be lost as well. 
Worse still, the head may ``crash", ruining not just the data on 
the hard disk, but also the hard disk itself.  The disk can be 
repaired or replaced, but the data is lost forever -- unless you 
have used \vault.

Data can be lost even when the computer is not turned on.  
A hard disk can be damaged by a hard bump and will almost 
certainly not survive a drop to the floor.  Bits on the medium can 
sometimes randomly change, perhaps as a result cosmic radiation or 
strong magnetic fields.

Floppies too are vulnerable to many hazards.  Even though 
they appear rugged, floppies have been ruined just by being placed 
next to a ringing telephone.  Leaving them in the sun, spilling 
coffee on them or simply misplacing them can all lead to loss of 
data.  The magnetic medium may also be substandard or worn.

Although some of these possibilities seem unlikely, they all 
have happened.  The message is clear -- if you want to be assured 
that your data is safe, {\em you must have at least two copies of your 
data at all times.  Moreover, at least one copy must always be in 
a safe environment, out of the machine.}  It follows that you 
need two sets of backup disks so that the one can be kept in a 
safe place while the second is being written.

Backing up may take extra time, but the insurance is well 
worth it.  Like all insurance, you don't need it until a loss 
occurs, and then it is too late to start using \vault.


\subsubsection{Strategies for Backing Up}

\vault\ lets you do three kinds of backups.  A {\em full backup}
copies all the files on the disk.  It often takes a long time because
a hard disk stores a lot of information.  It should be done initially
and then from time to time whenever a clean copy of everything on the
hard disk is desired. 

Backups should be done frequently, but the files on a disk 
change slowly.  Most of the time, only a small part of the hard 
disk changes between backups, making it redundant and wasteful of 
time to always do a full backup.  A {\em daily incremental} copies only 
those files that have changed since the last full or incremental 
backup and is generally quite fast.

After many daily incremental backups have been done, the 
incremental backup disks may contain many copies of frequently 
changing files.  This takes up valuable disk space and makes it 
harder to find the most recent version of a file should it need to 
be restored.  When that happens, a {\em cleanup incremental} backup can 
be used to ``clean up" and reorganize the several disks full of 
incremental backups, writing out the current version of every file 
that has changed since the last full backup (rather than since the 
last incremental backup).  If the incremental backups still use 
too many floppies, it is time to make another full backup.
 

\subsubsection{Organizing Your Backup Disks}
\label{organize}

Since a hard disk is many times the size of a floppy disk, it 
takes many floppies to back up a hard disk.  This set of disks is 
called a {\em backup set}.  Each disk in a backup set is identified by 
a {\em disk name} consisting of a {\em backup set name} and a {\em volume number}.  
If the backup set is called BACKA, the first disk in the backup 
set would be called BACKA.\$01, the second would be BACKA.\$02, and 
so forth.

The disk name is written on the disk by \vault\ and checked 
during subsequent backups to make sure the proper disk has been 
inserted.  You should also label the floppy the same way so you 
can easily identify it later.

As mentioned in Section~\ref{losingdata}, keeping only one backup
set is not enough to provide full protection.  If you are backing up
the hard drive with your only backup set in the floppy drive and you
discover an error with a file on the hard disk or the hard disk
crashes, you are out of luck, for there is no complete backup set from
which you can restore your hard disk files. 

Thus, you should have two backup sets for full backups, and 
they should be rotated.  The first time you do a full backup, you 
should use set 1.  The next time, use set 2, the next time, set 1 
again, and so on.

For even greater protection, you might consider having a 
third ``disaster backup set" which you only write occasionally and 
then put into safe storage, preferably at another location.  Not 
only does this provide protection again disasters such as fire, 
but it also offers some protection against hidden errors.  
Sometimes a file might become corrupted but the error not 
discovered until weeks later when the file is used.  If you have 
been faithfully backing up your hard disk and rotating among the 
two backup sets for full backups, the corrupted file will 
eventually be propagated to all of your backup disks, and when you 
go to recover it, all you will find is several copies of the same
bad file.

To successfully rotate your backup sets, you must remember 
which one was used last.  If you keep your backup disks in a box, 
put the most recently used set in the front and you will 
never forget which one was used last.  If you do get mixed up, you 
can look in the history file on the hard disk (\_BACKUP.HST or 
\_BACKUP.CTL on the floppy disk).

In addition to the full backup sets, you need two incremental 
sets consisting of two or three disks each.  Every day, before 
shutting off the computer, do a daily incremental backup.  This 
will usually add only a small amount of data to the incremental 
set.  After repeated daily backups, the incremental set will 
eventually fill up.  At this time, you can do one of two things.  
If the hard disk has changed significantly since the last full 
backup, then do another full backup.  Otherwise, perform a cleanup 
incremental backup on the second set and rotate the sets so that 
the set on which you just performed the cleanup incremental is the 
one on which future daily incrementals will go.  The old 
incremental set is then no longer needed and should be kept 
idle until the time comes for another cleanup incremental.


\subsubsection{Rules for Safe Backups}

You must remember these rules about safe backups:

\begin{itemize}
  \item Do a full backup every once in a while, rotating full backup 
 disk sets.

  \item Do an incremental backup every day before you turn off the 
 computer.

  \item Back up your hard disk before you endanger it by running a 
 new untested program.

  \item Keep your backup sets well organized and store them in a 
 clean, cool, dry environment away from magnetic fields and 
 other hazards.

\end{itemize}

\subsection{Getting Started -- Performing a Full Backup}

Now that you understand about backup procedures, you are 
ready to begin using \vault.  Boot your machine normally, and 
{\em be sure always to set the clock}.  Incremental backups will not 
work properly unless the clock is {\em always} set correctly whenever 
you are using the machine, for otherwise the file dates will not 
be meaningful.

Copy the files {\tt VAULT.PRG}, {\tt VAULT.RSC}, and {\tt
VAULT.HLP} to your hard disk program folder.  Put your Vault
distribution disk in a safe place and double-click on {\tt VAULT.PRG}.  You
are now standing in \vault, the most sophisticated backup program
that exists for the Atari ST. 


\subsubsection{Preparing the Backup Set}

As described in Section~\ref{organize}, you will need at least
two full backup sets and two incremental backup sets.  You should
begin by preparing labels for each disk in each set.  Pick a
suggestive name for each of the four backup sets such as {\tt BACKA},
{\tt BACKB}, {\tt INCRA}, and {\tt INCRB}.  The name can be up to
eight characters long and should consist only of letters and numbers.
The disks in each set should be numbered, beginning with 1.  \vault\
places a dollar sign in front of the volume number of each disk so
that the that the disk name will never be confused with a file or
folder.  For example, {\tt BACKA.\$01} is the first disk of backup set
{\tt BACKA}, {\tt BACKA.\$02} is the second, and so forth. 

To get a rough estimate of how many diskettes you will need,
go back to the desktop, click on the desktop icon for your disk 
and select the {\em Show Info} menu item to look at how many bytes are 
written on the disk.  Divide this number by the number of bytes 
that will fit on a disk.  This estimate may be too small, but 
serves as a good starting point.


\subsubsection{Selecting Parameters}

To do a full backup, return to \vault\ and click on the 
menu item labeled {\em Full Backup} under the {\em File} menu.  You are now 
looking at the input parameters dialog box.  The first and most 
important item here is the `directory to back up'.  \vault\ can 
either back up a full drive partition or only part of a file tree.  
You can enter this information in two ways.  Either type it in, or 
use the `all click' method described below.

% ***** OBSOLETE STUFF ON DRIVE BUTTONS *****
% first click on the drive you want to back up.  These are 
% represented by small boxes with drive letters in them.  When you 
% do this the drive letter will appear on the text line below the 
% buttons.  If you want to back up the entire directory tree, you 
% are done and can click on OK.  If you want to back up only a 
% folder or subfolder, either type in its name or use the file 
% selector.  To use the file selector,

The parameter labeled
`File selection masks' lets you select which files to back up.  Use
*.* to include all files.  Like TOS wildcards, `*' matches any string
of zero or more characters, `?' matches exactly one character, and
other characters match themselves.  Thus, *.PAS would match only those
files whose type is `.PAS', and *2.? would match all files whose name
ends with `2' and whose type is a single character. 

If you give more than one mask, \vault\ uses them from left 
to right.  For example, *.pas *.c backs up all the `.PAS' and `.C' 
files.  A mask preceded by an exclamation point (!) excludes the 
matching files.  For example, *.* !*.BAK backs up all files except 
the `.BAK' files.  Each new mask adds to or subtracts from the set 
of files specified by all preceding masks. For example, *.* 
!TEST.* *.C starts with all files, then removes those  matching 
`TEST.*', then adds back all files matching `*.C'.  Note that 
`TEST.C' will be backed up by these rules.

To select the directory to back up entirely with the mouse, click on
the `Select Starting Directory' box.  The standard file selector will
show and you can change the directory displayed in it.  When the
directory you want to back up is showing in the file selector box,
click on OK.  The parameter box will reappear with the directory name
showing on the line below the buttons.  The history file will be
written in the starting directory.

The parameter labeled `Directory selection masks' lets you specify
which subdirectories of the starting directory above you want backed
up.  If you want the starting directory and all subfolders, just put a
dot (`.') on this line.

Fancier selections can also be made here, and
the parameters on this line are parsed similarly to the paramaters of
the file selection masks line.  This line usually starts with a `.',
adding the starting directory and all its subdirectories into the set
of directories to be backed up.  Each new mask, which cannot be a
wildcard, adds a directory from this set.  As above, if the mask is
preceded by a `!', it is subtracted from the set instead.  Usually, a
mask includes or excludes the named directory and all its
subdirectories.  If you only want the mask to affect the named
directory and not its subdirectories, precede it with a sharp character
(`\verb|#|').  All
masks are relative to the starting directory.  That is to say, if the
starting directory is {\tt E:\verb|\|R\verb|\|} and you want to name
the directory {\tt E:\verb|\|R\verb|\|VAULT\verb|\|}, {\tt
VAULT\verb|\|} would be the correct mask for this.  Say the starting
directory is {\tt E:\verb|\|R\verb|\|}.  The following examples show
how directory selection masks work.

\begin{itemize}
\item `{\tt \verb|#|.}' backs up E:\verb|\|R\verb|\|, but not its subfolders.
\item `{\tt . !VAULT\verb|\| VAULT\verb|\|SRC\verb|\|}'
backs up E:\verb|\|R\verb|\|, E:\verb|\|R\verb|\|VAULT\verb|\|SRC\verb|\|,
and all of their subfolders except for E:\verb|\|R\verb|\|VAULT\verb|\|.
\item `{\tt . \verb|#|!VAULT\verb|\|}' backs up E:\verb|\|R, the subfolders of
E:\verb|\|R\verb|\|VAULT\verb|\|, and the subfolders of
E:\verb|\|R\verb|\| except for E:\verb|\|R\verb|\|VAULT\verb|\|.
\item `{\tt . !PD\verb|\| !VAULT\verb|\| !OBJFILES\verb|\|}' backs up
all of E:\verb|\|R except for the E:\verb|\|R\verb|\|PD\verb|\|,
E:\verb|\|R\verb|\|VAULT\verb|\|, and
E:\verb|\|R\verb|\|OBJFILES\verb|\| and all of their subfolders.  This
is probably how most directory selection masks will look; one wants to
block out entire subdirectories.
\end{itemize}

% When the box labeled `Copy subfolders' is checked, \vault\
% backs up the folder you specify and all its subfolders.  If you 
% uncheck this box, \vault\ will not back up subfolders.  
% Normally, this box should be checked.

When you have selected all of the input parameters, click on 
OK and the output parameters box will appear.

The first thing to select here is the name of the backup set 
you will be using.  If you want the starting disk to be other than 
the value shown (usually 1), you must also type in the starting 
disk number.

You must also select the name of the output folder.  This 
name will be used on the full backup and all incrementals to 
identify backups of the selected input folder.  Although this name 
can be only eight characters long, we suggest that you use a name 
suggestive of the input name.  For example, if you are backing up 
the folder {\tt E:\verb|\|RECORDS}, you might choose {\tt EREC} for 
the output folder 
name.  All of the files and folders from {\tt E:\verb|\|RECORDS} will be placed 
in the folder {\tt EREC.FUL}.  Later incrementals will automatically use 
the names {\tt EREC.001}, {\tt EREC.002}, etc.


\subsubsection{Inserting a Disk}

When you have selected all your options, click on the button 
labeled `OK'.  You will be given a box and asked to insert a 
disk.  {\em NEVER TAKE OUT OR INSERT A DISK UNLESS YOU SEE THIS BOX OR 
\vault\ TELLS YOU THAT IT HAS FINISHED BY DISPLAYING AN ALERT 
BOX!}  You should now insert the disk requested by \vault\ into 
either drive A or B.  Check the appropriate drive box to tell The 
Vault which drive you are using.

If the disk needs formatting, check the `Format' box.  If the disk is
already formatted but you want to clear it, click the `Clear Disk'
box.  If you want to append to a disk already written by the Vault,
check the `Append' box.  Normally when you do a full backup, you will
want to clear the disk, but the first time you use the disk, you must
of course format it. 

The `Dual Drive' option is useful if
you have two floppy drives and your disks are already formatted.
(This is usually the case; you only have to format disks once.)  If it
is selected, \vault\ starts by writing a disk in the drive you told it
to above.  When it is done writing that disk, it will look in the
other drive for the next disk it expects.  If it finds this disk, it
will go on and write it; otherwise, it comes back to the `Insert Disk'
dialog box being described here, asking you to insert an appropriate
disk.  Similarly, when \vault\ is done writing to the second drive, it
looks in the first drive again.  If when \vault\ is writing in one
drive, you put an appropriate disk in the other, \vault\ could write
continuously, never waiting for a disk change!

\vault\ will never format a disk automatically in dual mode, even if
the format option is selected, because formatting tells \vault\ to
{\em not} look at disk labels, but to go ahead and clear whatever disk
is in the drive.  This could be dangerous when done automatically; if
this option were in \vault\ and the user put two disks in the two
drives, \vault\ would go ahead and write disk 1, then disk 2, then
overwrite disk 3 onto disk 1, disk 4 onto disk 2, disk 5 onto disk 3,
and so on. 

The `Save Defaults' button shown in this box works exactly the same
way as the `Save Defaults' option from the main menu, described in
section~\ref{savedef}.  When you are done selecting the options for
this box, click on `OK'. 

\paragraph{Formatting a Disk}

\vault\ has a facility for formatting a disk before it is written on.
It can only format standard (non-twisted) disks of either nine or ten
sectors per track but can read and write disks which are formatted
differently as long as GEMDOS can also.  If you have your own favorite
disk formatter, you can use it instead of the one built into \vault.
If you do this, you will need to format all the disks you need before
you enter \vault. 

If you have checked the `Format' box, \vault\  will give you 
the `format options' dialog box after you insert the disk and 
click on OK.  You can choose either one or two sides (for 
a double-sided drive), and either nine or ten sectors per track.  
You will probably want ten sectors per track because it will let 
you put more data on each disk.  (Note however that there are a 
few restrictions on the use of 10 sector disks.  In particular, 
you can not use the desktop's disk-to-disk copy with them, 
although ordinary file copy works okay.)  When you are finished 
selecting the format options, click on `Format'.  If you decide 
not to format and want to insert a different disk instead, click 
on `Cancel'. 
 
The `Random Serial Number' option can normally be ignored, 
but if you are interested, here is what it does.  Each disk has a 
24 bit serial number that should be different on every disk 
you own.  (This number has nothing to do with the backup set 
volume number mentioned earlier.)  TOS uses the serial number to 
tell when a disk is changed; two disks with the same serial number 
inserted one after the other will look the same to TOS and can 
cause you to lose all of the files on the second disk.  Since 
there is no way for TOS to tell what serial numbers are already in 
use, it generates a random serial number when it formats a disk, 
hoping that it will be different from all others.  It usually will 
be.  If the `Random Serial Number' box is checked, as it normally 
is, \vault\ will do the same.  However, if you have your own 
numbering scheme and want to specify which number to use, click on 
the `Random Serial Number' box to remove the check.  A line will 
appear on which you can type your own serial number.  The serial 
number must be specified in HEX (base 16).

\paragraph{Checking Disk Labels}

If you did not tell \vault\ to format your disk, it will 
make sure that you have inserted the correct disk by checking that 
the label written on the disk (if any) matches the current backup 
set name and sequence number.  If they match, \vault\ will 
proceed automatically.  If not, it will give you a dialog box 
asking you what to do.  The two most common reasons for seeing 
this box are that you actually made a mistake and accidently put 
in the wrong disk or that you are making a new backup set and none 
of the disks have labels yet.  In the latter case, you should 
click on `Relabel and Proceed'.  The causes \vault\ to relabel 
the disk and proceed with the backup.  In the former case you 
should insert a different disk (presumably the one that was 
expected) and click on the `Insert Different Disk' button.

A third possibility is that you previously typed the wrong 
backup set name and want to proceed using the backup set you 
actually inserted in the drive.  To do this, click on 
`Proceed'.


\subsubsection{The Backup Process}

After \vault\ has a disk to write on, it does all the work.  
First, it plans which files to put on the disk and quickly creates 
headers on the disk for them.  After all the headers are created, 
it copies the actual data for each of the files.  A sophisticated 
special-purpose floppy disk cache is used to speed writing of the 
files.  Remember to {\bf never take the disk out} until \vault\
asks you to insert a new disk or tells you that it is finished.  
At times, it may look like the floppy drive is not busy, but it 
really is.
 
After each disk is written, \vault\ will ask you to insert 
another.  This process will continue until \vault\ has finished 
the backup, at which point control will return to {\em The Vault's} 
desktop. 


\subsection{Incremental Backups}

To do an incremental backup, select `Daily Incremental' or 
`Cleanup Incremental' under the `File' menu.  These work much the 
same as a full backup except that you won't be asked  for a backup
folder name; \vault\ uses the same name that was used for the 
most recent full backup.  In the case of all but the first daily 
incremental and a cleanup incremental, you also will not be asked 
for the name of the incremental backup set since the same name 
will be used as in the previous incremental.  Instead, \vault\ 
will instruct you to insert the same disk that was last used by 
the previous incremental backup.  However, you can always choose 
to write to a different incremental set by inserting the desired 
disk and then clicking on `Proceed' when informed that the disk is 
not the expected one.

The `Use Archive Bit' option is useful for incremental backups.  TOS
version 1.4 or newer will set the `archive' bit on a file whenever it
is modified.  This includes modifying a file with a database and any
time a file is created.  A file which is moved by copying and then
deleting the old file will have its archive bit set, too. 

Normally, \vault\ does not back up according to how the archive bit
is set, but does clear the bit when it backs up a file.  When the `Use
Archive Bit' flag in the `Options' menu is set, \vault\ will back up
files with the archive bit set and new files when doing an incremental
backup.  If a file it backs up would not have been backed up without
the `Use Archive Bit' flag, The Vault also changes its date so it
would have been.  This way, it will be backed up on subsequent Cleanup
Incrementals. 

Note that this option is not available with TOS 1.0 or TOS 1.2.  To
tell if you have TOS 1.4 or later, select `Desktop Info' from the
`Desk' menu while using the desktop.  If you have a color monitor, you
will see a ``rainbow'' floating across the Atari logo.  In any case,
there will be a long string of copyright dates, the latest which
should be 1989 or later.

\subsection{Error Recovery}

Sometimes, \vault\ may encounter a write error on a floppy disk.  In
this case, it tells you, and you are given the option to insert
another disk to replace the bad one.  When this is done, the new disk
{\em must} be formatted to be at least as large as the old disk, i.e.
it must hold the same amount of data or more.  It is best to replace
the old disk with one formatted in the same manner.

For example, if an error was found writing a single-sided 10-sector
disk, \vault\ requires that you replace it with a single-sided
10-sector disk, or a double-sided disk.  If an error was found writing
a double-sided 10-sector disk, another double-sided 10-sector disk is
the only replacement.

\subsection{Other Options}

\vault\ has a few other options that can on occasion be 
useful.  They are all selected from the {\em Options} menu.

\subsubsection{File Splitting}

\paragraph{The Split Threshold}

As stated before, \vault\ tries not to split files between 
disks but it will do so if necessary to avoid leaving a large 
unfilled ``hole" in a disk.  In more detail, \vault\ will first 
fill up a disk as well as it can without splitting files.  If the 
disk isn't full, it then looks for files which are larger than a 
preset ``split threshold".  If there are any, it will fill up the 
disk by splitting a file; if not, it will go on to the next disk.
Thus, the split threshold is both the smallest size file that will 
ever be split and the largest amount of empty space that \vault\ 
will ever leave on a disk (except for the last).
  
You can set the split threshold by selecting `Set Split 
Threshold' under the `Options' menu.  The threshold is normally 
set at 300,000 bytes.  The split threshold should always be 
smaller than the smallest disk you will be using; otherwise, {\em The 
Vault} will not work correctly if it comes to a file which is 
larger than the disk.

\paragraph{The Parts of a Split File}

When a file is split, \vault\ selects a name for each of its
parts.  The root of this name (that is, the part before the `.') is
the same as the root of the file being split.  The extender has a
unique id letter chosen from A to Z followed by a 2-digit part number.
Thus, the first part of the file {\tt FOO.BAR} may be called {\tt
FOO.A01}, in which case the second part would be called {\tt FOO.A02},
and so on.  If another file or part such as {\tt FOO.A99} already
exists that might conflict with the generated part names, \vault\ will
use B instead of A as the unique id letter.  If that doesn't work, it
tries C, and so forth.  It keeps doing that until it find a letter
that works.  If it can't use any letter, it gives an error.  Note that
if two files such as {\tt FOO.PRG} and {\tt FOO.RSC} both exist and
both need to be split, the parts of one would be named {\tt FOO.A01},
... and the parts of the other would be named {\tt FOO.B01}, ... . 

Each part of a split file contains a one-line, 22-byte header 
describing what file it is a part of, what its part number is, and 
whether it is the last part.  This information is used for putting 
a split file together when restoring it.


\subsubsection{Save Default Options}
\label{savedef}

You may save the default options so they will be the same every time
you run \vault.  To do this, select `Save Defaults' under the
`Options' menu.  All of choices that you made in all of the dialog
boxes and menus will be saved in a file you select, ending in {\tt .VDF}.
The file called {\tt VAULT.VDF} in the directory from which you ran
\vault is read is used to set the defaults when you run \vault.

Setting the default options often consists of ``pretending'' you are
doing a backup, and then at the last minute saving the options.  To
make this easier, a `Save Defaults' button is part of the dialog box
asking you to insert a disk, letting you save the defaults without
quitting your backup run. 

You may have two or three backup sets for one hard disk; one for each
partition would be common.  Each backup run may need different
defaults; for example, you may not want {\tt .PRG} files backed up on
your programming partition because they use up backup disk space and
can be rebuilt easily, but on your system partition, containing all
your commercial software, you most certainly would want to back these
up.  You can load whichever default file is appropriate for your
current backup with the `Load Defaults' option, found just under `Save
Defaults'. 

\subsubsection{Disabling Write Verify}

You may feel that you would rather live dangerously 
by skipping the write-verify operation that normally follows every 
write to disk.  This will make \vault\ run considerably faster 
but with a risk of unreadable backup data not being discovered 
until it is needed.  To disable write verification, uncheck the 
`Write Verify' menu item under Options.  We recommend that you 
always use write verify.

\subsubsection{The History File}

\vault\ writes a history of all of its activity to a  file 
called \_BACKUP.CTL and places it on the hard disk in the root 
directory or folder being backed up.  It supplies \vault\ with 
the date and label information necessary to automate the 
incremental backup process.  In addition, a file called 
{\tt \_BACKUP.HST} provides the user with a helpful record of the files 
which have been backed up and a means of locating a specific file 
in the backup set.  One can search for a file name in the list of 
files and thereby find the disk and folder on which it has been 
backed up.

{\tt \_BACKUP.HST} contains a four-line header followed by a list of 
files.  The header contains the date of the most recent backup, 
the date of the last full backup, the last output folder used, and 
the last incremental disk used.  The list of files contains the 
full pathname of each file that has been backed up, the creation 
date of the original file, and the disk and folder numbers of the 
backup copy.  {\tt \_BACKUP.CTL} is the same, except that it does not 
list the files which were backed up.

Each time an incremental backup is done, the backup history 
is modified.  The current date, output folder, and incremental 
disk are written in the header, and the names of all files backed 
up are appended to the end of the list of files.

When a new full backup is performed, the old {\tt \_BACKUP.HST}
file is renamed to {\tt \_OBACKUP.HST} before the new {\tt \_BACKUP.HST}
file is written.  Thus, the old history is preserved in case the new
backup fails. 


\subsection{Using \vault\ as a Copy Utility}

Although \vault\ was designed for backing up your data, 
it's speed of writing and other features make it attractive for 
other kinds of copying jobs as well.  To allow it to be used this 
way, two additional menu selections, totally unrelated to backup 
up data, have been provided -- `Full Copy' and `Incremental Copy'. 
Full copy works just like `Full Backup', except that it does not 
check disk labels, ask for specific disks, split files or write a 
log file.  Incremental copy is similar except that it only copies 
files that were created or modified after a date and time that you 
specify.  The two Copy selections are useful for simply 
duplicating data.

The results of a Full Copy are different from the results of 
using the desktop to copy a whole disk:

\begin{itemize}
  \item A Full Copy copies only files, not blank sectors, so the 
 result is a disk with no fragmentation.

  \item It will work with any format disk compatible with GEMDOS, not 
 just with 9 sector floppies.

  \item It can copy from single sided disks to double and vice versa, 
 and from a hard disk to floppies.

  \item It can be used to copy from one source disk to a set of 
 floppy disks.

\end{itemize}

\subsubsection{Using Full Copy and Incremental Copy}

Full Copy and Incremental Copy are used just like the backup
selections with one important difference: in both cases you can select
a full pathname for the output folder name instead of just an
eight-letter name.  Thus, if you select {\tt FINANCES\verb|\|TAXES}
as the output folder, then that is exactly where the data will go on
the floppies, and {\tt .FUL} or {\tt .001} will not be appended. 


\subsubsection{Specific Suggestions for the Use of Full Copy}

\paragraph{Putting Together Floppies}

You can quickly make up a floppy disk for a friend with 
copies of files from all over your hard disk and floppy library.  
Make a temporary folder on your hard disk and copy all the files 
you want to it.  Now, use Full Copy to copy this folder to the 
floppy disk.  This is much faster and easier than copying each 
file individually to the floppy, especially if you have only one 
floppy drive.


\paragraph{Splitting Floppies}

If you have one double-sided floppy and want to copy it to 
two single-sided floppies, this can be done using a Full Copy and 
two floppy drives.  Do a full copy from the input disk to the 
output disk.  \vault\ will ask for as many floppies as needed.  
With one drive, it is a bit harder.  Copy the files to the 
hard disk and use Full Copy to copy them to the single-sided 
disks.


\paragraph{Optimizing disks}

\vault\ can be used to optimize disks, that is, to pack 
files together on consecutive sectors of the disk and to eliminate 
``holes".  Since the floppies it writes are fully optimized, use 
Full Copy to copy all files from one floppy to another.

To use \vault\ as a hard disk optimizer, first back up the 
hard disk, then zero it using the hard disk utilities that came 
with your disk, and then copy all the files back using \key\
(the restore program provided with \vault).  This method is 
more reliable than a special purpose hard disk optimizer.  If the 
power goes out while you are using a disk optimizer you will 
probably lose all the data on the drive.  It is therefore a good 
idea to back up your hard disk before you optimize!  But if you 
are going to back up anyway, you might as well clear the disk and 
restore it from the backup set.

You will probably find other uses for \vault.  In the 
meantime, happy backing!


\subsection{Cautions and Limitations}

TOS has a few shortcomings that can cause problems using \vault.

\begin{itemize}

\item Although the underbar character is legal in file names, its use
in file selector boxes and certain other dialog boxes can cause GEM to
hang.  When this happens, rebooting the machine is your only recourse.
(This bug was fixed in the summer 1987 version and later, including the
``Rainbow'' version, of TOS ROM's.)

\item Incremental backups compare the file date and time maintained by
GEMDOS with the current date and time when deciding whether to back up
the file or not.  Of course, this means that you must always set the
clock whenever you reboot the machine so that these times are always
correct.  Unfortunately, GEMDOS only sets the file date and time when
the file is first created, not when it is modified.  Most programs
such as wordprocessors actually create a new file and rename or delete
the old one when the user updates it.  In such cases the file
date/time do accurately reflect the most recent modification and there
is no problem.  However, certain programs such as some database
managers actually modify the old file rather than creating a new one,
so the date/time of those files continues to reflect the time of
original creation, not the time of last modification.  Such files will
{\em not} be backed up on the incremental backup, unless you have TOS
1.4 ROMs and use the `Use Archive Bit' option.  The solution to this
problem is to run the program {\tt TOUCH.TTP}, furnished on the
distribution disk, every time any such file has been modified or at
least before each incremental backup.  This program sets the date/time
of the named file to the current date/time.  To use, click on {\tt
TOUCH.TTP} and type the name of the file to touch in the parameter box
that will appear. 

\item \vault\ formats only regular nine or ten sector floppy disks.
It {\em can} read and write any disk format that TOS will read, such
as {\em Twister}.  If you want to use Twisted disks, format them
before using \vault. 

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\key: A file Restore Program}

\subsection{Introduction}

\key\ is a program that makes it easy to restore files backed up 
by \vault.  It is also a general purpose file copy utility.  It 
can copy single files, groups of files matching a wildcard 
pattern, whole folders, or whole backup sets (all folders, all 
subfolders, etc.).  It preserves the file's date and time, making 
it easier to identify the latest version of a file.  It provides 
several options for what to do when the file already exists in the 
output folder.  (By default, it only copies the file if it is 
newer than the one it replaces.)  Finally, \key\  can restore a 
long file that \vault\ has been forced to split across two or 
more disks.

\subsection{Using \key}

To run \key, double-click on KEY.PRG.  You will be greeted by a
dialog box giving you the options.

\subsubsection{Specifying the Input}

You must specify an file name, pattern, or folder to copy from.  
If you give a file name or a TOS wildcard pattern (a name with 
`*'s and `?'), all matching files will be copied, depending on the 
`Copy subfolders' switch.  For example, {\tt E:\verb|\|FOO} will copy all the 
files in {\tt E:\verb|\|} and its subfolders named {\tt FOO}.  If you give just a 
foldername, all the files in that folder and its subfolders will 
be copied.  Usually you will be restoring entire folders, in which 
case you only need to give the name of the folder to restore from.  
Be sure to start your name with the letter of the drive to copy 
from, for example {\tt A:} or {\tt B:}.

When restoring files backed up by \vault, you will need to 
decide which folders to restore from.  For example, if you just did a 
full backup to folder {\tt E}, then the root directory of the floppy 
will contain only one folder named {\tt E.FUL}, and all of the files 
and folders backed up will be contained in it.  To restore those 
files, you should type  {\tt A:\verb|\|E.FUL}  on the ``input" line.  If you are 
restoring from an incremental backup, there will be folders with 
names like {\tt E.001}, {\tt E.002}, etc.  This is because a new folder is 
created each time you run an incremental backup.  Typing {\tt A:\verb|\|E.002}
will restore those files saved during the second incremental 
backup.  If you are in doubt about which folder to restore from, 
look on the backup disk or in the backup history file 
{\tt \_BACKUP.HST}.

\subsubsection{Specifying the Output}

On the ``output" line, give the name of the folder where the files 
should be put.  This folder will be created automatically if it 
does not already exist.

For example, if you previously ran a full backup of files from {\tt
E:\verb|\|} to output folder {\tt E} and now wanted to restore them from a
disk in drive A, you would type {\tt A:\verb|\|E.FUL} on the input line
and {\tt E:\verb|\|} on the output line. 

For a more complicated example, if you wanted to restore files to {\tt
D:\verb|\|LETTERS} that had been backed up on the third incremental backup
after having previously done a full backup to output folder {\tt
DLETS}, then you would type {\tt A:\verb|\|DLETS.003} on the input line
and {\tt D:\verb|\|LETTERS} on the output line.  This sounds harder than
it really is, for if you just look on the backup disks, you will see
what folders are there to restore from.  Note that you do not have to
restore files to the same folder that they originally came from,
although you will usually want to. 


\subsubsection{The ``Copy Subfolders" Option}

\key\ normally copies from the selected folder and all of its
subfolders and all of their subfolders and so forth.  If the `Copy
Subfolders' box is unchecked, then \key\ copies only from the selected
folder.  This is useful if you want to copy one file.  For example, if
the input is {\tt E:\verb|\|FOO} and {\tt FOO} is a file in {\tt E:\verb|\|} ,
you must uncheck the `Copy subfolders' option to prevent files named
{\tt FOO} in subfolders of {\tt E:\verb|\|} to be copied.  The box should
normally be checked when restoring from backup disks. 


\subsubsection{Overwrite Modes}

Any copy program has a problem when the file about to be copied 
has the same name as a file already in the output folder.  Should 
the file in the output folder be replaced with the one being 
copied, or should the copy not take place?

\key\  gives you four options to tell it what you want it to do 
in such cases.  Select the desired option by checking the box next 
to it.

If you check the ``Always" box, \key\  will copy every file in 
your input folder and always replace existing files whenever name 
conflicts occur.

If you check the ``Only if different" box, \key\  compares every 
input file with the corresponding one in the output folder, and 
only copies those that differ.  The effect is the same as if you 
said ``Always", but this is much faster if only a few files 
actually differ.  For example, you might want to use this option 
if a few of the files on your hard disk have been damaged and you 
don't know which ones.

If you check the ``Only if older" box (the default), \key\   
compares the dates of the input and output files.  If the output 
file is older than the input, it copies, replacing the output file 
by the input; otherwise it leaves the output file alone.  The 
result is that whichever version is newer ends up in the output 
folder.  This is useful, for example, when you want to merge two 
folders with different versions of the same files.

If you check the ``Never" box, \key\  will never write over an 
existing file.  This of course is the safest in the sense that 
files are never destroyed, but it may leave you with old versions 
of files.


\subsubsection{Performing the Copy}

After you have selected the restore options, put the disk to be 
copied into the drive and click on the ``Copy" button.  \key\  
will copy all of the files according to the input specification 
and ask you to insert another disk.  It repeats this process on 
each disk you insert.  When \key\  is done with the entire backup 
set (or you do not wish to restore any more files), press `q' when 
it prompts you for another disk and you will return to the options 
box.

\subsubsection{Split Files}

Normally, disks can be restored in any order.  However, split files
present a special problem.  \vault\ is sometimes forced to split long
files across two or more backup disks.  When this occurs, it gives
each piece a special name.  For example, a long file {\tt
MAILLIST.DOC} might get split into three parts named {\tt
MAILLIST.A01}, {\tt MAILLIST.A02}, and {\tt MAILLIST.A03}.  The
original name of the file, {\tt MAILLIST.DOC}, is stored at the
beginning of each part along with other information. 

When \key\  encounters the first part of a split file, it creates
the output file (if the overwrite mode permits it) and copies the 
first part in.  It also remembers that an incomplete file exists.  
Subsequent parts are added on until the file is complete.  For 
this to work, {\em you must insert the disks in the same order that 
they were written}.  \key\  does not check for the correct disk, 
and if you put them in in the wrong order, the part will be 
restored as if it were an ordinary file and not added on to the 
big file to which it belongs.

If you ask to quit before all of the parts of a split file have 
been restored, \key\  will show you which files are still 
incomplete and ask if you really mean to stop.  If you press `y', 
you will return to the top-level, and the incomplete files will be 
left in the output folder.  You should usually delete them 
immediately so that you do not later get mixed up and think that 
they are good files.


\subsection{Good Strategies for Using \key\ }

To restore all files in the least time possible, use the ``Overwrite 
if older" option and restore your disks in backwards order:  
Restore the most recent incremental backup folder first, then the 
next most recent, etc. and ending with the oldest incremental 
folder.  Finally, restore the most recent full backup.

For example, if you have a full backup named {\tt E.FUL} and three
subsequent incrementals named {\tt E.001}, {\tt E.002} and {\tt
E.003}, restore the folder called {\tt E.003} first, then restore {\tt
E.002} and {\tt E.001}, and last, restore {\tt E.FUL}. 

By restoring the disks in reverse order, the first version of a 
file that \key\  encounters is the most recent one.  When it 
later comes to older versions, they are skipped since a newer 
version has already been restored.  If the disks were restored in 
the same order as they were created, then every version of each 
file except for the latest would be restored and then later erased 
as newer versiosn came along, and the latest would be restored 
last.  This would still produce a correct result but would be 
slower.


\subsection{Using \key\ from a Command Line}
 
\key\  can also be used as a {\tt TTP} program or from a shell.  It 
takes a command line argument of the following form:


\begin{verbatim}
{ {[-f <file>] [-di <fold>] [-do <fold>] [-<switch>]}
   <inmask> <outfold> }
\end{verbatim}

The items between curly brackets \{ ... \} may be repreated any 
number of times.  The items between square brackets [ ... ] are 
optional.  The arguments and switches are explained below.

\subsubsection{-f $\langle$ file$\rangle$ }

 This tells \key\  to read one or more lines of 
 arguments from a file.  This is useful for copying long 
 lists of files.  For example, suppose {\tt PROGFILE.CPY}
 contains the following lines:  

\begin{verbatim}
               -di a:\ -do d:\
               *.c =
               *.pas =
               w*.* =
               *.doc =
\end{verbatim}

 Then the argument `{\tt -f PROGFILE.CPY}' would cause \key\  
 to read and interpret each of the lines in that file.  
 In this example, the result would be to copy all the 
 files in a:\verb|\| ending with .c, .pas, and .doc or beginning 
 with w to d:\verb|\|.

\subsubsection{-di $\langle$ fold$\rangle$ }

This sets the default input folder to $\langle$ fold$\rangle$.  This folder is used to
find all input paths that do not explicitly specify a folder.  For
example, if you specify `{\tt -di e:\verb|\|r}', then the input path
`{\tt src\verb|\|myprog.c}' would refer to the file `{\tt
e:\verb|\|r\verb|\|src\verb|\|myprog.c}', but the name `{\tt
d:\verb|\|yourprog.c}' would still refer to drive d.  If the `{\tt
-di}' switch is not given, TOS's ``current working directory" is used
instead.  This is folder containing the file KEY.TTP unless you are
using a shell that lets you set the working directory to something
else. 

\subsubsection{-do $\langle$ fold$\rangle$ }
This sets the default output folder to $\langle$ fold$\rangle$ .  The 
default output folder works just like the default input 
folder except that it applies to the output path.

\subsubsection{-$\langle$ switch$\rangle$ }
 $\langle$ switch$\rangle$  can be one of the switches described below.  
 For example  `{\tt -od}' selects the `overwrite only if 
 different' option.  The meanings of the various 
 options are explained in greater detail elsewhere in 
 this manual.  If no switch in a group is given, the one 
 shown in upper case is used.

\begin{verbatim}
          Overwrite option: [ o | OO | od | no ]
               o:    overwrite on
               OO:   OVERWRITE ONLY IF OLDER
               od:   overwrite only if different
               no:   never overwrite

  Subfolders option:  [ SUB | nsub ]
               SUB:  COPY SUBFOLDERS
               nsub: copy files only, not subfolders
\end{verbatim}

\subsubsection{$\langle$ inmask$\rangle$ }
 This is a pattern that selects which files to copy from.  
 Suppose the default input folder is `{\tt e:\verb|\|r}'.  The 
 following examples illustrate how $\langle$ inmask$\rangle$  works:

\begin{itemize}

\item
{\tt `taxes'}: All files in the folder {\tt e:\verb|\|r\verb|\|taxes} {\em if taxes
is a folder}, or the single file {\tt e:\verb|\|r\verb|\|taxes} if taxes is a file.

\item
{\tt `*.doc'}: All files in {\tt e:\verb|\|r} that end with .doc.

\item
{\tt `.'}: All files in the default input folder (in this case, {\tt e:\verb|\|r})

\item
{\tt `*.*'}:  All files in the folder {\tt e:\verb|\|r} that match *.*.  (This
is the same as `.'.)

\item
{\tt `d:\verb|\|'}: All files in the folder {\tt d:\verb|\|}.

\item
{\tt `src\verb|\|*.c'}: All .c programs in the folder {\tt e:\verb|\|r\verb|\|src}.

\item
{\tt `c:\verb|\|bin'}: All files in the folder {\tt c:\verb|\|bin} (or the 
 single file {\tt c:\verb|\|bin} if it is a file 
 instead of a folder).

\item
{\tt `\verb|\|work.*'}: All files in {\tt e:\verb|\|} named `work' with any 
 extensions (since e: is the drive of the 
 default input folder).

\end{itemize}

 \subsubsection{$\langle$ outfold$\rangle$ }
 This is the directory to which the input files will be 
 copied.  Like the input folder, it is relative to the 
 default output.  If it is `.', then it specifies the 
 current default output folder.  (See the description of 
 the `{\tt -do}' switch.  Suppose that the default output 
 folder is set to {\tt e:\verb|\|m}.  The following are some examples 
 to show how {\tt $\langle$ outfold$\rangle$ } works:

\begin{verbatim}
   .      e:\m
   \r     e:\r
   docs   e:\m\docs
   \      e:\
   d:\    d:\
\end{verbatim}

Here are examples of command lines as you might type them to a 
shell.  (In some shells which expand wildcards, you may need to 
put them in quotes.)

\begin{verbatim}
key a:\ b:\                             Copy disk a:\ to disk b:\
key -di a:\noise -do b:\ *.* .          Copy folder a:\noise and 
                                          all subfolders to disk b:\
key -di a:\ -do b:\ e:\*.pas . *.c .    Copy e:\*.pas and a:\*.c to b:\
key -di a:\ *.c d:\test                 Copy a:\*.c to d:\test\
key -di d:\ -do h:\  . .                Copy d:\*.* to h:\
\end{verbatim}

\end{document}