Initial commit

1 files changed, 147 insertions, 0 deletions

diff --git a/pkg/utilities/nttools/doc/tselect.hlp b/pkg/utilities/nttools/doc/tselect.hlp
new file mode 100644
index 00000000..56299faa
--- /dev/null
+++ b/pkg/utilities/nttools/doc/tselect.hlp
@@ -0,0 +1,147 @@
+.help tselect Jul92 tables
+.ih
+NAME
+tselect -- Create a new table from selected rows of an old table.
+.ih
+USAGE
+tselect intable outtable expr
+.ih
+DESCRIPTION
+This task creates a new table from a subset of rows in an input table.  
+The rows are selected on the basis of a boolean expression whose
+variables are table column names.  If, after substituting the values associated
+with a particular row into the column name variables, the expression evaluates
+to yes, that row is included in the output table.  Boolean operators can be used
+in the expression in either their Fortran or SPP forms.  The following boolean
+operators can be used in the expression: 
+
+.nf
+equal		.eq.  ==	not equal		.ne.  !=
+less than	.lt.  <		less than or equal	.le.  <=
+greater than	.gt.  >		greater than or equal	.ge.  >=
+or		.or.  ||	and			.and. &&
+negation	.not. !		pattern match		      ?=
+.fi
+
+The pattern match operator (?=) has no corresponding Fortran form.  It takes a
+string expression as its first argument and a pattern as its second argument.
+The result is "yes" if the pattern is contained in the string expression.
+Patterns are strings which may contain meta-characters (i.e., wildcard 
+characters used in pattern matching).
+The meta-characters themselves can be matched by preceeding them with the escape
+character (\).
+The meta-characters are: 
+
+.nf
+beginning of string	^	end of string		$
+one character		?	zero or more characters	*
+white space		#	escape character	\
+begin ignoring case	{	end ignore case		}
+begin character class	[	end character class	]
+not, in char class	^	range, in char class	-
+.fi
+
+The expression may also include arithmetic operators and functions.
+Trigonometric functions use degrees, not radians.  The following arithmetic
+operators and functions can be used in the expression:
+
+.nf
+addition		+	subtraction		-
+multiplication		*	division		/
+negation		-	exponentiation		**
+concatenation		//	date difference		delta(x,y)
+absolute value		abs(x)	cosine			cos(x)
+sine			sin(x)	tangent			tan(x)
+arc cosine		acos(x)	arc sine		asin(x)
+arc tangent		atan(x)	arc tangent		atan2(x,y)
+exponential		exp(x)	square root		sqrt(x)
+natural log		log(x)	common log		log10(x)
+modulo			mod(x)	minimum			min(x,y)
+row number		row()	maximum			max(x,y)
+nearest integer		nint(x)	convert to integer	int(x)
+convert to real		real(x) convert to string	str(x)
+.fi
+
+The row number function returns an integer value corresponding to the
+row number in the table.  The date difference function returns a real
+value corresponding to the Julian date of the first argument minus the
+Julian date of the second argument; the arguments to the data function
+must be in CDBS date format:  i.e., character strings of the form
+YYYYMMDD:HHMMSSCC.  Any field after the colon is optional.  The last
+date field (CC) is hundreths of a second.
+
+One concept in most databases and in STSDAS tables is the concept of a
+null value: a value which indicates that the element is unknown or
+non-existent.  An element in an STSDAS table is null if it is INDEF in a
+numeric column or a zero length string in a text column. Evaluating
+expressions involving nulls requires a three valued logic:  true,
+false, and unknown. Any arithmetic operation on a null element should
+return another null and any comparison operation should return an
+unknown.  Unfortunately, tselect does not implement a true three
+valued logic correctly.  The code instead evaluates any expression
+containing a null element as unknown.  Since tselect only returns rows
+for which the expression is true, all such rows are excluded from the
+output of tselect.  This is usually right, but sometimes wrong, as in
+the case where two comparisons are joined by an or and one evaluates
+to true and the other evaluates to unknown.  It also sometimes returns
+nonintuitive results, as when checking that a column is not equal to
+INDEF.
+.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.
+If more than one input table was used, then 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 list file and the name of the file
+passed to this parameter (preceded by the "@" character).
+.le
+.ih
+EXAMPLES
+1. Extract all binary stars brighter than fifth magnitude from a catalog:
+
+.nf
+tt> tselect starcat.tab binary.tab "binary && mag <= 5."
+.fi
+
+2. Create a new set of spectra where all measurements with errors greater
+than ten percent are excluded. Use file name editing to create new tables
+with the extension ".tbl" instead of ".tab":
+
+.nf
+tt> tselect  *.tab  *.%tab%tbl%  "ERROR / (FLUX + .001) < .1"
+.fi
+
+3. Create a table of engineering parameters whose names begin with a digit:
+
+.nf
+tt> tselect datalog.tab sublog.tab "name ?= '^[0-9]'"
+.fi
+
+4. Return all observations in a schedule for the day of Dec 31, 1989:
+
+.nf
+tt> tselect schedule.tab week.tab "abs(delta(date,'19891231:12'))<.5"
+.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.  Expressions involving nulls may evaluate incorrectly, see
+above for a discussion.
+.ih
+REFERENCES
+This task was written by Bernie Simon.
+.ih
+SEE ALSO
+tproject, tjoin, tproduct
+
+Type "help tables opt=sys" for a higher-level description of the 'tables' 
+package.
+.endhelp