; PRTTP
;---------------------------------------------------------------
;! prints contents of tapes, all supported formats
;# Task Tape
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1999, 2002-2004, 2008
;;  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
;-----------------------------------------------------------------------
PRTTP     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
PRTTP:   Task to print contents of tapes (UV data, maps, ...)
INTAPE          0.0         9.0    Tape unit # (0=> 1)
NFILES          0.0     32000.0    # files to advance from
                                   beginning of tape.  >10000 ->
                                   start where tape is now
DATAIN
                                   Disk file name (FITS and
                                   VLA archive only)
PRTLEV         -4.0         2.0    Amount of print
                                      ( 2 -> a lot)
                                      ( 0 -> summaries)
                                      (-1 -> brief print)
                                      (-2 -> terse print)
                                      (-3 -> table of files)
                                      (-4 -> table of files,
                                             skip tape read)
DOCRT          -3.0       132.0    > 0 => print on CRT, else
                                      use line printer
                                   > 72 => terminal width
OUTPRINT
                                   Printer disk file to save
                                   required for PRTLEV = -3,-4
STRC3                              Name of tape
BCOUNT                             File number at start (only
                                   when NFILES > 10000)
DOEOT           -1.0     1000.0    >0 => there are null files on
                                   the tape before the EOT
NPIECE           0.0       90.0    Maximum disk-file piece # to
                                   list from uv-tables files
ERROR            -1.0       3.0    >= 2 -> do not use AIPS
                                   history in the FITS file
----------------------------------------------------------------
PRTTP
Type:  Task  (interactive only)
Use:   To print on the line printer or terminal a fairly detailed
       summary of the contents of a tape or pseudo-tape disk file.  The
       program begins by rewinding the tape and then advances the tape
       by the user specified number of files.  PRTTP then reports on the
       contents of all files until an end-of-information mark is found.
       The tape is finally positioned to allow writing beginning at the
       previous end-of-information.  The task can recognize the FITS
       formats (map, UV groups and tables, VLBA), the IBM map format,
       the VLA UV-data export format, and VLA archive format tapes (post
       Jan. 1988).  PRTTP will also report the lengths of records in
       files of other types.
       PRTTP (and IMLOD, UVLOD, FITLD, TPHEAD) now understand and
       interpret the standard world coordinate system keywords CDi_j
       and PCi_j.  They are used if possible and problems reported.
Adverbs:
  INTAPE......Input tape drive number.  0 => 1.
  NFILES......Number of files to advance from the beginning of the tape.
              <= 0 => 0.  To have the program begin at the current tape
              position, give NFILES any number > 10000.  The relative
              file numbers (n) will appear on the print as 10000+n.
  DATAIN......48-character name of the disk file from which to read a
              FITS are vLA archive file.  ' ' => use magnetic tape
              INTAPE.  DATAIN 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> only works for FITS files and is usually omitted
              when the file is local to the current computer.  If the
              DATAIN file is missing, the task will, for FITS files
              only, try finding the file with the character "1"
              appended.
              For VLA archive files, the actual file names must end in
              a number representing the "file number" of the "tape".
              DATAIN (as with FILLM) MUST be the file name WITHOUT THE
              FILE NUMBER.  See EXPLAIN for more details.
              To use the VLA archive directly, contact NRAO at
                  analysts@nrao.edu.
              The web has tools to review the contents of the archive
                  http://www.vla.nrao.edu/astro/archive/vladb/
              and to request data from the archive
                  http://www.vla.nrao.edu/astro/archive/archreq/
  PRTLEV......Amount of print desired (affects most formats):
              -4 => one line/file table output, not printed.  Use
                    advance file to skip large files rather than reading
                    every record.
              -3 => one line/file table output, not printed
              -2 => extremely terse output,
              -1 => limited information,
              0 => summaries in IMHEADER form,
              1 => add non-History cards,
              2 => add History cards too.
  DOCRT.......False (<= 0) use the line printer if OUTPRINT = ' '
                   else write named OUTPRINT file only.
                   When OUTPRINT is not blank, DOCRT=-2 suppresses the
                   page-feed character on page headers and DOCRT=-3
                   suppresses page headers and some other header
                   information.
              True  (> 0) use the terminal interactively.  The task will
                   use the actual terminal width as a display limit
                   unless 72 < DOCRT < width.  In that case, the display
                   limit will be DOCRT characters.
  OUTPRINT....Disk file name in which to save the line printer output.
              ' ' => use scratch and print immediately for interactive
              jobs - batch jobs use OUTPRINT = 'PRTFIL:BATCHjjj.nnn'
              (jjj= job #, nnn = user #).  When OUTPRINT is not blank,
              multiple outputs are concatenated, and the file is not
              actually printed.  Required if PRTLEV = -4 or -3.
  STRC3.......12-character string to give name of tape.  Used for tapes
              only and just for display purposes.
  BCOUNT......File number of first file displayed.  This is used only
              for magnetic tape and when PRTTP is told to start at the
              current position.   0 => 10001.
  DOEOT.......Normally, PRTTP stops the first time that it finds a null
              file assuming that it is at the end of information.  If
              you know that there are null files on the tape before the
              real end of information, set DOEOT = maximum number of
              consecutive null files that might occur.  Used only with
              magnetic tape.
  NPIECE......is the highest piece number of uv-table pieces to be read
              from disk.  It is ignored for tape reading and for images
              and old-fashioned random-groups data files.
  ERROR......>= 2 => do not parse AIPS history cards found in the FITS
             header.  Do not use this option until you have tried PRTTP
             without it.  If you get mysterious errors (usually error 4
             which implies premature end of file), then try PRTTP with
             ERROR set to 2.  For a period of time, data sets written
             out with FITAB, read back in, and then written out with
             FITTP could have so many AIPS history records in their
             header as to cause PRTTP (and UVLOD) to read the data
             wrongly.
----------------------------------------------------------------


DATAIN           (for VLA archive data)
     It is now (as of 2002-07-22 in FILLM and 2002-12-06 in PRTTP)
possible to read the VLA archive format data from disk files instead
of magnetic tape.  All files to be read in a single run of FILLM must
reside in the same disk directory and have the same name except for
the last character or characters (no leading zeros) which define the
file number.  Thus, you could copy tape files with dd to disk and then
read them with FILLM or you could ftp them from some archive to your
local disk and then read them.  Note that remote tape does not work
for FILLM (from disk).  The analysts at the AOC in Socorro will have
access to a disk archive and can prepare data files suitable for
loading with FILLM for you to download via anonymous ftp.  For
example, when I ask them to find the data for program AB1024, they
find that tape XH02045 data files 1 through 10 contain some of my
data.  I then copy those files to a disk directory which I call
          $VLADATA/AB1024
using file names file_1, file_2, ... File_10.  Then in FILLM I set
          DATAIN='VLADATA:AB1024/file_
          NFILES = 0; NCOUNT=10
to read all of these files.  Note that I put the DATAIN= command last
on its line and did not follow it with a close quite (').  This allows
the lower case letters to be retained.

