Initial commit

1 files changed, 115 insertions, 0 deletions

diff --git a/pkg/utilities/nttools/doc/tquery.hlp b/pkg/utilities/nttools/doc/tquery.hlp
new file mode 100644
index 00000000..61857fd7
--- /dev/null
+++ b/pkg/utilities/nttools/doc/tquery.hlp
@@ -0,0 +1,115 @@
+.help tquery Jan1999 tables
+.ih
+NAME
+tquery -- Create a new table from selected rows and columns of an old table.
+.ih
+USAGE
+tquery intable outtable expr columns sort
+.ih
+DESCRIPTION
+This task combines the functions of the tasks 'tselect', 'tproject', and
+'tsort' to create a more powerful task that can produce a sorted table of
+user-selected rows and columns.
+It can be used whenever you want to do more than one of these operations
+without creating intermediate tables.  This task creates a new table
+containing a subset of the rows and columns in an old table.  The rows in the
+new table can be sorted on any column or combination of columns.  The select,
+project, and sort operations are controlled by the parameters 'expr',
+'columns', and 'sort',
+respectively.  If the value of any of these parameters is a null or
+blank string, the corresponding operation is not performed.  Otherwise, the rows
+are selected whenever the row meets the conditions defined by 'expr';
+columns are
+selected by the 'columns' parameter, and rows are
+sorted on the columns named in 'sort'.  The hidden parameter 'uniq' is used
+to eliminate duplicate rows from the output table.  The hidden parameter
+'ascend' sorts the table in ascending order, and the parameter 'casesens'
+specifies whether sort conditions are to be case sensitive.
+.ih
+PARAMETERS
+.ls intable [file name template]
+Table(s) from which rows are copied. If input is redirected, this
+parameter will ignored and input will be read from STDIN instead.
+.le
+.ls outtable [file name template]
+The new table(s) containing the copied rows.
+The number of output tables must equal the number of input tables.
+.le
+.ls expr [string]
+The boolean expression which determines which rows are copied to the new
+table.  The expression may be placed in a file and the name of the file
+preceeded by a '@' can be given in its place.  If the expression is null
+or blank, all rows are selected.  The syntax and method used to define
+this boolean expression is explained in detail in the help file for the
+'tselect' task (type "help tselect" for more information).
+.le
+.ls columns [string]
+Column template describing the columns that are to be selected
+from the old table. A column template consists of a list
+of column names, which can include wildcard characters.
+The column names, or patterns, are separated by commas or white space.
+The list of columns can be placed in a file and then
+the name of that file passed to 'columns' (preceded by
+the "@" character).  If the first non-white character in the template
+is the negation character (either "~" or "!"),
+the new table will contain those columns
+that do NOT match the column template. If the column template
+is null or blank, all columns will be selected.
+.le
+.ls sort [string]
+Column template describing the columns to be sorted.  The
+first column name is the primary sort key with subsequent columns
+used to break ties.  If this parameter
+is null or blank, no sort will be done.
+.le
+.ls (uniq = no) [boolean]
+Make sure all rows are unique in a table?
+
+If 'unique' is set to "yes", only one of each set of duplicate rows is included
+in the output table.  All columns in the output table must be identical for
+the row to be removed.  String comparisons are case sensitive.  Care should
+be used in setting this option for large tables, as it significantly increases
+the running time.
+.le
+.ls (ascend = yes) [boolean]
+Should sorts be performed in ascending order?
+
+If 'ascend = yes', the table is sorted in ascending order, with the first
+row containing the smallest value of the sorted column.  Otherwise, the table
+is sorted in descending order, with the largest value first.
+.le
+.ls (casesens = yes) [boolean]
+Are sort operations case sensitive?
+
+If 'casesens = yes', sorts on character columns are case sensitive, with upper
+case letters preceding lower case.  Otherwise, the sort is not case
+sensitive.
+.le
+.ih
+EXAMPLES
+1. Extract all binary stars from a catalog; write their names, magnitudes,
+and colors to a new table, sorted on magnitude:
+
+.nf
+tt> tquery starcat.tab binary.tab binary name,mag,color mag
+.fi
+
+2. Remove duplicate rows from a set of tables. Otherwise, leave the tables
+unchanged. Using file name editing (i.e., the "%" characters to delineate
+old strings and new strings), change the file name extensions from ".tab"
+to ".tbl".
+
+.nf
+tt> tquery *.tab *.%tab%tbl% "" "" "" uniq+
+.fi
+.ih
+BUGS
+Column names must be set off from operators by blanks in the expression so
+that they can be correctly parsed by the expression evaluator.
+.ih
+REFERENCES
+This task was written by Bernie Simon.
+.ih
+SEE ALSO
+tsort, tselect, tproject
+.endhelp