; MK3IN
;---------------------------------------------------------------
;! translate Haystack MKIII VLBI format "A" tapes into AIPS
;# TASK VLBI UV
;-----------------------------------------------------------------------
;;  Copyright (C) 1995-1997
;;  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
;-----------------------------------------------------------------------
MK3IN     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
MK3IN     Task which reads Haystack MKIII VLBI format "A" tapes
INFILE                             Experiment info file name
IN2FILE                            A-file name - see HELP
INTAPE                             Tape drive number
NFILES                             Number of files to skip
REFDATE                            Reference date. 'yyyymmdd'
TIMERANG                           Timerange selected
SOURCES                            Source selection list
DOUVCOMP         -1.0        1.0   1 (T) => compressed data
DOCONCAT         -1.0        1.0   1 (T) => append data to old
                                   files (use with caution).
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 #.
APARM                              Control information
                                   (1) = CL table time
                                         increment (min).
                                   (2) = Maximum tape parity
                                         error rate (0=> 0.01)
                                   (3) = Maximum dropout rate
                                         accepted (0=> 0.5)
                                   (4) <0.5 => full FBS corr.
                                       >0.5 => phase-only FBS
                                       >1.5 => suppress FBS
                                   (5) = No of files to read
                                         from tape (0=> to EOT)
                                   (6) 0 => apply all error
                                            checks to data
                                       1 => ignore CRCC errors
                                       2 => ignore slip sync
                                       3 => ignore both CRCC
                                            and slipped sync
                                   (7) > 0 = separate sidebands
                                   (8) > 0 = accept data with
                                             LO offset
                                   (9) = Print level (0..4)
                                   *** DEBUG ***
                                   (10) = 1=> dump headers
                                          2=> dump header, data
----------------------------------------------------------------
MK3IN
Task:  This task reads MKIII VLBI data from Haystack "A" tapes.
       An ASCII experiment file is read from disk to assign
       antenna numbers and obtain other information.  Any type
       52 (Haystack FRNGE output) records are written to an AIPS
       HF table (see EXPLAIN MK3IN).
Adverbs:
  INFILE.....Name of ASCII experiment information file.
             Eg., disk$res:[username]STATIONS.DAT under VMS or
             MYVLB:STATIONS.DAT under UNIX
  IN2FILE....Name of ASCII file containing list of scans to
             be read from an 'A' tape. This file can be
             generated by hand, or using the task AFILE.
             If IN2FILE = ' ', all scans will be read from the
             tape.
  INTAPE.....Tape drive from which to read data.
  NFILES.....Number of files to skip on the tape.
  REFDATE....Reference date 'yyyymmdd', ' ' => first found.  ('dd/mm/yy'
             is accepted too, but deprecated.)  Better get it right!!!
             Data may not be in time order on the tape and the default
             reference date is the first date found.  Data on days
             before the reference data will have negative times and will
             be rejected by the default TIMERANG as well as causing
             other troubles displaying the data.  (Task FXTIM may be
             used to correct the times if you have this problem.)
             The reference day used should be one for which there is
             actual data or the antenna table will end up with incorrect
             data (a warning message is given in this case).
  TIMERANG...Range of UTC times to be read wrt REFDATE. 0=>all.
             If any part of a scan is selected then that whole
             scan is read. See EXPLAIN MK3IN for details.
  SOURCES....Sources to be included in or excluded from the
             output file.  If the first character of any
             element is "-" then all named sources are excluded
             otherwise all named sources are included.  Names
             should correspond to those used in the Mk3
             experiment file.  If all entries are blank then
             all sources are selected.
  DOUVCOMP...If true (DOUVCOMP >= 0) the output data is written
             in compressed format which can result in a
             substantial reduction in disk space needed but only
             calibration routines are likely to interprete this
             data.
  DOCONCAT...If true (>0) then data is to be appended to an
             existing file if possible.  Possible output files
             can be selected by OUTNAME, OUTDISK and OUTSEQ.
             Use this option with CAUTION.
  OUTNAME....Output UV file name (name).    Standard behavior
             with default 'MKIII DATA'.
  OUTCLASS...Output UV file name (class).   Standard defaults.
  OUTSEQ.....Output UV file name (seq. #).  0 => highest unique.
  OUTDISK....Disk drive # of output UV file. 0 => highest disk
             with space for the file.
  APARM......Task control information.
             (1) = Time increment in CL table entries in min.
                   0 => 2 min.  <0 => use PRT (near center) time
                   only
             (2) = Maximum parity error rate on the
                   MKIII data tapes for good data. 0=> 0.01
             (3) = Maximum dropout rate on the MKIII
                   data tapes for good data. 0=> 0.5
             (4)   <0.5 => make full amplitude-phase
                    Fractional Bit Shift (FBS) correction.
                   >0.5 => make phase-only FBS correction.
                   >1.5 => do not make FBS corrections.
             (5) = Number of file to read from tape 0=> to EOT.
             (6) = Data rejection criteria
                   0 => apply all MK3 error checks
                   1 => ignore CRCC errors in sync blocks
                   2 => ignore slipped sync errors (XS/YS)
                   3 => ignore both CRCC and slipped sync
             (7)   If > 0 then separate sidebands into different
                   IF.  This may fail if it exceeds the max.
                   number of IFs.
             (8)   If > 0 then accept data with an LO offset,
                   otherwise terminate job. Note that no
                   correction is yet made for LO offsets.
             (9) = Print level 0=> Source hdr per scan;
                   1=> include scan error summary and
                   correlator model summary; 2 => list
                   each correlator separately; 3  => print
                   COREL file names; 4=> error summary per
                   correlator module serial no.
             (10) = flag indicating a dump of the raw data is
                    requested on Fortran unit 9.
                    0 => no dump
                    1 => header records only
                    2 => headers plus data (type 51 records)
----------------------------------------------------------------
MK3IN : Creates an AIPS uv data set from Haystack MKIII A tapes.
DOCUMENTOR : W. D. Cotton, NRAO/CV
RELATED TASKS : MK3TX, AFILE

                        PURPOSE

     MK3IN creates an AIPS uv data set from a Haystack MkIII
"A tape".

                       COMMENTS

INFILE:
     A separate external file MUST be created by the user (and
text editor) containing the names of stations used in the
current VLB experiment. The station names are entered in quotes
like this :
STATIONS='NRAO','VLA','OVRO','FDVS','MPI','JDRLMKII',
'OSO25','CRIMEA'
Note: no case conversion is done so the case should match the
antenna name as given on the tape.  When MK3IN starts up, it
will list the stations it found in INFILE.  Task MK3TX should
help in the determination of the antenna names used.
   The first time MK3IN is run on data from an experiment,
antenna names 'ANY' may be used and any antennas found (up to
the number of 'ANY's in STATIONS) will be accepted.  If more
data is to be read from other tapes then the STATIONS array must
be filled in using the values in the AN table.  The order of the
antenna names in STATIONS defines the antenna numbers used
inside the AIPS data base.  To insure that a given antenna is
always given the same number be sure to update the values in
STATIONS after any execution of MK3IN in which a new antenna has
been added as a result of an 'ANY' in the STATIONS list.
   The times in the data set can be either in UTC or IAT.  To
use IAT the correction from UTC to IAT (IAT-UTC) should be given
as the parameter TIMEOFF as in:
TIMEOFF=23.0
If no value of TIMEOFF (or 0.0) is given then the time system is
assumed to be in UTC.
   The Stokes parameter range of the output file is set using the
parameter:
  STOKES= subset of {'RR','LL','RL','LR'}. The default Stokes is
'LL'.

   If polarization sensitive data is to be read in this is
indicated by the parameter DOPOL=1; if data are all of the same
Stokes' type this is indicated by DOPOL=-1 (the default).
   The MKIII correlators usually indicate different
polarizations by using frequency codes; as these codes are not
entirely consistent they may be entered using FREQCODE as:
FREQCODE='R','L','r',l'   (where R=RR; L=LL; r=RL; l=LR).
If DOPOL=1 the defaults are 'R','L','r' and 'l' else any
frequency code is selected.

   The following are optional parameters in the experiment
file, and will default to the values found for the first scan.
  NO_LAGS  -  Number of XC lags in output file (only correlation
              functions with this lag range will be translated;
              autocorrelation functions with half this range).
  NO_IF    -  Number of IF's in the output file.
  SIDEBAND -  'DOUBLE' => concatenate video converter USB, LSB
              to form one IF (default).
Enter the delimiter character (/) at the end of the experiment
information.

    The experiment definition may be followed by an optional
list of antenna aliases.  This comprises a line containing
the keyword ALIASES and a delimeter character (/) followed
by a list of paired strings.  If the first string of any pair
matches an antenna name in the input data then the antenna
name will be replaced by the second string.  This is done
before matching the antenna names against the antenna list
given in the experiment definition.

    Here is an example experiment definition file using aliases.

STATIONS='TDRSE', 'USUDA', 'DSS43'
/
ALIASES /
'TDRS1' 'TDRSE'
'TDRS2' 'TDRSE'
'TDRS3' 'TDRSE'
'TDRS4' 'TDRSE'
/

In this experiment data from TDRSE was correlated using four
different names.  With the alias list given, MK3IN will recognize
all four names as referring to the same telescope and will name
this telescope TDRSE in the AIPS data file.


    Examples:
         INFILE='disk$res:[username]stations.dat'     (VMS)
         INFILE='MYAREA:STATIONS.DAT'                 (Unix)
            where MYAREA is an environment variable set before
            starting AIPS:
            %setenv MYAREA /mnt/username.
    Note: All file names used on a Unix system must have only
    uppercase characters in the name.

   The abbreviations used in the error summary have the following
meaning:

   Code  Desc
   MOD   Correlator module serial number (0 => module sum).
   CS    Correlate suppress
   TS    Tapes out of sync
   AP    AP array overrun
   PP    No PP update
   YS    Y slipped sync.
   XS    X slipped sync.
   CL    No X clock or no Y clock.
   TM    Unexpected tape time.
   CRCC  CRCC error in remote station sync block,
         reference station sync block.
   XP    X parity errors exceed parity error rate
         for good data.
   YP    Y parity errors exceed parity error rate
         for good data.
   XD    Fewer than allowed fraction of the nominal
         number of bits are correlated within the AP
         in the cos channel (set by maximum dropout rate).
   YD    As for XD but applies to the sine channel
         correlation count (ignored for AC functions).
   MT    Module termination status bad (ie operator
         reports error condition).
   3A    MKIIIA error condition.
   TOT   Total number of module output records read.

    Each column indicates the percentage of module output records
with the appropriate error condition.  The field Nvis=nnn
indicates the number of full correlation functions passed by
MK3IN. The field Good=xx% indicates what percentage of
correlation functions was passed.

Multiband Observing

   A special problem occurs when data at different observing
bands are observed simultaneously, e.g. S/X geodetic style
observations.  MK3IN will read all data and place them in the
same file.  For purposes of calibration and imaging these must
be seperated into seperate files using UVCOP.

FRNGE output

   The output of the Haystack baseline fringe fitting routine
FRNGE is copied to the AIPS table of type HF.  The labels of the
column are the names of the entries in the Haystack
documentation.  The contents of this table with a description
from Haystack documentation are given in the following:

Col #  Label    Type(dim)  Description
 1   XY          C*2       Baseline code, 1 char per antenna.
 2   UTC TAG     I(6)      UTC time tag (YMDHMS) EPOCH for delay
                  and rate .
 3   VLB2 UTC    I(6)      UTC of FRNGE processing (YMDHMS)
 4   ARCHIV      I(4)      ARCHIV
 5   SAMPRATE    I         Sample rate in kbits/sec
 6   FR/PP       I         no. frames per parameter period
 7   PASS NO.    I         Pass number
 8   NO. CHANELS I         #U/L sideband pairs included in this
                   processing (i.e. # of discrete LO
                   frequencies)
 9   NO. OF AP   I(28)     #Accumulation periods by sideband by
                   channel
10   RECTRACK    I(2,2,14) Track # table in order of:
                   Station #, Refer/partn Sideband, Channel #
11    COREL VERSION NO. I  COREL version #
12    UTCM TAG   I(6)      UTC time tag (YMDHMS)  EPOCH for
                   "central" EPOCH
13    LU OF PRINTOUT   I   LU of printout (for FRNGP)
14    REF. TAPE DRIVE NO. I Reference tape drive number
15    REM. TAPE DRIVE NO. I Remote tape drive number
16    SPECIAL OPTIONS  I    Special options NAME(211)
17    INTEGER PARM(250)  I  Integer value of PARAM(250) [=999
                   for special PCAL by AP]
18    CORELXTNT       I(2,14) COREL extent# from which each
                   track is taken.
19    CALBYFRQ        I(3,2,14) Phase-cal amp, phase and freq by
                   station and channel normalized as follows:
                      AMP 0 to 10000(in voltage) -1=manual cal
                      PHS -18000 to +18000
                      frq  kHz
20    PROCUTC         I(2,14) COREL processing UT (YDDD) by
                    sideband and channel.
21    ERRORATE        I(2,2,14) Tape error rate by station,
                    sideband and channel encoded as:
                    1000*LOGT(error rate) (=-32000 if no errors)
22    INDEX           I(2,14) COREL index #s by sideband and
                    FRNGE CH#
23    FRNGE ERROR CODE  I   FRNGE error code 0=OK NE.0 Don't use
24    SBDOFFST FLAG   I     flag 1=this run had sideband fixup.
25    STAR ID         C*8   Radio source name
26    BASELINE ANT1   C*8   First antenna name of baseline
27    BASELINE ANT2   C*8   Second antenna name of baseline
28    CORELFILE       C*6   COREL correlation output
                   file name
29    TAPEID ANT1     C*8   first raw-data tape ID label
30    TAPEID ANT2     C*8   second raw-data tape ID label
31    VLB2PRG         C*6   FRNGE program version YYMMDD
32    RUN CODE        C*8   Run code, e.g. "329-1300"
33    FRNGE QUALITY CODE C*1 FRNGE quality code 0=no good,
                   1=very poor, 9=very good, A=has FRNGE error
                   code=1,B=2 etc.
34    FREQ. GROUP CODE C*2  Frequency group code
35    ORIG. COREL FILE NAME C*6 Original COREL file name
36    TAPE Q CODE     C*6   Tape Q code
37    REF OCCUPATION CODE C*8 Ref station occupation code
38    REM OCCUPATION CODE C*8 Rem station occupation code
39    RFREQ           D(14) LO frequencies (MHz) by channel
40    REF FREQ        D     RF freq (MHz) to which phase is
                   referred
41    DEL OBSV        D     Observed group delay in
                   microseconds equals single band delay if only
                   one freq. processed.  DELOBSV=T2-T1, T1=time
                   of arrival at site 1 (reference site) as
                   measured by the site clock at site 1, T2=time
                   of signal arrival at site 2 as measured by
                   site clock at site 2.  The signal in question
                   is the one which arrives at site 1 at a UTC
                   time equal to that given as the UTC epoch.
42    RATOBSV        D     Observed delay rate (usec/sec)
                   corrected for the phase cal rate.
43    NB DELAY       D     Narrow-band group-delay (usec)
44    DGPD           D     group delay ambig. (usec)
45    BTE0           D     apriori clock (usec)
46    EPOCH0         D     ref. st. clock epoch (usec)
47    DEL OBSVM      D     observed delay at central epoch
48    RAT OBSVM      D     observed delay rate at central epoch
49    DLY2           D     phase delay at EPO+1 sec
50    DLY3           D     phase delay at EPO-1 sec.
51    AMBYFRQ        R(2,14) Amp and phase by channel 1=100%
                   phase=-180 to 180 deg. residual to COREL and
                   uncorrected for PCAL rate.
52    PHASECAL       R(2)  Phase cal rate by station (usec/sec)
53    DELRESID       R     Delay residual to COREL a priori.
54    DELSIGMA       R     Calculated delay error (usec)
55    RATRESID       R     Delay-rate residual to COREL a priori
                   (usec/sec) corrected for phase cal rates.
56    RATSIGMA       R     Calculate delay-rate error (usec/sec)
57    COHERCOR       R     Coherent multi-freq correlation
                   coefficient. (1=100% correlation)
58    TOTPHASE       R     Total observed fringe phase (deg)
59    UVF/ASEC       R(2)  Fringes per asec in N-S and E-W
60    STARELEV       R(2)  Calculated star elevations run reference
                   time by station (deg).
61    AAMP FRNGE     R     amplitude from incoherent addition of
                   frequency channels.
62    URVRSEC        R(2)  Rate derivatives mHz/sec arc
63    SRCHPAR        R(6)  Search parameters
64    DEPSBRES       R     Single band delay residual (usec)
65    SNR            R     Signal to noise ratio in sigma.
66    PROB           R     Probability of a false detection.
67    INCOH          R     Incoherent segmented fringe amp. in
                   units of 10,000.
68    EARP           R     total phase refered to an epoch at
                   time the signal reaches the center of the
                   earth.
69    REARP          R     Residual phase corrected to earth
                   centered epoch
70    START          R     Start time in seconds past hour
71    STOP           R     Stop time in seconds past hour
72    EPD            R     Epoch offset from center of run in
                   sec.
73    DUR            R     Effective run duration in seconds.
74    DELSS          R     Single-band delay error in microsec.
75    QB             R     Ratio of min to max data accepted in %
76    DISCD          R     % data discarded
77    TOTPM          R     Total phase at central epoch


Notice about using DAT tapes

   The current practice at the MkIII correlators (3/92) appears
to be to copy entire 9 track archive tapes INCLUDING the EOI
(double file mark).  Strictly speaking, data after an EOI
mark is inaccessable and on some systems (Suns?) this may be
true in practice.  If MK3IN does not recover all of the data
that you expect then tell it "GO" a second (or further) time
WITHOUT rewinding the tape until it no longer finds any data.

