.help ffilecat Nov92 ftools.futils
.ih
NAME
ffilecat  --  Finds the values of keywords in a series of input files,
and puts them into a binary fits table 
.ih
USAGE
ffilecat  infile outfile keywords
.ih
DESCRIPTION
This task makes a catalog, in the form of a binary fits file, from the
list of files given in the 'infile' parameter.  The name of the catalog file
is 'outfile'.   The first column of the
catalog contains the filenames, the second, the extension numbers.  The rest
of the columns contain the values of the keywords given in the parameter 
'keywords', with the value from each file appearing in the row labeled in the
first column by its filename.  If the outfile already exists, 
it will append the values to this existing table, using the column names 
for the keyword names if the keyword variable is blank.  If it is not, 
then the keywords are taken from this variable, and put into the columns in the 
order in which they appear in the keywords variable.  
In either case, the 
keyword values are checked to make sure they have the same type as the 
column to which they are assigned in outfile.  If the parameter omit is 
set to true, the whole input file row is omitted in case of type 
mismatches.   Otherwise, the value is set to undefined.   
If the outfile does not exist, then one is created.  The column types are 
set based on the types of
the values in the input files.  If  all the values for a single keyword 
are not of the same type, then the 
column is set to a character type.  If one of the keywords does not exist 
in one of the input files, then its value in the outfile is set to undefined, 
unless omit is set to true, in which case the line is omitted.
.ih
PARAMETERS
.ls infile [string]
The list of file names from which to get the keyword values, separated by 
spaces.  They are 
assumed to be in BINTABLE format.  If the first character is '@', the
rest of the string is taken to be a filename in which the input files are 
listed, one filename per line.
.le	
.ls outfile [filename]
The name of the output binary FITS table.  Data can be appended to any 
existing extension of an outfile, but ffilecat will not append a  new 
extension onto an existing file.
.le		
.ls keywords [string]
List of keywords to search for, separated by spaces.  If the first character 
is '@', the rest of the string is taken to be a filename in which the 
input files are listed, one filename per line.  
.le		
.ls (maxlen = 20) [integer]
This is the minimum length chosen for string columns, when the outfile
doesn't already exist.  If any of the values for the keyword are longer 
than maxlen, the column is defined to be the longest of them.
.le		
.ls (minlen = 0) [integer]
If minlen is non-zero, then all character strings are truncated at minlen
characters.  This overrides maxlen.
.le
.ls (aform = "NONE") [string]
Controls the formatting of all character variables by writing a TDISP keyword,
whose value is the aform string.  Aform = NONE means write no TDISP keyword.
.le
.ls (eform = "NONE") [string]
Same as aform, but for all E columns.
.le
.ls (iform = "NONE") [string]
Same as aform, but for all I and J columns.
.le
.ls (omit=no) [logical]
If true, then any infile which does not contain all the keywords,
or which contains some invalid data types, is omitted.  If it is set to
false, then these values are set to undefined.
.le		
.ls (quiet=no) [logical]
If true, then the error messages for most non-fatal errors are suppressed.
.le

.ih
EXAMPLES
.nf
1.	Put the values of the keywords "NAXIS" and "NAXIS2" from the files
	"one.fits", and "two.fits", into the file "out.fits": 
		
	ft> ffilecat "one.fits two.fits" out.fits "NAXIS NAXIS2"
	
2.  Put the values of the keywords "NAXIS" and "NAXIS2" from a list of 
    files contained in the file "list.fil" (created, for example by using 
    'ls -1 *.fits> list.fil' in UNIX), the result is put in "out.fits",
    and all files with no values of "NAXIS" or "NAXIS2" are omitted
    
    ft> ffilecat "@list.fil" out.fits "NAXIS NAXIS2" omit=yes
.fi
.ih
BUGS
.ih
SEE ALSO
.endhelp


