; EXTAB
;---------------------------------------------------------------
;! exports AIPS table data as tab-separated text
;# Task Table Plot
;-----------------------------------------------------------------------
;;  Copyright (C) 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
;-----------------------------------------------------------------------
EXTAB     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
EXTAB:  Task to export AIPS table data as tab-separated text
INNAME                             Image name (name)
INCLASS                            Image name (class)
INSEQ             0.0    9999.0    Image name (seq. #)
INDISK            0.0       9.0    Disk drive #
INEXT                              Extension type
INVERS           -5.0   46655.0    Extension file version #
BCOUNT            0.0              First row number
ECOUNT            0.0              Last row number
XINC              0.0   32767.     Increment between rows
OUTFILE                            Output text file
DOHMS            -1.0       2.0    If > 0 print times with
                                   hh:mm:ss.s format
NCOUNT            0.0              Print the first NCOUNT values
                                   in a cell plus
BDROP             0.0              values BDROP through
EDROP             0.0              EDROP (if appropriate)
BOX                                List of columns to be printed
                                   0 -> all.
----------------------------------------------------------------
EXTAB
Type:  Task
Use:   EXTAB may be used to extract data from an AIPS table and
       to write it out in a form that can be imported into a
       spreadsheet, a database, or some other non-AIPS program
       for further analysis or display.
Adverbs:
  INNAME.....Image name (name).           Standard defaults.
  INCLASS....Image name (class).          Standard defaults.
  INSEQ......Image name (seq. #).         0 => highest.
  INDISK.....Disk drive # of image.       0 => any.
  INEXT......Extension file type          No default
  INVERS.....Extension file version #     0 => highest.
  BCOUNT.....First row to list.           0 => 1.
  ECOUNT.....Last row to list.      < BCOUNT => to end.
  XINC.......Increment in row number between listings.
             <= 0 => 1.
  OUTFILE....Full name of the output file, normally given as a
             logical directory name followed by a colon and a
             file name.                   No default
  DOHMS......If DOHMS is false (<=0), the times in the output
             will be printed in days.  If DOHMS > 0, they will
             be printed in the form hh:mm:ss.s.  This is done
             fro any column having units of DAYS and a header
             which starts with TIME.
By default, EXTAB writes all elements in a cell of a table,
generating one output column per element. The next three
adverbs may be used to select a subset of the elements to be
written out. In general, elements 1..NCOUNT and BCOUNT..EDROP
will be written out; the two ranges may overlap or be identical
(as in the default case) but only one copy of each array element
in the overlapping range will be written out..
  NCOUNT.....Elements 1 through NCOUNT are printed for each
             selected cell in the table.  0 => 100000.
  BDROP......Additionally, elements BDROP through EDROP are also
             printed.                     0 => 1.
  EDROP......Additionally, elements BDROP through EDROP are also
             printed.                     < BDROP => 100000.
  BOX........To select the column numbers to be printed including
             their order.  Up to 40 may be selected.
                                          0 => all columns in
                                               basic order.
----------------------------------------------------------------
EXTAB:  AIPS table export task
Documenter: Chris Flatters, NRAO
Related Programs: PRTAB, TBOUT

Contents:

    1. Overview
    2. Limitations
    3. Using EXTAB as a Paraform Task

1. Overview

    EXTAB writes data from an AIPS table to a text file that is
suitable for importing into a program that is capable of dealing
with simple tabular data (e.g. a spreadsheet or a relational
database). The data from one row of the table is written to a
single line of the output file and individual data items are
separated by horizontal tabulation characters. Table columns
that have array values are split apart so that each array index
is given its own output column.

    Numeric quantities are represented with sufficient precision
that no significance is lost in translating them from machine
representation to decimal and back to machine representation
provided that the host system complies with IEEE rules for
floating-point arithmetic. This means that you should be able
to use EXTAB to transfer AIPS table data to a spreadsheet
without incurring any loss of information due to rounding
errors.

    The output format used by EXTAB is easy for programs to read
but appears rather messy to a human reader. I recommend that you
use PRTAB, which uses the same inputs as EXTAB to select the
table data, to preview the before writing it out using EXTAB.

2. Limitations

    EXTAB uses a fixed length buffer to hold each line of
output. Many types of AIPS table contain more data in a row
than will fit into this buffer. In these cases you will have
to use BOX, NCOUNT, BDROP, and EDROP to reduce the amount of
data to be written out. In most cases it will be easier to
choose the columns and array ranges that you want to export
in AIPS rather than filter out the unwanted items in another
program anyway.

    If you use DOHMS to write times in hh:mm:ss form then,
few, if any, programs will recognize the output times as
anything other than arbitrary character strings. Be prepared
to do some work with PERL or some equaivalent tool if you
want the destination program to recognize them as dates.
You will probably find it easier to export times as
fractional days by setting DOHMS to false.

    Logical values and values from bit-field columns are
written out using the strings 'true' and 'false'. It is
possible that you may have to globally edit these in order
for the destination program to recognize them as logical
constants.

3. Using EXTAB as a Paraform Task

    EXTAB separates the logic of selecting the table data and
reading the data from the presentation of that data in the
output file. It can therefore be used as a paraform task for
writing out table data in other text-based formats.

    All of the routines that deal with the presentation of the
output data begin with the two letters OF. These are the
routines which would need to be modified to change the output
format.

    Each column type has a particular routine that governs how
its values are written out and a constant in the local include
file at the top of the program that gives the maximum width of
an item of data. If you just wish to change the way in which
one or more of the data items are represented while preserving
the general arrangement that one table row corresponds to one
line of output then you only need to change these routines
and the corresponding constants. The relevant routines and
constants are shown below.

Column Type            Formatting Routine        Constant
-----------            ------------------        --------
double-precision             OFWRDP               OFDPWD
single-precision             OFWRSP               OFSPWD
character string             OFWRST                None
integer                      OFWRIN               OFINWD
logical                      OFWRLG               OFLGWD
time (hh:mm:ss)              OFWRTM               OFTMWD

If you wish to add extra characters (e.g. quotation marks)
before or after string values then you will also need to
change the calculation of the column width in OFINIT.

    If you wish to add extra text at the beginning or end of
a table row then you will need to change OFSROW (called when
starting a row) or OFFROW (called when finishing a row) and
take the extra text into account when testing whether the
row data will fit in the output buffer in OFINIT.

    More extensive changes to the output format may require
changes to OFINIT (opens the output file and checks for
potential problems with the length of the output buffer),
OFTITL (writes out the column titles), and OFFINI (closes
the file).
