; FILLR
;---------------------------------------------------------------
;! reads old VLA on-line-system tapes into AIPS
;# Task Tape UV
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1999
;;  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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
FILLR     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
FILLR     Task to read a VLA MODCOMP archive tape.
          UNLESS YOU HAVE VERY OLD DATA, YOU WANT TASK FILLM
INTAPE                             Tape drive number
NFILES                             Number of files to advance
DOALL                              If true take all sources.
OBJECT                             Source name
BAND                               Frequency band (P,L,C,X,U,K)
QUAL                               Source qualifier -1=>all
VLAOBS                             VLA obs. pgm. name ('AZ99')
VLAMODE                            VLA obs. mode ('  '=normal)
NPOINTS                            Max. number of 1000's vis
BIF               0.0        2.0   Start IF to read, 0 => all
EIF               0.0        2.0   End IF to read, 0 => BIF+1
OUTNAME                            Output UV file name (name)
OUTCLASS                           Output UV file name (class)
OUTSEQ           -1.0     9999.0   Output UV file name (seq. #)
OUTDISK           0.0        9.0   Output UV file disk unit #.
DPARM                              User options.
                                   1 => Avg. time (seconds)
                                   2 => max. IF flag allowable
                                       (default 3)
                                   3 => max. sum of IF flags per
                                        baseline (def 4)
                                   4 => Control dropping of
                                        shadowed data
                                        < 0  => no shadow check
                                        0 or < 25 => 25 m limit
                                        > 25 => Shadow limit is
                                        DPARM(4) in metres
                                   5 = no. channels (see HELP)
                                   6 => Subarray number 0=>any.
                                   7 => reference date offset.
                                   8 => CL table time incr. min
                                   9 => No. files to read.
----------------------------------------------------------------
FILLR
Task:  This task will create an AIPS uv data file and fill it by
       reading selected data from a VLA MODCOMP archive tape.

       NOTE THAT THIS TASK IS FOR DATA IN A FORMAT NOT WRITTEN SINCE THE
END OF 1987.  ALL OF THE ARCHIVE DATA WERE CONVERTED TO THE NEW FORMAT
AS WELL, SO FILLR APPLIES TO DATA TAPES EXPORTED FROM THE VLA PRIOR TO
1988 (OR AT LEAST PRIOR TO THE ARCHIVE UPGRADE).  FOR MORE RECENT TAPES,
USE FILLM.

Adverbs:
  INTAPE.....Tape drive from which to read data.
  NFILE......Number of tape files to advance before reading.
  DOALL......If DOALL is true, a multi source output file
             will be written with associated SoUrce, iNdeX
             and CaLibration extention tables.

  OBJECT.....Name of the desired source. blank=>first found.
  BAND.......Name of desired frequency band i.e. 'P','L','S',
             'C','U','X' or 'K'.  Blank => first found.
  QUAL.......Source qualifier number, -1=>all.
  VLAOBS.....The name of the observing program on the VLA,
              e.g. 'AZ99'. blank=> first found.
  VLAMODE....The VLA observing mode. Normal interferometer mode
             is '  '. (2 characters).
  NPOINTS....The maximum number of 1000's of visibilities.  The
             output file will be contracted if the guess is too
             large but the file cannot be expanded.  If the
             guess is low by more than 20% then FILLR will stop
             when the file fills up.
  BIF........Start IF to read, 0 => all IF's
  EIF........End IF to read, 0 => MIN (BIF+1, NIF) where NIF is
             the number of IF's present in data base
  OUTNAME....Output UV file name (name).    Standard behavior
             with default 'source name'.
  OUTCLASS...Output UV file name (class).   Default 'UVDATA'
  OUTSEQ.....Output UV file name (seq. #).  0 => highest unique.
  OUTDISK....Disk drive # of output UV file. 0 => highest disk
             with space for the file.
  DPARM......User options.
             (1)  Averaging time in seconds. If 0 no averaging
                  will be done. NOTE: the program subtracts 2
                  seconds from this value.
             (2)  Maximum IF flag allowable from the online
                  system.  0 => 3
             (3)  Maximum sum of IF flags per baseline, 0 => 4
             (4)  Control shadow checking
                  < 0       => don't drop shadowed data
                  0 or < 25 => drop data with 25 metre limit
                  >= 25     => drop data when they are shadowed
                               by an amount in the range
                               0 < SHADOWED <= DPARM(4)
                               where DPARM(4) is in metres
             (5)  if spectral line data for a given source/band
                  with more than one number of channels is
                  present in the data one may be specified by
                  DPARM(5).  0 => first encountered.
             (6)  Subarray number desired. 0=>first found.
             (7)  Reference date offset
             (8)  Time increment (min.) for CL table entries.
                  0 => 5 min.
             (9)  FILLR will attempt to read up to DPARM(9)
                  files and write to a single output file.
                  0 => all.
----------------------------------------------------------------
FILLR:  Task which creates and fills an AIPS uv data set using
        a VLA MODCOMP archive data tape.
DOCUMENTOR: W. D. Cotton, NRAO.
RELATED PROGRAMS: All AIPS uv programs

                          PURPOSE

     FILLR reads a VLA MODCOMP archive format visibility tape,
creates and fills an AIPS uv data base.  Since such a tape may
contain data for a number of observing programs and sources the
user must specify the data that he/she desires.

COMMENTS
     The tape must be properly mounted and the correct
density specified.  This is most easily done using the MOUNT
command in AIPS.  When through reading the tape and no other
tape processing is anticipated, use DISMOUNT to free the tape
drive for other users.





NPOINTS:
     This adverb specifies the maximum number of UV points
which will be transferred to disk from tape. The value of
NPOINTS is 1000 times the number of points to be transferred,
and should also be set at the lowest multiple of 1000 higher
than the number of points to be loaded to disk (e.g.,
NPOINTS=17 for a data set containing 16,201 visibility
records).
     There is a 20% leeway in NPOINTS.  If you set
NPOINTS=17, the UVLOD will read up to 20,400 uv points before
terminating. A warning message is given if more data are found.


OUTDISK:
     Make sure there is enough space for the source data on
the specified OUTDISK (see below).  This is especially
important is many large data bases will be written onto the
disk.


DPARM:

(1)  The data are averaged by averaging all unflagged data with
time tags within the specified period after the first record in
a given integration.  The time tags, u, v, w etc. for each
visibility written will be the average for the integration
irregardless of the flagging; that is the u, v, w may not
correspond to the true weighted average.  Two seconds are
subtracted internally to keep the integration times produced
from being one more MODCOMP integration than intended.

(2-3)  The online system assigns a flag level to each IF in
each integration period.  DPARM(2) sets the maximum allowable
flag level for a give IF and DPARM(3) sets the maximum sum if
the IF flag levels allowed for a correlator.  Increasing flag
level values correspond to increasingly serious problems.

(4)   Data for which one antenna shadows another antenna is
normally rejected.  Crosstalk and solar interference normally
are serious problems in this case.  If DPARM(4) is greater than
0 shadowed data will be passed.

(5)   Modcomp tapes may contain data for a given source/band
with different numbers of spectral channels at different times.
Such data must be kept in separate files.  DPARM(5) is used to
specify which set of data is desired by specifying the number
of channels.  If DPARM(5) <= 0 then the first set encountered
will be used.  The default will have the desired action in
almost all practical situations.

(7)   If data from several tapes are to be concatenated they
must be read by FILLR independently and concatenated by DBCON.
This data should all have the same reference date.  DPARM(7) is
the number of days to offset the reference date.
Example:
     DPARM(7) = -1 causes FILLR to use the day BEFORE the first
day encountered as the reference date.

(8)   A dummy CL table is created with appropriate default
values.  DPARM(8) gives the time interval between entries.
0 defaults to 5 min.

(9)   Modcomp tapes frequently contain several files.  Using
DPARM(9) the number of files read can be controlled.  The
default (0) is to keep reading the entire tape; this may produce
unpredictable results if there are other types of files
following the Modcomp records.  Labled tapes must be read one
file at a time and then concatenated via DBCON.

EXECUTION TIMES:
     The execution time depends on the location on the tape
of the desired data.  If the user starts reading from the
beginning of the tape, required CPU time may be only 10 seconds
for data near the beginning of the tape and several minutes for
data close to the end of the tape, with a roughly linear
relation in between (i.e., most of the CPU time for a data set
not at the beginning of the tape is spent reading through the
tape to find the desired data set). In an otherwise empty VAX
11-780 it takes about 5.5 min to load 50,000 visibility points
(all four polarizations)


DISK SPACE:
     The size of a data set loaded via UVLOD is linearly
proportional to the number of UV records in the data. The ratio
of disk blocks to visibility records is roughly 1:7, so a data
set containing 50,000 visibility records will occupy
approximately 7,000 blocks of disk space.  Be sure there is
enough space on OUTDISK to hold the data.
