.help fmerge Feb92 ftools.futils
.ih
NAME
fmerge -- Merge common columns in two or more FITS file extensions.
.ih
USAGE
fmerge infiles[ext#] outfile columns
.ih
DESCRIPTION
This task merges 2 or more separate FITS tables
by appending all the rows from the separate tables in to one output FITS
table.
Only the columns specified by the 'columns' parameter will be copied to
the output file, and those columns must exist in all the input tables.
All additional header keywords from the first input
file are copied to the new FITS file, as are most of the additional keywords
in the extension header of the first file. (See the 'copyprime' parameter).
Requested keywords from the last file are updated or added to the output
file.  (See the 'lastkey' parameter.)
A history record will be added for each appended file.  (See the 'history'
parameter.)

The data in the output table will be scaled according to the
TSCALn and TZEROn values specified in the first input table, if any.
Also, the value(s) used to define null values will be as specified in
the first input file.
If a different null value is specified in a later input file, then a
warning message will be issued.
.ih
PARAMETERS
.ls infiles [string]
The file names and extensions of the FITS tables to be merged.  Use
@filename to specify the name of an ASCII file containing a list
of file names.
.le
.ls outfile [filename]
The name of the FITS file to be created containing the merged rows from
all the input FITS files.  If preceeded by a !, an existing file of the
same name will be overwritten.
.le
.ls columns [string]
Name(s) of columns to be included in the output table.
These column names must exist in all the input files (case is NOT significant).
Use @filename to input a file containing a list of column names.
.le
.ls (mextname = " ") [string]
The name of the output merged extension.  If a blank is specified (the default),
the extension name of the first input file will be used.
.le
.ls (copyprime=yes) [boolean]
If true, all of the primary header keywords, the primary array (if
any), and most of the extension keywords of the first input file are
copied to the output file.  If false, only minimal headers are
created.  Copyprime=yes does not copy the following keywords from an
extension (but some are replaced automatically): SIMPLE, BITPIX,
NAXIS, NAXISn, EXTEND, XTENSION, EXTNAME, PCOUNT, GCOUNT, TFIELDS,
TTYPEn, TBCOLn, TFORMn, TSCALn, TZEROn, TNULLn, TUNITn, THEAP, TDIMn,
TDISPn, GROUPS, BSCALE, BZERO, BUNIT, BLANK, CTYPEn, CRPIXn, CROTAn,
CRVALn, CDELTn, TLMINn, TLMAXn, OPTICn, TCRPXn, TCRVLn, TCDLTn,
TCTYPn, TCDnnnn, TCROTn, PLTSCLn, END
.le
.ls (lastkey=' ') [string]
A list of keys in the last input file to be updated or added to the output
file.  If the first character is an '@', the following string will be taken to
be a file.  In the file, any number of keyword can be specified, one per line.
If the specified key exists, its value will be updated.  If not, a
new keyword will be written.
.le
.ls (history=yes) [boolean]
If true, history records will be added to the output file primary header
indicating that FMERGE created the file, and history records of each input file
will be added to the extension header.
.le
.ls (clobber = no) [boolean]
If true, an existing file of the same name as the requested output file
will be overwritten.
.le
.ih
EXAMPLES
1.  Merge the rate and pha columns in the third extension of the FITS file
test.fit with the first extensions of the
FITS files test1.fit and test2.fit and write the merged
rows in the output file merged.fit.  Update the TIME-END keyword with the
value from test2.fits:

  ft> fmerge "test.fit[3] test1.fit test2.fit" merged.fit "rate,pha" lastkey=TIME-END

.fi
.ih
BUGS
.ih
SEE ALSO
ftmerge, ftappend, ftlist, ftcopy
.endhelp
