AIPS HELP file for EXTAB in 31DEC24
As of Thu Apr 25 20:45:26 2024
EXTAB: Task to export AIPS table data as tab-separated text
INPUTS
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.
HELP SECTION
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.
EXPLAIN SECTION
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).