; EXTAB ;--------------------------------------------------------------- ;! exports AIPS table data as tab-separated text ;# Task Table Plot ;----------------------------------------------------------------------- ;; Copyright (C) 1999, 2008 ;; 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).