; TABED
;---------------------------------------------------------------
;! Task to edit tables
;# TASK TABLE EDITING
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1999-2000
;;  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
;-----------------------------------------------------------------------
TABED     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
TABED     Task to edit tables
INNAME                             Input image name (name)
INCLASS                            Input image name (class)
INSEQ             0.0     9999.0   Input image name (seq. #)
INDISK            0.0        9.0   Input image disk unit #
INEXT                              Input table extension type
INVERS                             Input table file version no.
OUTNAME                            Output image name (name)
                                   NB: default output = input!
OUTCLASS                           Output image name (class)
OUTSEQ           -1.0     9999.0   Output image name (seq. #)
OUTDISK           0.0        9.0   Output image disk unit #.
OUTVERS                            Output table file version.
                                   Must be equal to INVERS for
                                   header functions(OPTYPE=KEY)
BCOUNT            0.0    99999.0   Beginning row to copy
ECOUNT            0.0    99999.0   Last row to copy: 0 => end
OPTYPE                             Type of operation:
                                   'COPY','ADD ','MULT','DIV ',
                                   'REPL','CLIP','DELE','INSR'
                                   'KEY '
APARM                              Column selection parameters:
                                   1: Col. number.
                                   2: Low subscript
                                   3: High subscript
                                   4: Keyword data type (1-6)
                                   5: test col., 6: test value
                                   7: test tolerance,
                                   8: subscript, 9: no. char.
KEYWORD                            Name of table keyword.
KEYVALUE                           Value given to numeric parm.
KEYSTRNG                           Value given to a character-
                                   valued parameter.
TIMERANG                           Time range to use.
----------------------------------------------------------------
TABED
Task:  TABED edits AIPS extention tables files.
       Use PRTAB to determine the relevant column numbers for
       specifying data.
          If the output table is not the input table the data
       selected will be appended to the end of the table.
Adverbs:
  INNAME.....Input image name (name).       Standard defaults.
  INCLASS....Input image name (class).      Standard defaults.
  INSEQ......Input image name (seq. #).     0 => highest.
  INDISK.....Disk drive # of input image.   0 => any.
  INEXT......Extention table type (e.g. 'CC') no defaults.
  INVERS.....Version number of table to modify, 0=>highest.
             -1 => loop over all tables of type INEXT.
  OUTNAME....Output image name (name). If the output file is
             unspecified the output file defaults to the input.
  OUTCLASS...Output image name (class).     See above
  OUTSEQ.....Output image name (seq. #).    See above
  OUTDISK....Disk drive # of output image.  See above
  OUTVERS....Output version number.         See above
             -1 => output number = input number.
             Must be equal to INVERS for header functions
             (OPTYPE=KEY).
  BCOUNT.....Beginning row number to be included .
  ECOUNT.....Last row number included.  0 = highest.
  OPTYPE.....The operation type:
             'COPY' = Copy selected data with no modification,
             'ADD ' = Add KEYVALUE to table entries,
             'MULT' = Multiply table entries by KEYVALUE,
             'DIV ' = Divide table entries by KEYVALUE,
             'REPL' = replace table entries by KEYVALUE or
                      KEYSTRING,
             'CLIP' = Not yet implemented,
             'DELE' = Not yet implemented,
             'INSR' = Not yet implemented,
             'KEY ' = Replace/add KEYWORD in table header.
                      Note: the output file is ignored for
                      OPTYPE='KEY'. OUTVERS has to equal INVERS.
  APARM......Column selection parameters:
             1 = The logical column number for the column to be
                 modified.  Use PRTAB to determine.
             2 = Lowest subscript in array.  A table entry can
                 be an array so this points to first value in
                 this array to modify.  For character strings
                 this is the first character. 0=>1
             3 = Highest subscript in the array. 0=>all.
             4 = Data type for keyword operations:
                 1 = double precision
                 2 = single precision
                 3 = character (up to 8 char)
                 4 = long integer
                 5 = logical (KEYSTRNG='.TRUE' or '.FALSE.'
                 6 = short integer (16 bits if available)
              The specified operation can be conditioned on the
              result of a test comparision of a specified value
              with a specified table entry.  If this test is
              specified the operation is only performed if the
              specified table entry agrees with a specified
              value to within a specified tolerance.  This test
              if specified if APARM(5) > 0.
                 APARM(5) = test column,
                 APARM(6) = test value,
                 APARM(7) = test tolerance,
                 APARM(8) = test column subscript,
                 APARM(9) = number of characters to compare
                            (used for character data only).
              If the test column contains a character string
              then the APARM(9) characters beginning with
              APARM(8) are compared aginst the value in
              KEYWORD.  Recognized wildcards are:
                  '*' => any number of arbitrary characters,
                  '?' => as single arbitrary character.
              Default APARM(8)=1, APARM(9)=8 (max=8).
  KEYWORD.....The keyword name for table keyword operations or
              the test character string for a conditional
              operation on a table entry.
  KEYVALUE....The value to be given to a numeric parameter.
              If the data type is single precision use:
                  KEYVALUE(1)
              If the data type is double precision use:
                  KEYVALUE(1) + KEYVALUE(2)
              If the data type is integer use:
                  ROUND (KEYVALUE(1))
  KEYSTRNG....The value to be given to a character parameter.
              For logical variables use '.TRUE.' and '.FALSE.'
              No default.
  TIMERANG...Time range of the data to be used. In order:
             Start day, hour, min. sec,
             end day, hour, min. sec. Days relative to ref.
             date. Only used if table has a column labeled
             'TIME'.
----------------------------------------------------------------
TABED:  Task to modify and/or copy portions of a table.
Documentor: W. D. Cotton
Related Programs: PRTAB, CLCOR, TACOP, TAFLG

     This task allows the modification of entries in AIPS tables,
either inplace or copying the results to another table.  Either header
Keyword-Value pairs or "row" data may be modified.  In addition, an
operation on row data may be conditioned on the result of a test on a
value or character string in each the row.

OUTPUT TABLE:

     TABED may work either in place, in which case the input table is
modified, or writing the modified table entry to a second file. Note:
Keyword-Value operations are always done inplace but if the output of
a table row operation is to a previously nonexistant table all of the
keywords from the input table are copied.
     The output table is specified by OUTNAME, OUTCLASS, OUTSEQ,
OUTDISK and OUTVER.  If these are not specified then the default
output file is the input file.  If the output table is not the same as
the input table then the new entries are appended to the end of the
table.

KEYWORD OPERATIONS:

     There are two types of operations, modifying a Keyword-Value pair
and everything else.  The desired operation is specified by the ADVERB
OPTYPE.  A description of the Keyword operation follows:

OPTYPE = 'KEY'
    This operation is to modify the value associated with a Keyword in
the table header if it exists or add the Keyword-Value pair if the
Keyword is currently not in the header.  This operation is always
inplace and the output file is the input file.  The current Keywords
and their values may be determined using PRTAB.
     The Keyword to be modified or added is given in the adverb
KEYWORD; the value to be associated with the Keyword is given by
KEYVALUE if it is numeric, or KEYSTRNG if a character string or
logical value.  The keyword type for a Keyword to be added is given by
APARM(4) using the following codes:
            1 = double precision (sum of KEYVALUE(1 and 2)),
            2 = single precision (KEYVALUE(1)),
            3 = character (up to 8 char from KEYSTRNG),
            4 = long integer (INTEGER (KEYVALUE(1))),
            5 = logical (KEYSTRNG='.TRUE' or '.FALSE.'
            6 = short integer (16 bits if available).

"ROW" OPERATIONS:

     The table consists of a number of rows containing a number of
columns.  All operations involve an entire row (logical record) in the
table.  Each column in a row has an associated value which is either a
scalar or a 1-dimensional array.  Each row in the table has the same
structure.  Each column has an associated data type, the defined row
data types and the way values are passed to TABED are the following:
      double precision: KEYVALUE(1)+KEYVALUE(2)
      single precision: KEYVALUE(1)
      character: up to 16 characters from KEYSTRNG
      long integer: INTEGER (KEYVALUE(1))
      logical: true or false as given by KEYSTRNG '.TRUE.' or
              '.FALSE.'
      short integer: INTEGER (KEYVALUE(1))
      bit: Like logical but 1=true, 0=false.

     A single column may be operated on at a time; this column is
specified by APARM(1); the data type of this column in contained in
the header and does not need to be specified although the value given
in KEYVALUE or KEYSTRNG must correspond to the column type.  The
logical column numbers may be determined from a PRTAB listing, the
column numbers are given above the column label at the top of the
listing.
     One value is passed to TABED but if the table entry to be
modified is an array then a number of contigious elements in the array
may have the same operation performed.  The first array subscript is
given by APARM(2) and the highest by APARM(3).

OPTYPE='COPY'
     This OPTYPE specifies that the selected logical table entries
(entire rows) be copied from one table to another.  No values are
modified.

OPTYPE='ADD'
     This OPTYPE specifies that the value given in KEYVALUE be added
to the specified column entry(s) in the table.  This operation is not
defined for character, logical or bit data.

OPTYPE='MULT'
     This OPTYPE specifies that the new table value(s) is(are) the old
value(s) multiplied by the value specified in KEYVALUE.  This
operation is not defined for character, logical or bit data.

OPTYPE='DIV '
     This OPTYPE specifies that the new table value(s) is(are) the old
value(s) divided by the value specified in KEYVALUE.  This operation
is not defined for character, logical or bit data.

OPTYPE='REPL'
     This OPTYPE indicates that the current values of the specified
table entries are to be replaced with the value given in KEYVALUE or
KEYSTRNG.  This operation is defined for all data types.

OPTYPE='CLIP','DELE', and 'INSR' are not yet implemented.

SPECIFYING THE ROWS:

     The rows to be operated on may be specified unconditionally by
BCOUNT and ECOUNT, the first and last row numbers to be considered,
and/or conditionally by TIMERANG and/or APARM(5-9).   If a column
title is 'TIME' then the range of values in this column for rows to be
considered further can be limited to the range given in TIMERANG.
This will work properly if the units of the TIME column are days; the
units may be determined from a PRTAB listing.
     Rows passing any BCOUNT-ECOUNT or TIMERANG test may be further
selected by the result of a test on an arbitrary column.  This column
is specified by APARM(5); a positive value of APARM(5) indicates that
such a test is to be performed.  The array index of the column entry
to be tested is given in APARM(8).
     For numeric columns the test is passed if the tabulated value
agrees with the test value APARM(6) to within a tolerance given by
APARM(7).  If the test is passed the requested operation is performed.
     For columns containing character data, the test string is passed
in adverb KEYWORD which is limited to 8 characters.  The first
character in the tabulated string to be tested is given by APARM(8)
and the number of characters to be tested is given in APARM(9).  Two
wildcard characters are recognized; '*' means any number of arbitrary
characters, '?' means a single arbitrary character.

EXAMPLES:

     The following examples show how to set that adverb values for
several different types of table editing operations.

     The first example is to change the value of the logical Keyword
APPLIED in SN table 1 to false.
   OUTNAME='ABC'; OUTCLASS='UVDATA'; OUTSEQ=1; OUTDISK=1
   OUTVER=1; INEXT='SN'
   OPTYPE='KEY'; APARM=0 0 0 5
   KEYWORD='APPLIED'; KEYSTRNG='.FALSE.'

     The next example is to multiply the fluxes of the first 25 CLEAN
components from one CC file by 1.273 and write the results to another.
The flux density is given in column 1.  Note: the output table need
not exist prior to this operation.
   INNAME='3CXYZ'; INCLASS='ICL001'; INDISK=2; INSEQ=1
   INVER=1; INEXT='CC'
   OUTNAME='ABC'; OUTCLASS='ICL001'; OUTDISK=3; INSEQ=1
   OUTVER=1
   OPTYPE='MULT'; APARM=1 1 1; KEYVALUE=1.273 0
   BCOUNT=1; ECOUNT=25

     The next example is to set the group delay for antenna 3, first
polarization (RCP), and IFs 1 and 2 to 0.0 for the time range
1/2:30:00 1/2:55:00 in an SN table.  The antenna number is in column 4
and the delays for the first polarization "DELAY 1" are in  column 12.
   INNAME='3CXYZ'; INCLASS='MULTI'; INDISK=1; INSEQ=1;
   INEXT='SN'; INVER=1
   CLRO
   OPTYPE='REPL'
   APARM=12 1 2 0 4 3 0.3 1 0
   KEYVALUE=0.0
   BCOUNT=1; ECOUNT=0
   TIMERANG= 1 2 30 0 1 2 55 0

     The last example is to change the PFLAGS (Stokes correlator
flags) in an FG table to 1111 (all correlators i.e. RR, LL, RL, LR in
order, are flagged) if the REASON is 'TVFLG 28-AUG-87 13:34:28'.  The
PFLAGS column is 8 and the REASON column is 9.  The last 8 characters
of the REASON string are checked due to an ambiguity in the first 16
(i.e. TVFLG was run several times that day.)
   INNAME='3CXYZ'; INCLASS='MULTI'; INDISK=1; INSEQ=1;
   INEXT='FG'; INVER=1
   CLRO
   OPTYPE='REPL'
   APARM=8 1 4 0 9 0 0 17 8
   KEYWORD='13:34:28'; KEYSTRNG='.TRUE.'
   BCOUNT=1; ECOUNT=0
