; TBDIF
;---------------------------------------------------------------
;! Compare entries in two tables
;# TASK UTILITY TABLE
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1999, 2004, 2009
;;  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
;-----------------------------------------------------------------------
TBDIF     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
TBDIF:    Compare entries in two tables
INNAME                             Main input file (name).
INCLASS                            Main input file (class).
INSEQ             0.0    9999.0    Main input file (seq. #).
                                      0 => high
INDISK            0.0       9.0    Disk unit #.       0 => any
INEXT                              Input table extension type
INVERS                             Input  file version no.
IN2NAME                            2nd UV data (name).
IN2CLASS                           2nd UV data (class).
IN2SEQ            0.0    9999.0    2nd UV data (seq. #).0=>high
IN2DISK           0.0       9.0    2nd Disk unit #.  0 => any
IN2VERS                            2nd table version no.
BCOUNT            0.0    99999.0   Beginning row to compare
ECOUNT            0.0    99999.0   Last row to compare: 0 => end
SOURCES                            Column names to compare
CALSOUR                            Column names for match
DOALL            -1.0       1.0    > 0 print all matching rows
                                   else print rows that differ
DOCRT            -3.0     132.0    > 0 -> use CRT, else printer
                                   > 72 => CRT width in chars
OUTPRINT
                                   Printer disk file to save
BADDISK           -1.0      1000.0 Disks to avoid for scratch.
----------------------------------------------------------------
TBDIF
Type:  Task
Use:   TBDIF compares entries in two tables.  If multiple columns are
compared then each one will be done separately.  For each selected row
in the first table the second table is searched for a match as
specified by CALSOUR.  If a match is found the values in the selection
columns and the comparison columns are printed.  For numeric data type
a summary of the statistics are also printed at the end of the
listing.
Adverbs:
  INNAME......1st table (name).       Standard defaults.
  INCLASS.....1st table (class).      Standard defaults.
  INSEQ.......1st table (seq. #).     0 => highest
  INDISK......1st table (disk no.)    0 => any
  INEXT.......Table type (e.g. 'CC') no defaults.
  INVERS......1st table version numnber.
  IN2NAME.....2nd table (name).       Standard defaults.
  IN2CLASS....2nd table (class).      Standard defaults.
  IN2SEQ......2nd table (seq. #).     0 => highest.
  IN2DISK.....2nd Disk unit #.               0 => any.
  IN2VERS.....2nd table version numnber.
  BCOUNT.....Beginning row number of first table to be included.
             See EXPLAIN TBDIF for the effects of sorting.
  ECOUNT.....Last row number of first table included.
             0 = highest.
  SOURCES....List of column names to compare.  Columns can be
             specified by column number using the form
             'COL#(i)'.  Column 12 is specified by 'COL#(12)'.
  CALSOUR....List of columns names (or numbers using the same
             conventions as SOURCES) which must match exactly.
             Only the first exact match in the 2nd table will be
             considered so the columns given in CALSOUR should
             assure an unique match.
  DOALL......> 0 => print all rows that match up
             <= 0 => print only those that differ
  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 most 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.
  BADDISK.....This array contains the numbers of disks on which
              it is desired that scratch files not be located.
              BADDISK has no effect on input files.
----------------------------------------------------------------
TBDIF:  Task to compare selected columns in two similar tables.
Documentor: W. D. Cotton
Related Programs: PRTAB

   This task allow a relatively flexible way of comparing the
values in two tables.  TBDIF will search the second table for an
entry with matching values of a set of columns.  When a match is
found the values of the comparison column in the two tables are
given and their difference for numeric data types.  Values from
the selection columns are given in the order of the columns
listed in CALSOUR as space permits.  At the end of the
comparison listing a summary of the comparisons (numeric columns
only) is given.  Only one comparison column will be processed at
a time but multiple columns may be specified in SOURCES.
   Either selection or comparison columns may be arrays.  All
element in a selection column are tested and all element in a
comparison column are compared both in the row by row
comparisons and the summary.
   The UNITS associated with the columns may trigger special
behaviour.  If the units are "DAYS" in a selection column then
that column is displayed as d/h:m:s.  If the units are "DEG" in
a real type comparison column the difference will be reduced to
the range (-180,180).
   In order to speed the comparison of the two tables they are
sorted by the first selection column.  For long table this means
that the first selection column (CALSOUR(1)) should be one that
has a relatively large number of values to minimize the search
time.  Due to this sorting of the table, BCOUNT and ECOUNT do
not necessarily refer to the order in the input table.
