; IMLOD
;---------------------------------------------------------------
;! Reads tape or disk files to load images to disk
;# TASK TAPE FITS IMAGE-UTIL
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1998-1999, 2002-2003, 2008-2009, 2020
;;  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
;-----------------------------------------------------------------------
IMLOD     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
IMLOD:  Task to store an image from a FITS or IBM-CV data file
INTAPE            0.0       9.0    Input tape drive # (0 => 1)
OUTNAME                            Image name (name)
OUTCLASS                           Image name (class)
OUTSEQ           -1.0    9999.0    Image name (seq. #)
                                      0 => highest unique number
                                     -1 => FITS tape value
OUTDISK           0.0       9.0    Disk drive # (0 => any)
NCOUNT            0.0     999.0    Number of files to load.
DOTABLE          -1.0       1.0    True (1.0) means load tables
NFILES        -9999.0    9999.0    # of files to advance on tape
NMAPS             0.0     999.0    # IBM maps to advance on tape
DATAIN                             Disk file name (FITS only)
ERROR            -1.0       3.0    >= 2 -> do not use AIPS
                                   history in the FITS file
----------------------------------------------------------------
IMLOD
Type: Task
Use:  IMLOD loads a map from tape or disk to an AIPS catalog disk.  The
      format may be the "IBM" map format or the FITS format.  The task
      converts the file map header into the standard form and stores the
      header in the header file.  The map array is then stored in a
      separate disk file in the same catalog location.  The tape is
      positioned after the End-of-file mark for FITS tapes or after the
      last row for IBM tapes.  Thus, for the latter an EOF may be the
      next record.  If any TABLES data are found on a FITS tape or disk
      file, they may be converted to additional extension files of the
      image.  This applies to Clean Components and other AIPS table
      files written by FITTP or FITAB and to some general tables written
      by other systems.  If IMAGE extensions are present, they are
      written to separate catalog entries, but all TABLES are attached
      to the primary catalog entry.

      IMLOD (and PRTTP, 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......The input tape drive #.  0 => 1.
  OUTNAME.....The output image name (name).  Standard behavior
              with default = the original map file name (FITS),
              the source name, or 'NONE'.
  OUTCLASS....The output image name (class).  Standard behavior
              with default = the original map class (FITS) or a
              class of the form 'STYP  ', where S = (I, Q, U, V)
              Stokes parameter of the image and TYP = (BEM, CLN,
              MAP) for a beam, clean map, or anything else.
              Special combination images (OPTD et al.) are also
              recognized.
  OUTSEQ......The output image name (seq #).  0 => Find the
              lowest number which produces a unique mapname.
              -1 => use the sequence number on the tape (if
              any - works only on tapes written by FITTP).
  OUTDISK.....The disk drive #.  0 => highest with space
  NCOUNT......The number of consecutive files to load from tape.
  DOTABLE.....True (1.0) means load all tables. (FITS only).
  NFILES......# of files to skip on tape before reading data
              1 => start of next file, -1 => start of previous
              file.  0 => not tape movement before read.  Use
              the AIPS verb AVFILE if needed to position at the
              start of the current (or other) file plus TPHEAD
              to make sure you are at the right place.
  NMAPS.......For IBM map format there can be more than map in a
              single tape file.  IMLOD first positions at the
              start of the requested file (with NFILES), then
              advances NMAPS into the file (for IBM format
              only).
  DATAIN......48-character name of the disk file from which to
              read a FITS file.  It 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.
  ERROR......>= 2 => do not parse AIPS history cards found in the FITS
             header.  Do not use this option until you have tried IMLOD
             without it.  If you get mysterious errors (usually error 4
             which implies premature end of file), then try IMLOD with
             ERROR set to 2.  For a period of time, UV data sets written
             out with FITAB, read back in, processed, and then written
             out with FITTP could have so many AIPS history records in
             their header as to cause IMLOD to read the data wrongly.
----------------------------------------------------------------
IMLOD:  Task to store an image from a FITS or IBM-CV tape
Documentor: E.B.Fomalont
Related Programs: PRTTP, FITTP, AVTP, MOUNT, DISMOUNT

                        PURPOSE

     IMLOD is the task used to read images from tape or disk to disk in
the format used by AIPS.  There are two formats recognized by AIPS are
FITS format and IBM-map format.  FITS format is the most general and
images can be written on tape or disk in this format from many
institutions.  The IBM-map format is an old format which is compatible
with an old tape format used in Charlottesville. IMLOD is able to
distinguish between these two formats.
     FITTP and FITAB are the AIPS tasks which generate a FITS tape or
file from an image on disk.
     In FITS, each image is contained in a separate file.  For
spectral-line work the image may consist of many planes.  More than one
image can be loaded with one execution of IMLOD if they are in
consecutive files on the tape.  Certain extension files may be
associated with an image.  At the present time general tables files and
clean-components files written by FITTP will be read into AIPS using
IMLOD.
     FITS format files can be read from a disk file on one of
the AIPS disks.  This uses the adverb DATAIN.

                          COMMENTS

OUTNAME, OUTCLASS, OUTSEQ, OUTDISK
     If OUTNAME is unspecified, the following will be taken:
          Original outname used when writing image
          Source name
           'NONE'
     If OUTCLASS is unspecified, the following will be taken:
          Original outclass used when writing image
          Class of form 'STYP' where S is the Stokes parameter
             and TYP is the type of image
          'IMAP'
     If OUTSEQ = 0
          Lowest available sequence number for the specified
             OUTNAME and OUTCLASS and OUTDISK
     If OUTSEQ = -1
          Original outseq used when writing image
          Lowest available sequence number for the specified
             OUTNAME and OUTCLASS and OUTDISK.

NCOUNT
    Number of consecutive files to load.  If NCOUNT is zero then
    one file will be loaded.

DOTABLES
    If DOTABLES is false (-1) then table files such as CC files
    will not be loaded from tape.  If these files are not
    needed this option can greatly increase loading time.
