; ARESTORE
;---------------------------------------------------------------
;! Restores back up tapes of users data
;# Obsolete Catalog
;-----------------------------------------------------------------------
;;  Copyright (C) 1995
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
;---------------------------------------------------------------
ARESTORE  LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
----------------------------------------------------------------
ARESTORE
Type: Stand alone command procedure.

Use:  This procedure is used to restore AIPS data file from
      tapes that were backed up with ABACKUP.  The procedure
      can be used only on a VAX/VMS system.  The restore
      process will not merge data sets.  This means that
      the disk to be restored can not contain any data for
      the given user.  This procedure replaces the older and
      less flexible RESAIPS.

Operation:
      The user should begin by exiting AIPS with an EXIT or QE
      command to get to the DCL level (the $ prompt level).
      Then, the user puts a tape on a drive, and puts the drive
      on line.  Next the user starts the procedure by typing
      ARESTORE .  NOTE: THAT YOU NO LONGER TYPE "@ARESTORE".
      The procedure will display a series of self
      explanatory (?) prompts that will lead the user through
      the backup procedure.  A detailed explanation of the
      prompts are available with the AIPS EXPLAIN verb.
----------------------------------------------------------------
ARESTORE: VAX/VMS stand alone command procedure to backup data.
DOCUMENTOR: G. A. Fickling  NRAO/CV
RELATED PROGRAMS: ABACKUP

                           PURPOSE

ARESTORE provides AIPS users on the VAX under the VMS
operating system an easy way to use the BACKUP utility to
restore to disk AIPS files that were backed up on tape with
ABACKUP.  The BACKUP utility does not attempt to write the
tape in ways that can be read by other computers, so BACKUP
ignores things that AIPS has to worry about such as byte
swapping and specifying floating point values in a general way.
This allows BACKUP to be much faster and to write the tape in
a more compact form.  ABACKUP backs up all files, including plot
files, slice files, etc. that AIPS can not yet handle.  BACKUP
also has some very sophisticated error checking and error
handling features.

                        RUNNING ARESTORE

   First, get to the DCL level ($ prompt level) by doing a QE
or EXIT from AIPS.  Make sure your tape is physically mounted
and on line.  The most convenient way to mount the tape is
to allow ABACKUP to do it for you.  You can also mount the tape
external to the procedure with then DCL command

$ MOUNT /FOR tape_drive_device_name  DUMMY TAPE

   Next run the procedure by typing

$ ARESTORE

The following text will show the prompts generated by the
procedure and provide some additional explanation.  The
prompts will be printed in this text in all capital letters to
help distinguish them from the accompanying comments.

ENTER THE AIPS TAPE DRIVE NUMBER

This is the same number used inside of AIPS for INTAPE.
After you enter a drive number you will get a mount message,
or an error message.  An error will cause the "drive number"
question to be repeated.  If things get really fouled up,
you may have to do a "CTRL Y" and start over.  The next
prompt is

DO YOU WANT A (SLOW) INDEX OF DATA SETS ON TAPE? (Y OR N)

The (SLOW) is a warning that the procedure must read through
all of the data on tape to produce an index or directory.  This
can take 10 minutes to an hour depending on the amount of data
on tape and the current load on the machine.  If you answer "Y"
then the procedure will type an index.  The tape must be mounted
as a labeled tape to produce the index,  so the procedure will
do a dismount and mount before and after printing. The index
will look  something like the one below:

DIRECTORY __MTA0:[]

DSK1V1.221;1           25        2-MAY-1984 00:00
DSK2V1.221;1          138        2-MAY-1984 00:00
DSK3V1.221;1            2        2-MAY-1984 00:00
DSK2V1.221;1          138        9-MAY-1984 00:00

TOTAL OF 4 FILES, 303 BLOCKS.

The index is a directory of "data sets".  All data on
one disk is stored in a data set.  A data set name is
in the form DSKnVi.hhh where "n" is the AIPS disk number and
"i" is usually 1 unless more than one tape is needed for a
disk, and hhh is the AIPS user number in hexadecimal. In the
example above, user number 545 has his data for May 2 on the
first three AIPS disks stored in the first three data sets.
The forth data set (note the duplicate name) is user 545's
data on disk 2 for May 9.  If the user in this example wants
to restore the May 9 data, he must skip over the data for disk
2 on May 2nd, i.e. he must skip at least 2 and at most 3 data
sets.  ARESTORE will find the data set for the correct disk as
long as a duplicate data set name is not between the current
tape position and the correct data set.  This brings us to the
following prompt:

ENTER THE NUMBER OF DATA SETS TO SKIP (IF YOU DO NOT HAVE SAVE
SETS ON TAPE WITH DUPLICATE NAMES THEN YOU CAN ENTER ZERO)
ENTER

The next prompt is

ENTER USER NUMBER

Enter the user number you use when starting up AIPS.

The next prompt allows you to restore one disk or all disks.

ENTER AIPS DISK NUMBER (ZERO IMPLIES ALL DISKS)

An entry of "0" will cause ARESTORE to look for AIPS disks 1
through the maximum number of AIPS disks IN ORDER.  A missing
save set will cause the tape to go to the end of tape looking
for that save set and then stop.  Consequently, nothing after
the missing save set gets restored.  The procedure quits after
finding the save set for the last disk even if more save sets
are on tape.  For user 545 in our example, if the tape was at
the beginning of tape, a "0" entry would restore the three data
sets for May 2.  The May 9 data set would not be restored.

At this point the files are restored from tape.  The final
prompt is

DO YOU WANT TO RESTORE ANOTHER DISK FROM THE SAME TAPE (Y OR N)

If you enter "Y" then the procedure again asks for a disk number
and proceeds from that point.  An answer of "N" will dismount
the tape and exit the procedure.
