.help tbdump Feb93 noao.digiphot.ptools
.ih
NAME
tbdump -- print fields (columns) from a list of  APPHOT/DAOPHOT STSDAS table
	  databases
.ih
USAGE
tbdump tables columns expr
.ih
PARAMETERS
.ls tables
The name of the APPHOT/DAOPHOT table database(s) to be dumped.
.le
.ls columns
The template specifying the names of the columns to be dumped.
A null or blank string means
dump all columns.  A column template consists of a list
of either column names or column patterns containing the usual pattern matching
meta-characters.  The names or patterns are separated by commas or white space.
Column names must be spelled in full but may be upper or lower case.
The columns list can be placed in a file and the name of the file preceded
by an '@' character given in place of the column template.
If the first non-white character in the column template
is the negation character '~', the output will contain those columns
NOT named in the remainder of the column template.
.le
.ls expr
The boolean expression to be evaluated once per record.
Only the fields in those records for which the boolean expression
evaluates to yes are printed.
If \fIexpr\fR = "yes", the specified columns in all the records are
printed.
.le
.ls datafile = STDOUT
If \fIDatafile\fR is not null ("") then the table data will be written
to an output file with this name. By default the table data is written
on the standard output.
\fIDatafile\fR will not be created if the table is empty.
.le
.ls cdfile = ""
If \fICdfile\fR is not null ("") then the column definitions will be written
to an output file with this name.
The column definitions consist of the column name, data type (R, D, I, B,
or C), print format, and units.
.le
.ls pfile = ""
If \fIPfile\fR is not null ("") then the header parameters will be written
to an output file with this name.
\fIPfile\fR will not be created if there are no header parameters.
.le
.ls rows = "-"
\fIRows\fR is a string which may be used to specify ranges of rows which are
to be dumped.  The default of "-" means dump all rows.  The first
ten rows could be specified as \fIrows\fR = "1-10" or just \fIrows\fR = "-10".
To dump the first ten rows and all rows from 900 through the last,
use \fIrows\fR = "-10,900-".  \fIRows\fR = "1,3,7,23" will print only
those four rows.  It is not an error to specify rows larger than the largest
row number as they will simply be ignored.
See the help for RANGES in XTOOLS for further information.
.le
.ls pagwidth = 158
The width of the output for printing the table data.  If any of the columns
to be printed is wider than this an error message will be displayed, and
the data will not be dumped.  The width of each character column is
increased by two to include a pair of enclosing quotes.
.le
.ih
DESCRIPTION
This task converts selected records from an APPHOT/DAOPHOT STSDAS table
database to ASCII format
and by default prints the result on the standard output.
TBDUMP  output does not include row numbers or column names.
The TABLES package task TPRINT can be used for more readable output.

The PTOOLS version of TBDUMP described here is 
actually a combination of the STSDAS TABLES package tasks TSELECT and TDUMP.

The three primary uses for TBDUMP are to format STSDAS tables for input to
applications
which expect simple text input, allow editing that would be
difficult or impossible with the TABLES package TEDIT task, such as
global substitutions,
and facilitate copying a table over a network to another computer.
For the latter two applications the table can be dumped to three separate files
containing column definitions, header parameters, and table data,
edited, column data types changed, etc.
The TABLES package TCREATE can be used to create a new table from the three
ASCII files produced by TBDUMP.
By default only the column data is dumped.

TBDUMP queries for the columns to be dumped. If \fIcolumns\fR is null ("")
then all the columns are dumped.
All the rows are dumped by default, but ranges of
rows may be specified with the \fIrows\fR parameter.
If the table is wider than will fit on a page,
the output will consist of more than one line per row of the table,
but all the columns will be printed before moving on to the next row.
This is in contrast to TPRINT,
which prints all rows for those columns that will fit on a page,
then prints all rows for the next set of columns, etc.
Character columns with multiple words are printed with enclosing quotes.

The TABLES package TLCOL task (with TLCOL.NLIST=1) may be used to generate
a list of
column names so there is no question about spelling or case.  This list may
be edited to rearrange the names and/or delete some, the list
file preceded by an '@' and used as the value of the \fIcolumns\fR
parameter.

The output records are selected on the basis of an input boolean
expression \fIexpr\fR whose variables are the tables column names.
If after substituting the values associated
with a particular record into the field name variables the
expression evaluates
to yes, that record is included in the output table.

The supported
operators and functions are briefly described below. A detailed description
of the boolean expression evaluator and its syntax can be found
in the manual page for the IMAGES package HEDIT task.

The following logical operators can be used in the boolean expression. 

.nf
	equal		  ==	not equal		!=
	less than	  <	less than or equal	<=
	greater than	  >	greater than or equal	>=
	or		  ||	and			&&
	negation	  !	pattern match		?=
	concatenation	  //
.fi

The pattern match character ?=  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 pattern matching meta-characters.
The meta-characters themselves can be matched by preceeding them with the escape
character.  The meta-characters listed below. 

.nf
	beginning of string	^	end of string		$
	one character		?	zero or more characters	*
	white space		#	escape character	\
	ignore 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.
The following arithmetic operators and functions are supported.

.nf
addition		+		subtraction		-
multiplication		*		division		/
negation		-		exponentiation		**
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)
minimum			min(x,y)	maximum			max(x,y)
convert to integer	int(x)		convert to real		real(x)
nearest integer		nint(x)		modulo			mod(x)
.fi
.ih
EXAMPLES
.nf
1. Dump the "ID", "MAG" and "MAGERR" columns of the DAOPHOT package NSTAR
output to the standard output.

    pt> tbdump n4147.nst.1 "ID,MAG,MAGERR" yes

2. Dump the "ID", "MAG", and "MAGERR" columns of the above file for records
which have  "MAG <= 20.0".

    pt> tbdump n4147.nst.1 "ID,MAG,MAGERR" "MAG <= 20.0"

3. Dump the "MAG" and "MAGERR" columns of the above file and pipe the
result to graph.

    pt> tbdump n4147.nst.1 "MAG,MAGERR" yes | graph STDIN

4.  Dump all the columns in the first 100 rows of the above file.

    pt> tbdump n4147.nst.1 "" yes rows="1-100"
.fi
.ih
BUGS
.ih
SEE ALSO
tables.tdump,tables.tprint,tables.tlcol,tables.tcreate,ptools.txdump,ptools.pdump
.endhelp