titable: Insert 2-D tables into rows of a 3-D table.

Package: nttools

Usage

titable intable outtable

Description

This task performs the inverse operation of task txtable: it inserts one or more 2-D tables into rows of a 3-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 is a single 3-D table name. If the output table exists, insertion will be done in place. If the output table does not exist, it will be created. The input and output tables must not be the same.

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

When creating a new output table, the information describing its columns can be taken from two sources. If parameter 'template' has the name of an existing 3-D table, the column descriptions, including maximum array sizes, will be taken from that table. If 'template' has an invalid or null ("") value, the column-defining information will be take from the first table in the input list, where its number of rows will define the maximum array size allowed in the table being created. Column selectors are allowed in the template table.

NOTE: Both the output and template table names must always be supplied complete, including their extension. Otherwise the task may get confused on the existence of an already existing table.

Insertion is performed by first verifying if column names in both input and output tables match. If a match is found, values taken from that column and all selected rows from the input table will be stored as a 1-dimensional array in a single cell in the corresponding column in the output 3-D table. The row in this table where the insertion takes place is selected by the "row" task parameter. It points to the row where the first table in the input list will be inserted, subsequent tables in the list will be inserted into subsequent rows. This mechanism is superseded if the "row" parameter is set to INDEF or a negative value, and the keyword "ORIG_ROW" is found in the header of the input table. This keyword is created by task txtable and its value supersedes the row counter in the task.

If the maximum array size in a target column in the output 3-D table is larger than the number of selected input rows, the array will be filled up starting from its first element, and the empty elements at the end will be set to INDEF (or "" if it is a character string column). If the maximum array size is smaller than the number of selected rows, insertion begins by the first selected row up to the maximum allowable size, the remaining rows being ignored.

This task correctly handles scalars stored in the input table header by task txtable. Since the selector mechanism does not work with these scalars, the task will always insert them into the output table, provided there is a match in column names.

Parameters

intable [file name list/template]: A list of one or more tables to be inserted. Row/column selectors are supported.

outtable [table name]: Name of 3-D output table, including extension. No support exists for "STDOUT" (ASCII output).

(template = "") [table name]: Name of 3-D table to be used as template when creating a new output table.

(row = INDEF) [int]: Row where insertion begins. If set to INDEF or a negative value, the row number will be looked for in the input table header.

(verbose = yes) [boolean]: Display names of input and output tables as files are processed ?

Examples

Insert columns named FLUX and WAVELENGTH from input tables into a 3-D table:

cl> titable "itable*.tab[c:FLUX,WAVELENGTH]" otable.tab

Bugs

The output and template table names must be supplied in full, including the extension (e.g. ".tab"). If the output table name is not typed in full, the task will create a new table in place of the existing one, with only the rows actually inserted. This behavior relates to the way the underlying "access" routine in IRAF's fio library works.

References

This task was written by I. Busko.