FMERGE (Feb92)                ftools.futils               FMERGE (Feb92)



NAME
    fmerge -- Merge common columns in two or more FITS file extensions.
    
    
USAGE
    fmerge infiles[ext#] outfile columns
    
    
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.
    
    
PARAMETERS
    
    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.
    
    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.
    
    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, or use a single space (" ") or a hyphen ("-")
        to select all columns.
        
    
    (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.
    
    (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
    
    (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.
    
    (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.
    
    (clobber = no) [boolean]
        If true, an existing file of the  same  name  as  the  requested
        output file will be overwritten.
    
    
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
    
    
    
BUGS
    
    
SEE ALSO
    ftmerge, ftappend, ftlist, ftcopy