; FITAB
;---------------------------------------------------------------
;! writes images / uv data w extensions to tape in FITS format
;# TASK TAPE FITS UV IMAGE-UTIL
;-----------------------------------------------------------------------
;;  Copyright (C) 1999-2000, 2003-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
;-----------------------------------------------------------------------
FITAB     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
FITAB:  Task to write maps or uv data as tables on a FITS tape
DOALL          -1.0         1.0    1 (T) do all, -1 (F) do 1st.
INNAME                             Image name(name).  Standard.
INCLASS                            Image name(class). Standard.
INSEQ           0.0      9999.0    Image name(seq. #).
INDISK          0.0         9.0    Disk drive #.      0 => any
INTYPE                             File type.     Blank => any
OUTTAPE         0.0         9.0    Tape drive #.  0 => 1
DATAOUT
                                   Disk file name
DOEOT          -1.0         1.0    1 (T) go to end tape first.
FORMAT          0.0         4.0    tape format:   0 => 3.
                                       1 for 16-bit integer
                                       2 for 32-bit integer
                                       3 for 32-bit IEEE
                                         floating point
                                       4 for 8-bit integer
BLOCKING        0.0        10.0    tape blocking factor (<= 10)
QUANTIZE        0.0                Quantize images written
                                   ***** BE CAREFUL!!!
DOUVCOMP       -1.0         1.0    > 0 => write compressed form
                                   of uv data in output tables
NPIECE          0.0        90.0    Break uv data into NPIECE
                                   pieces
BDROP           0.0        90.0    Don't write the first BDROP
                                   pieces
CATNO                              Limit range of DOALL
----------------------------------------------------------------
FITAB
Type: Task
Use:  FITAB converts the standard header and map or uv data and writes
      it on an output tape in the FITS format.  The first or all uv or
      image files that match the input parameters can be written.  The
      tape is left following the End-of-file mark which terminates the
      last file written.  All Clean Components extension files for maps
      or ANtenna files for uv data will be written with the image in a
      standard binary TABLES format (following the image or itself in
      the file).  Other tables-format extension files will also be
      written.

      FITAB differs from FITTP in that it writes uv data as a binary
      table rather than a "random-groups" structure.  This allows it to
      be written in a compressed format that is essentially the same as
      compressed uv data on disk.  It also allows the data if it is in
      time order to be written as multiple files each covering no more
      than a specified time interval.

      *****************************************************************
           FITAB IS NEW IN 15APR99 AND ITS UV-DATA OUTPUT CANNOT
                 BE READ IN TO EARLIER VERSIONS OF AIPS
      *****************************************************************

Adverbs:
  DOALL......True (> 0) means do all files matching the input
             parameters, false (<= 0) means do the 1st match
             only.
  INNAME.....The input image name (name).  Standard defaults.
  INCLASS....The input image name (class). Standard defaults.
  INSEQ......The input image name (seq. #). 0 => any if DOALL
             is true, 0 => highest if DOALL is false.
  INDISK.....The input disk unit #. 0=> search all disks in
             order for file meeting the other criteria.
  INTYPE.....The input data type (MA or UV or ' ' for either)
  OUTTAPE....The output tape unit #.  0=> 1.
  DATAOUT....The name of a 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 (DOALL=-1).  If the data set is broken into
             multiple pieces, then the file name will have a character
             appended to it representing the piece number.  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.
  DOEOT......True (> 0) means to advance the tape to the end of
             information (double EOF) before writing, false means write
             wherever the tape is now positioned.  Note: set DOEOT true
             ONLY if you think that there are already FITS data files on
             the tape AND if you wish to preserve them.
  FORMAT.....Code to tell what format to be used in writing the main
             image data portion of the file as
                   1 for 16-bit integers - only images
                   2 for 32-bit integers - only images
                   3 for 32-bit IEEE floating point - images
                   4 for 8-bit integers - only images
             Default: 0 => 3.
             If you want to import your FITS data into another system,
             make sure that it is able to read the format that you have
             selected.  Tables including all UV data are written in a
             format appropriate to their columns.  The UV visibilities
             are in a format controlled by DOUVCOMP.
  BLOCKING...Code to tell what blocking factor to be used in writing the
             whole file  Default: 0 => 10.
             Considerations: (a) blocking factor <= 10.
                (b) Blocking is ignored when writing to disk
                    rather than tape.
                (c) Larger blocks use fewer I/O operations
                    making tape reads and writes more efficient.
  QUANTIZE...<= 0 => write the output image with the maximum possible
             accuracy (as is done by FITTP).
             > 0 => quantize the output image so that the least bit has
             the value QUANTIZE in the units of the image.  This
             parameter is ignored for uv data.  If FORMAT is 1 or 2, the
             task will use format 2 for output if necessary to avoid
             clipping the image values.  If FORMAT=3, the task will
             integerize the image values with QUANTIZE and then write
             the image in IEEE floating point.  This option is usefull
             when the FITS file is to be compressed (with gzip for
             example) for more efficient storage or transmission.  If
             QUANTIZE < 1/4 of the noise in the image, then the noise in
             the output image will be only a percent or 2 larger than in
             the input.  This is a very dangerous option; if QUANTIZE is
             set too high the image is severely compromised.
                **************    BE CAREFUL.    ****************
  DOUVCOMP...> 0 => write the uv data out in a compressed format similar
             to the compressed format used on disk.  This can reduce the
             size of the files by as much as a factor of 3, but limits
             the dynamic range within a single visibility sample to a
             part in 32700 or so.  It also means that a single weight is
             assigned to all unflagged samples in the record.  This may
             be undesirable in the presence of averaging of data that
             are flagged differently for different Stokes, IFs, and/or
             spectral channels.  <= 0 => write the samples in 3
             floating-point values (real, imaginary, weight) per
             channel/IF/Stokes.
  NPIECE.....The UV data may be broken into NPIECE segments.  Writing
             several smaller files may be more reliable on magnetic tape
             or across networks.  If pseudo-tape disk files are being
             written, the output files for the additional pieces will
             have 1 or 2 appended characters in their names giving the
             sequence numbers.
  BDROP......If NPIECE > 1 and NPIECE > BDROP > 0, do not write the
             first BDROP pieces.  This option is used for those times in
             which the first BDROP pieces were written to tape
             correctly, but the BDROP+1 piece failed for some reason
             such as running off the end of the tape.
  CATNO......Range of catalog numbers over which the operation is to
             take place.  CATNO(1) <= 0 -> 1; CATNO(2) < CATNO(1) ->
             very large.
----------------------------------------------------------------





