.help txtable Jan97 tables
.ih
NAME
txtable -- Extract rows from a 3-D table into separate 2-D tables.
.ih
USAGE
txtable intable outtable
.ih
DESCRIPTION
This task extracts one or more rows from a 3-D table and writes each row
as a 2-D table. The input may be a filename template, including 
wildcard characters, or the name of a file (preceded by an @ sign) containing 
table names.  The output may be either a directory specification or a list 
of table names. If the output is a list of tables then there must be the same 
number of names in the input and output lists, and the names are taken in 
pairs, one from input and one from output. The input and output tables must 
not be the same.

This task supports row/column selectors in the input table name. These
may be used to select subsets of both rows and columns from the input table.
If no selectors are used, all columns will be extracted, and the number
of output tables will be the number of rows in the input table.
Type 'help selectors' to see a description of the selector syntax. 

Since one input table may generate several output tables, the task adopts
the following naming scheme for these output tables: their names are
built by appending a suffix to the name given in parameter "outtable".
The suffix has the form "_rXXXX", where XXXX stands for the row number 
in the input table. The suffix is appended before the file name extension.
The task recognizes as valid table name extensions the values ".tab",
".fits" and ".fit". Any other extension is assumed to be part of the root
file name. If only one row is extracted, or in case of ASCII output, no 
suffixing takes place.

NOTE: Be careful when using a wildcard for the extension.
If you have the files "table.tab" and "table.lis" in the current directory,
for example, then the command "txtable tab* test/" would expand both files 
to the subdirectory "test".

There are two forms of handling scalar columns in the input table. If
task parameter "compact" is set to 'no', the corresponding column in the
output table will have the scalar value in its first row, and all other
rows will be filled with INDEF. If parameter "compact" is set to 'yes',
scalar columns will be written into the header as a set of header keywords.
These keywords can be used later by task 'titable' to re-insert the
scalars as cell elements of a 3-D table.

The task does not propagate array dimensionality when extracting arrays
into columns in the output table. If dimensionality information exists
in the 3-D table, that information is lost, that is, the table cell from
the input table is written as a structureless, plain table column.

The input row number is written to the header of the output table in
keyword ORIG_ROW. This allows 'titable' to put the data back where 
'txtable' got them from.
.ih
PARAMETERS
.ls intable [file name list/template]
A list of one or more tables to be expanded. Row/column selectors are supported.
.le
.ls outtable [file name template]
Either a directory name or a list of output table names. The standard
value "STDOUT" generates ASCII output that can be redirected to a file.
.le
.ls (compact = yes) [boolean]
Write scalars as header keywords ?
.le
.ls (verbose = yes) [boolean]
Display names of input and output tables as files are processed ?
.le
.ih
EXAMPLES
Extract columns named FLUX and WAVELENGTH from rows 11 to 13 of a 3-D table:

.nf
cl> txtable "table.tab[c:FLUX,WAVELENGTH][r:row=(11:13)]" tableout
.fi

This will generate three tables named "tableout_r0011", "tableout_r0012"
and "tableout_r0013".
.ih
BUGS
.ih
REFERENCES
This task was written by I. Busko.
.ih
SEE ALSO
titable, selectors
.endhelp
