; TCOPY
;---------------------------------------------------------------
;! Tape to tape copy with some disk FITS support
;# TASK TAPE UTILITY FITS
;-----------------------------------------------------------------------
;;  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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
TCOPY     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
TCOPY:  Task to copy the contents of one tape to another
INTAPE            0.0       9.0    Tape drive # (0 => 1)
NFILES        -9999.0    9999.0    # of files to advance on tape
NCOUNT            0.0  999999.0    # of files to copy 0=>all
INFILE
                                   if nonblank = FITS disk file
OUTTAPE         0.0         9.0    Tape drive #.  0 => 2
DOEOT          -1.0         1.0    1 (T) go to end tape first.
OUTFILE
                                   if nonblank = FITS disk file
----------------------------------------------------------------
TCOPY
Type:  Task
Use:   Copy the contents of one tape to another.  Tape files are
       arbitrary subject to an upper limit on the block size.
       1. Disk files may be used only for FITS format data.
       2. There is a maximum block size of 32764 bytes.
       3. FITS files copied from disk to tape will have a
          blocking factor of 1.
       4. TCOPY may be used to insert missing end-of-file marks
          between FITS-format data sets.
       5. The input tape is NOT repositioned if NFILES = 0.
          Most AIPS tasks interpret 0 to mean position at the
          beginning of the current file.  (Use the verb AVFILE
          to move the tape if you need this function.)
Adverbs:
  INTAPE.....Tape drive #.   0 => 1
             Ignored if INFILE is nonblank
  NFILES.....# of files to skip on tape before reading data.  If
             0, the tape is not repositioned.  If < 0, it is
             backed up to previous files; if > 0, it is advanced
             to following files from the tape position at the
             start of the program.
             Ignored if INFILE is nonblank
  NCOUNT.....The number of files to copy.  0=>all
             1 if either INFILE or OUTFILE is nonblank
  INFILE.....Input FITS disk file name.  Set to blank (' ') if
             tape.  The name is limited to 48 characters and
             must be in the form
                    <logical>:<file name>
             or
                    <node>::<logical>:<file name>
             where <node> is the remote computer name, <logical>
             is the environment variable (logical name) for the
             disk area in which the file named <file name> is
             stored.  <node> is usually omitted when the file is
             local to the current computer.
  OUTTAPE....The output tape unit #.  0=> 2
             Ignored if OUTFILE is nonblank
  DOEOT......True (> 0) means to advance OUTTAPE to the end
             of information before writing, false means write
             wherever the tape is now positioned.
             Note: set DOEOT true ONLY if you think that there
             are already data files on the tape AND if
             you wish to preserve them.
             Ignored if OUTFILE is nonblank
  OUTFILE....The name of a FITS disk file into which to write.
             If blank then write to tape.  If output is to a
             disk file, only 1 file can be written.
             The name is limited to 48-characters and must be
             in the form
                  <logical>:<file name>
              or
                  <node>::<logical>:<file name>
              where <node> is the remote computer name,
              <logical> is the environment variable (logical
              name) for the disk area in which the file named
              <file name> is to be stored.  <node> is usually
              omitted when the file is local to the current
              computer.
----------------------------------------------------------------
TCOPY: Task to copy selected files from one tape to another
DOCUMENTOR: W. D. Cotton, NRAO
RELATED PROGRAMS: PRTTP, FITTP, UVLOD, FITLOD, IMLOD

   This task was designed to facilitate copying an arbitrary set
of files from one one tape to another.  In particular, it is
designed to copy many input tapes to a single output tapes, an
operation apparently not considered by the writers of standard
file copying utilities.  The output tape should have an
appropriate end-of-information for the type of medium and there
should be no embedded double end-of-file marks as occurs with
the unix utility tcopy.  There is no reblocking of the files
copied.

   The tape to tape copy is limited only by the limited block
size of the AIPS I/O system to tape blocks of 32764 bytes or
less.  Otherwise, arbitrary files can be copied.

   Positioning of the tapes is relatively simple.  The input
tape is not moved before the copy begins unless NFILES is
nonzero.  In this case the tape is advanced (or backed) over the
specified number of end-of-file marks leaving the tape
positioned after the file mark.  Likewise, the output tape is
not repositioned unless DOEOT is true.  In this case the tape is
repositionned after the end-of-file mark following the last file
on the tape.  A tape error on either the input or output will
cause TCOPY to attempt to write an end-of-information on the
output tape and quit.  There is no repositioning of either tape
when TCOPY quits (either normally or abnormally).

   There is limited support for disk resident files.  These are
limited by the AIPS I/O system to FITS format (2880 byte blocks)
files. A copy of a disk file to tape will result in 2880 byte
blocks (blocking factor = 1) on the output tape.

   A possible error in writing FITS tapes - which occurred in
AIPS once for a few weeks - is the omission of the end-of-file
mark between FITS data files.  TCOPY looks for the "signature"
40 bytes that starts a FITS file (SIMPLE = T) and inserts an EOF
in the output stream.  Note that this only works when writing
actual magnetic tapes; it does not work when OUTFILE is not
blank.  If you have only one tape drive and have this problem,
copy your full tape file to disk with the Unix utility "dd".
Set INFILE to this disk file and copy back to (real) tape.
----------------------------------------------------------------
