Trailing-Edge - PDP-10 Archives - decuslib20-06 - decus/20-156/tapsav.rnd
There are no other files named tapsav.rnd in the archive.
.title     TAPSAV - A file storage utility for magnetic tapes
.c;TAPSAV - A file storage utility for magnetic tapes
.c;August, 1983
.s1.c;Written by:
.s1.c;Douglas Bigelow
.c;Wesleyan Computing Center
.c;Wesleyan University
.c;Middletown, CT  06457
.hl 1 Introduction
        TAPSAV is a magnetic tape manipulation program which allows the quick
and convenient storage of disk files on tape.  When you have many files to
store and either don't need them on disk or don't have room for them, TAPSAV
will let you put them onto a private tape and retrieve them whenever you wish.
TAPSAV was designed to avoid the problems associated with standard DEC tape
utilities, which aren't designed for small scale, single user tape work.
        TAPSAV provides the following features:
.ls "o"
.le;A tape directory maintained solely on disk, which allows the following
actions to be performed without accessing the tape:
.ls "o"
.le;Deletion of files.
.le;Un-deletion of files.
.le;Quick and complete wild-card searches of the tape contents.
.le;Modification of the tape title.
.le;Adding files to the tape and automatically deleting old copies.
.le;Rebuilding the directory from scratch if the disk copy is lost.
.le;Saveset structure to allow restoration of classes of files.
.le;Files on tape are not directory-specific, and may be saved or
restored to or from anywhere.
.hl 1 TAPSAV operating environment
        TAPSAV makes the following assumptions when it is started:
    Tape directories are to be read and written from logical device
TSDIR:, which should be defined as a directory.  A LOGIN.CMD or
COMAND.CMD file is a logical place for this.  If TAPSAV is unable to find
a device TSDIR:, you will be warned that you need to add a line like the
following to your LOGIN.CMD file:
        All tape directories will be stored as files in this area, and will
be of the form VOLID.TAPEDIR, where VOLID is the volume identifier of your
tape.  An example of a tape directory file would be, using the above TSDIR:
        Tape directory files are
never saved onto a TAPSAV tape.
    Tapes are mounted with the logical name TS:.  If TAPSAV finds such a
device upon startup, it prints out the tape volume name and identifying
banner.  If
your tape has been mounted with some other name, you must tell TAPSAV
what device name has been used with the TAPE command (below).
        An example of a mount command for a TAPSAV tape might be:
    If not specified, the default directory for saving and restoring files
is the user's connected directory.
.hl 1 TAPSAV commands
        The following is a list of TAPSAV commands and their actions:
.ls "o"
.le;CREATE (a new TAPSAV tape)
.br;This command creates a directory for the tape you have mounted as
device TS:.  If a directory already exists for this tape, you will be warned
that the CREATE command will wipe out the old tape contents, and be given
a chance to change your mind.  The CREATE command must always be done for
a new tape, or when rebuilding a tape from scratch.
.le;DELETE (specified file(s) from tape)
.br;This command sets deleted status
for a specified group of files.  For information on how the files are
specified, please see the following section.
.le;DIRECTORY (of tape to file)
FILESPEC (for wildcard files) WILDSPEC
.br;Creates a directory listing in the
file specified.  If no filespec is given, the directory is printed on the
terminal.  Usual mode of use is DIR<cr> or DIR DSK:TAPE.DIR<cr>.
     For information on partial
directories of special types of files only, please see section 3.4.
.le;EXIT (from TAPSAV)
.br;Returns you to EXEC command level, leaving TAPSAV.
.le;FAKETAPE (tape id:) VOLID
.br;This command is used to fool the program into thinking a certain tape
is mounted, so that you can check out directories without having to mount
the tape.  VOLID is the volume identifier of the tape.
.le;LIST (filenames on save or restore)
.br;Causes the program to tell you what file transfers are in progress.
This is the default mode.
.le;HELP (with program commands)
.br;Gives a short summary of commands.
.le;NOLIST (of filenames on save or restore)
.br;Causes the program to omit listing files on a save or restore.
.le;REBUILD (the tape directory)
.br;Rebuilds the tape directory from scratch if it has been damaged or
.le;RESTORE (specified file(s) to disk area:) DIRECTORY
.br;Restores a list of files from tape to the specifed place.  If no
directory is specified, files are sent to user's connected directory.
.le;SAVE (specified files into saveset:) SAVESET NAME
.br;Saves a group of files on tape, putting them all into the same saveset.
If not specified, the saveset name used is GENERAL.  Maximum length name
is fifteen characters.
.le;SDIRECT (of tape to file) FILESPEC
.br;Like the DIRECTORY command, except that it includes deleted files in
the listing.
.le;SUPERSEDE (files on tape when:)
.br;The subcommands which follow specify when files on tape should be
superseded by files on disk with the same filenames:
.ls "o"
.le;Across - supersede files across saveset boundries.
.le;Always - always supersede tape files.
.le;Never - never supersede tape files.
.le;Older - supersede tape files when older than disk files. (This is
the default)
.le;TAPE (device name) NAME:
.br;Specifies what device name is used for the magtape drive.  TAPSAV will
create the logical name TS: and assign it to that drive.  This command is
not needed if you mount the tape as TS: in the first place.
.le;TITLE (for the tape)
.br;Gives you the opportunity to change the tape title, an 80-character
string used to identify the tape in any manner you choose.
.le;UNDELETE (specified file(s) from tape)
.br;Removes the deleted status from a group of files.
.hl 2 Specifying groups of files on a DELETE, RESTORE or UNDELETE
        Following one of the commands above, you will enter the file
specification mode, where the prompt changes from TAPSAV-- to File--.
This indicates that you may type a file specification, which may be a
single file or a wildcard specification which may cover a whole group of
files.  One separate file specification is allowed per line, and the
File-- prompt is repeated until you signify end of list with a (CR).
        Files may also be selected by their numbers from a directory listing.
A single number or a number range (6:10) may be typed in place of a filename.
        Following each specification, the program will indicate how many
files in the directory matched by typing out [ "n" found], where "n" is
a number.  Here is an example:
                        [1 found]
                        [0 found]
                        [16 found]
                        [5 found]
                [ Starting transfer to disk... ]
        Recognition is not available on these files.  The same files may be
selected by different commands due to wildcard overlap, but each file will
be restored once.
        In case you mistakenly specified too many files or the wrong 
files, there are two ways to abort a restore after you have started it.
The first is to type _^C.  This will abort the program and you must start
again from scratch.  The second is to type _^E.  This will temporarily 
stop the restore.  You must then specify one of four options.  The _^E
abort and its options are discussed later in section 3.5.
.hl 2 Specifying groups of files on a SAVE
        Following a SAVE command, you will again get the File-- prompt, but
it will work a bit differently.  Since you are now specifying files on disk
rather than in the tape directory, recognition is available to complete file
names.  If any particular file or file group is not valid for some reason,
you are notified with an error message and the file is ignored, but you are
still in file listing mode.  When saving, you are not notified of the number
of matches, since it could be a potentially very large number.
(EG File--PS:<*>*.*.*)
        When a file is saved, other versions of the file on tape are
automatically deleted.  The generation number of a file is not preserved
on tape, so when a file is restored it automatically takes the first
appropriate generation number for a particular directory.
        When working with a large number of files, you should be aware that
if the end of tape reflector is encountered on a save, the monitor will
automatically cause the next tape volume to be mounted and will continue the
save on the next tape.  This is OK if you have specified multiple volumes
in your mount request, but if you have not the monitor will request a
"SCRATCH" tape to be mounted.
        Your job will freeze until the operator asks
you what tape to use for the continuation.  In most cases you will wish to
use _^C to abort your job, and you will have safely saved all of the files
that had an [OK] after them when they were listed during transfer.  You may
then dismount your tape, and put any remaining files onto a new tape.  This
is generally more convenient then continuing onto a second tape.
Unfortunately, it is not possible for the program to warn you automatically
when the tape end is encountered, so operator intervention is generally
.hl 2 Retrieving files by saveset name
        Saveset names are maintained on the tape as 1-15 character strings.
If you wish to retrieve a specified type of file from only one saveset, and
ignore the file type in other savesets, you can use the /Saveset: switch
at the end of the filespec given to the File-- prompt.  When no saveset name
is given, all are searched.  Here are some examples:
                [ 6 found ]
                [ 12 found]
        The first command will retrieve all .MAC files found in the SOURCES
saveset, and ignore all others.  The second will retrieve all files in the
DATA-FILES saveset.
.hl 2 Partial directories
        By using the full format of the directory command, you may get a
directory of only specific files on a tape.  The command is:
        DIRECTORY (of tape to file) TTY: (of wildcard files) *.PAS
        In the above example, only files of type .PAS would be listed in the
directory to the terminal.  Any wildcard formation may be used (ALPHA.*,
*.Q??, *.*).  A saveset name may also be tacked on to restrict files to that
saveset only, for example *.MAC/SAVESET:Alpha.  This would list only the
*.MAC files in the Alpha saveset and ignore all others.
        As with the normal directory command, you may route the output listing
to a file by substituting the name in place of the default TTY: field.
.hl 2 Interrupt commands
        The following control characters may be used to interrupt TAPSAV
while it is processing a tape:
.le;_^A -- Print filename of last file seen while tape positioning is in
progress.  May be used during a save or restore to list the last file seen.
This is usually useful only when in NOLIST mode.
.le;_^E -- Interrupt a SAVE or RESTORE to accept a further command.  
This command may be used to change between LIST and NOLIST mode 
while running.  The _^E interrupt may also be used to ABORT
the present restore operation, and to RESUME the restore as if no
interrupt command had been typed.
.hl 1 Speeding up tape usage
        There are several ways in which you may use TAPSAV efficiently.
First, it pays to keep tapes down to a managable size.  Rather than fill up
a tape, you should use several different tapes to keep each one half filled
or less.
        As you keep using a tape, you are likely to save newer versions of
files, replacing the older ones.  Any files superseded in this manner remain
on the tape, taking up space with DELETED status set.  Thus each successive
save and restore takes longer, as more and more tape must be passed over on
the way to the current end of the tape.
        In some cases, you may wish to retain your deleted files, as a way
of archiving old program versions.  If you wish to discard deleted files,
however, you may follow this procedure:
.le;Get a SDIRECT (super-directory) listing of the tape to examine all deleted
.le;UNDELETE any files that you wish to retain.
.le;RESTORE files *.* to a disk area, preferably empty.
.le;CREATE the tape again.  Reply YES when TAPSAV asks if you really wish
to overwrite the old directory.  This leaves you with a logically empty tape.
.le;SAVE files *.* from the area you dumped them into.
        This procedure effectively removes all deleted files from the tape,
leaving only active files.  To determine if this procedure is necessary, you
can get a DIRECTORY of the tape and look at the total number of pages at the
bottom.  Then do an SDIRECT command and look at the total number of pages
including the deleted files.  If the second number is much greater than the
first, you probably wish to rebuild the tape.
.hl 1 Implementation details
        All tape I/O in TAPSAV is done in buffered mode.  While somewhat
slower than asyncronous dump mode I/O, it is simpler to use and error
correction is easier.  The tape format was designed to be as simple as
possible, to facilitate restoration of files if the tape becomes damaged
and a software specialist has to tackle it by hand.  All tape records are
14 pages long for efficient tape packing,
and each file occupies one file on tape.
The first 40 words of the first record of each file contains the file
header information, which is what TAPSAV uses to reconstruct the tape if the
directory is damaged.  The number of the file in the directory is the position
of the file on the tape, there is no header file on the tape itself.
        TAPSAV checks the file creation date when in "supersede older" mode.
When a file is restored from tape to disk, the creation and last write dates
are set to reflect their values when the file was saved.
.c;[End of TAPSAV.DOC]