.help flookup June93 ftools.futils
.ih
NAME
flookup -- Create a new FITS file from selection based on a lookup table
.ih
USAGE
flookup infile[ext#] outfile lookup
.ih
DESCRIPTION
This task creates a new table based on the criteria specified in a 
lookup table.  Based on the value of each row's element in the
column specified by the tcolumn parameter, the upper and lower bounds of
acceptable value of "column" are found in the lookup table.  Depending on
the value of the "bounds" parameter, all rows with values 
satisfying the requested condition
are copied to the output file.  Single value lookups are specified by
setting the ubcol parameter equal to a blank or a '-'.

The bounds parameter is used to describe the condition between the 
upper and lower bounds in the lookup table, and the condition column
in the input file.  In this parameter a parenthesis specifies that
the value of the bound in NOT included in the condition, and a square
bracket means that the value IS included.  Further, the direction of
the parenthesis or bracket indicates the position of the table condition
column value with respect to the lower or upper bound column value.
This is best described with examples:
.nf
	condition		       bounds
lbcol < column < ubcol			()
column < lbcol or column > ubcol	)(
lbcol <= column <= ubcol		[]
column < lbcol or column >= ubcol	)[
lbcol < column				(
column <= lbcol				]
lbcol = column				[]
lbcol <> column				)(
.fi

.ih
PARAMETERS
.ls infile [filename]
A file name (including optional extension number in square brackets) of the 
FITS table to be searched.
.le
.ls outfile [filename]
The name of the created  FITS file to contain the selected rows from the
input table.  If preceeded by a !, an existing file of the same name
will be overwritten.
.le
.ls lookup [filename]
The name (and extension) of the lookup table.
.le
.ls tcolumn = "PHA" [string]
The name of the column that is the key to the lookup table.
.le
.ls lcolumn = "CHAN" [string]
The name of the column in the lookup table corresponding to tcolumn.
This column must be in ascending order.
.le
.ls lbcol = "RTI_MIN" [string]
The name of the column in the lookup table containing the lower bound.
.le
.ls ubcol = "RTI_MAX"  [string]
The name of the column in the lookup table containing the upper bound.
If this parameter is blank or '-', only a single value lookup is performed.
See the description above for details on the specification.
.le
.ls column = "RTI" [string]
The name of the column in the input file to be compared.
.le
.ls bounds = "()" [string]
This parameter specifies the condition to be tested 
and whether the bounds of the condition include the
value of lbcol and/or ubcol.  See the description above for details.
.le
.ls (history = yes) [boolean]
If true, history records will be added to the output file primary header
indicating that FLOOKUP created the file, and another
will be added to the extension header.
.le
.ls (copyall = yes) [boolean]
If true, all other extensions, including the primary array are copied
to the output file.
.le
.ls (copyprime = no) [boolean]
If true, and if copyall is false, only the primary array is copied to the
output file.
.le
.ls (clobber = no) [boolean]
If true, an existing file with the same name as the requested output file
will be overwritten.
.le
.ih
EXAMPLES
.fi
.ih
NOTES:
This program is currently optimized for lookup table keys 
that are one
value apart (i.e. 1,2,3) and 1024 elements or less.

Rows containing null values in either the key column or the comparison
column are never copied to the output file.
BUGS
.ih
SEE ALSO
fselect
.endhelp
