Initial commit

1 files changed, 167 insertions, 0 deletions

diff --git a/noao/digiphot/ptools/doc/txdump.hlp b/noao/digiphot/ptools/doc/txdump.hlp
new file mode 100644
index 00000000..bd432afb
--- /dev/null
+++ b/noao/digiphot/ptools/doc/txdump.hlp
@@ -0,0 +1,167 @@
+.help txdump Aug91 noao.digiphot.ptools
+.ih
+NAME
+txdump - print fields from selected records in an APPHOT/DAOPHOT text database
+.ih
+USAGE
+txdump textfiles fields expr
+.ih
+PARAMETERS
+.ls textfiles
+The APPHOT/DAOPHOT text database whose fields from selected records are to
+be printed.
+.le
+.ls fields
+A template defining the fields to be printed from each selected record.
+The fields are specified by keywords defined in the text database output
+files #K and #N entries. Upper or lower case and minimum match
+abbreviations are permissible. Some fields such as "mag" may have
+multiple entries. An individual entry can be referenced by specifying an
+array index, e.g. "mag[2]" or several values can be selected by
+specifying a range of elements, e.g. "mag[1-3]". The fields are output in
+the order in which they are specified in the 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 fields in all the records are
+printed.
+.le
+.ls headers = no
+Preserve the APPHOT/DAOPHOT text database output format. The selected
+fields are printed on the standard output, preceded by parameters list,
+if \fIparameters\fR = yes, and the keyword, units,
+and format information, exactly as they appear in the text database.
+.le
+.ls parameters = yes
+Print the keyword parameters records in APPHOT/DAOPHOT format on the
+standard output if \fIheaders\fR = yes.
+.le
+
+.ih
+DESCRIPTION
+\fITXDUMP\fR selects a subset of fields specified by the \fIfields\fR
+parameter from an APPHOT/DAOPHOT text database or a list of databases by
+evaluating a boolean expression supplied by the user and prints the
+results on the standard output.
+If \fIheaders\fR = no, the resultant output is in simple list format
+with all the specified fields in one line of text and adjacent fields
+separated by whitespace. The fields are printed in the order in
+which they appear in \fIexpr\fR. If \fIheaders\fR = yes, the
+selected fields are printed on the standard output, preceded by
+the parameter list, if \fIparameters\fR = yes, and the keyword, units,
+and format information, exactly as they appear in the text database.
+Newlines will not be inserted in the output so users should take
+care not to exceed the IRAF text file line limit of 161 characters.
+
+The output records are selected on the basis of an input boolean
+expression \fIexpr\fR whose variables are the field names
+specified by the #N keywords or the parameters specified by the
+#K keywords in the APPHOT/DAOPHOT text database.
+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
+
+1. Print the fields XCENTER and YCENTER from the output of the APPHOT
+CENTER task.
+
+.nf
+	pt> txdump image.ctr.1 XCENTER,YCENTER yes
+.fi
+
+2. Select the fields ID, XCENTER, YCENTER and the first three magnitudes
+MAG{1-3] from the output of the APPHOT PHOT task.
+
+.nf
+	pt> txdump image.mag.2 "ID,XCEN,YCEN,MAG[1-3]" yes
+.fi
+
+3. Print all fields for all records in the above file with a magnitude
+through the first aperture of less than 20.0.
+
+.nf
+	pt> txdump image.mag.2 * "MAG[1] < 20.0"
+.fi
+
+4. Print the id and all magnitudes for which magnitudes 1 and 2 are < 20.0
+from a file which is the output of the APPHOT PHOT task.
+
+.nf
+	pt> txdump image.mag.3 ID,MAG "MAG[1] < 20.0 && MAG[2] < 20.0"
+.fi
+
+5. Select the ID, XCENTER, YCENTER, MSKY and MAG fields from the output
+   of the DAOPHOT NSTAR task for records where the magnitude is not
+   INDEF, while preserving the format of the text database so it
+   is suitable for input into a rerun of NSTAR.
+
+.nf
+	pt> txdump image.nst.1 "ID,XCENTER,YCENTER,MSKY,MAG"  \
+	    "MAG[1] != INDEF" headers+
+.fi
+
+.ih
+BUGS
+TXDUMP does not allow arrays in the expression field.
+
+Users should not dump more fields than fill a 161 character textline
+as IRAF does not currently fully support longer text lines.
+.ih
+SEE ALSO
+images.hedit,ptools.tbdump,tables.tdump,ptools.pdump
+.endhelp