From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001
From: Joseph Hunkeler <jhunkeler@gmail.com>
Date: Wed, 8 Jul 2015 20:46:52 -0400
Subject: Initial commit

---
 pkg/utilities/nttools/threed/doc/titable.hlp | 100 +++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 pkg/utilities/nttools/threed/doc/titable.hlp

(limited to 'pkg/utilities/nttools/threed/doc/titable.hlp')

diff --git a/pkg/utilities/nttools/threed/doc/titable.hlp b/pkg/utilities/nttools/threed/doc/titable.hlp
new file mode 100644
index 00000000..f0479b6b
--- /dev/null
+++ b/pkg/utilities/nttools/threed/doc/titable.hlp
@@ -0,0 +1,100 @@
+.help titable Mar97 tables
+.ih
+NAME
+titable -- Inserts 2-D tables into rows of a 3-D table.
+.ih
+USAGE
+titable intable outtable
+.ih
+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.
+.ih
+PARAMETERS
+.ls intable [file name list/template]
+A list of one or more tables to be inserted. Row/column selectors are supported.
+.le
+.ls outtable [table name]
+Name of 3-D output table, including extension. No support exists for 
+"STDOUT" (ASCII output).
+.le
+.ls (template = "") [table name]
+Name of 3-D table to be used as template when creating a new output table.
+.le
+.ls (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.
+.le
+.ls (verbose = yes) [boolean]
+Display names of input and output tables as files are processed ?
+.le
+.ih
+EXAMPLES
+Insert columns named FLUX and WAVELENGTH from input tables into a 3-D table:
+
+.nf
+cl> titable "itable*.tab[c:FLUX,WAVELENGTH]" otable.tab
+.fi
+
+.ih
+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.
+.ih
+REFERENCES
+This task was written by I. Busko.
+.ih
+SEE ALSO
+txtable, selectors
+.endhelp
-- 
cgit 

