From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Wed, 8 Jul 2015 20:46:52 -0400 Subject: Initial commit --- pkg/utilities/nttools/doc/tainsert.hlp | 132 +++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 pkg/utilities/nttools/doc/tainsert.hlp (limited to 'pkg/utilities/nttools/doc/tainsert.hlp') diff --git a/pkg/utilities/nttools/doc/tainsert.hlp b/pkg/utilities/nttools/doc/tainsert.hlp new file mode 100644 index 00000000..3d07855b --- /dev/null +++ b/pkg/utilities/nttools/doc/tainsert.hlp @@ -0,0 +1,132 @@ +.help tainsert Jan98 tables +.nj +.ih +NAME +tainsert -- Copy a column of scalars from one table +to an array entry in another. +.ih +USAGE +tainsert intable outtable row column +.ih +DESCRIPTION +This task reads an entire column from one table +and inserts those values (presumably more than one) +at a specified row and column in an output table. +If the output table exists it will be written to in-place; +otherwise, it will be created. + +By default, the same column name is used in both tables. +If the column does not exist in the output table, the column will be created. +If the output table and the row and column already exist, +the array of values at that location will be overwritten. +The number of elements copied will be the minimum of +the number of input rows and the output column array size. +If the number of input rows is larger than the array size, +a warning message will be printed, +and the extra rows will be ignored. +If the number of input rows is smaller than the array size, +the remaining array elements will be set to INDEF. + +If the specified row number is less than one or is INDEF, +'tainsert' looks for the header keyword ORIG_ROW in the input table. +ORIG_ROW is written by 'taextract'. +If that keyword exists, its value is used as the row number. +.ih +PARAMETERS +.ls intable [file name] +Name of the input table. +.le +.ls outtable [file name] +Name of the output table. +If this table doesn't exist it will be created. +.le +.ls row = -1 [integer] +This is the row number in the output table. +The default means that 'tainsert' should use +the value of the header keyword ORIG_ROW. +.le +.ls column [string] +Column name in the input table and, by default, also in the output table. +If this column does not exist in the output table, it will be created, +and the array size will be set to the number of rows in the input table. +See the descriptions for 'outcolumn' and 'size', however. + +It is an error if this column in the input table contains array entries. +.le +.ls outcolumn = "" [string] +If 'outcolumn' is specified, +that name will be used for the output table; +otherwise, 'column' will be used for both input and output tables. +This provides an easier way to change the name of the output column +than by running 'tchcol' after running 'taextract'. +Note that if 'outcolumn' is specified, +it is used not only for finding the column in the output table +but also for creating the column if it wasn't found. +The 'size', 'datatype', 'colunits', and 'colfmt' parameters, +by contrast, are only used when creating a new column. +.le +.ls (size = INDEF) [int] +When creating a new column in the output table, +the default is for the array size of that column to be set to +the number of rows in the input table. +This may be overridden by specifying a value for 'size'. +If 'size' is a positive integer, not INDEF, +this will be used as the array size when creating the new column. +.le +.ls (datatype = "") [string] +When creating a new column in the output table, +the default is to use the same data type as the column in the input table. +However, if 'datatype' is specified (i.e. not null or blank), +this will be used as the data type when creating the new column. +For numeric and boolean columns, only the first character is used: +"r" and "d" for single and double precision floating point, +"s" and "i" for short integer and integer, +"b" for boolean. +For a character string of maximum length 12 (for example), use "ch*12". +.le +.ls (colunits = "") [string] +When creating a new column in the output table, +the units will be set to 'colunits' if it has been specified; +otherwise, the units will be copied from the column in the input table. +.le +.ls (colfmt = "") [string] +When creating a new column in the output table, +the print format will be set to 'colfmt' if it has been specified; +otherwise, the print format will be copied from the column in the input table. +.le +.ih +EXAMPLES +1. Copy the entire column "polar" from table "scalar.tab", +and insert the values into row 5, column "polar", of table "array.tab". +If "array.tab" does not exist it will be created. +If column "polar" does not exist in "array.tab", +that column will be created. + +.nf +at> tainsert scalar.tab array.tab 5 polar +.fi + +2. Copy the arrays from row 5, columns "wavelength" and "flux", +from "array.tab" to a temporary table, +sort them on the wavelength, +and insert them back where they came from. + +.nf +at> taextract array temp 5 wavelength +at> taextract array temp 5 flux +at> tsort temp wavelength +at> tainsert temp array 0 wavelength +at> tainsert temp array 0 flux +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Phil Hodge. +.ih +SEE ALSO +taextract + +Type "help ttools opt=sysdoc" for a higher-level description of the 'ttools' +package. +.endhelp -- cgit