.help faddcol Sep95 ftools.futils
.ih
NAME
faddcol -- copies a list of columns from one FITS table extension to another.
.ih
USAGE
faddcol infile colfile colname
.ih
DESCRIPTION
This task copies a specified list of columns from one FITS binary or
ASCII table to another.  The 2 FITS tables must be of the same type
(ASCII or binary) and have the same number of rows.  The input target
file is updated in place so it would be prudent to make a copy of the
input file before running this task, in the event that it does not
complete successfully and leaves the file in a corrupted state.

This task supports all the defined data types of FITS columns, including
vector columns, but does not currently support variable-length vector
columns.  The standard column descriptor keywords in the header are
also copied along with the column itself.  This includes the following
keywords: TNULL, TSCAL, TZERO, TUNIT, TDISP, TDIM, TLMIN, TLMAX, TDMIN,
TDMAX, TCTYP, TCUNI, TCRPX, TCRVL, TCDLT, and TCROT.  Any other
relevant keywords can be copied separately (e.g., using the FKEYPAR and
FPARKEY tasks in the ftools package).

Optionally, this task will write a HISTORY keyword recording the name
of the file from which the column(s) were copied.  Also, if the DELKEY
parameter is set = true, then this task will delete any keywords with
the same name as the added columns.  This is provided to help support
the 'Greenbank convention' which does not allow columns
and keywords to have the same name.
.ih
PARAMETERS
.ls infile [file name]
Name of the input file  (including  optional  extension
number in square brackets) to be updated.   The default
extension number is 1.
.le
.ls colfile [file name]
Name of the file (including  optional  extension number in square
brackets) containing the column(s) to be copied to infile. The default
extension number is 1.
.le
.ls colname [string]
List  of  column  names in the order to be copied to the input FITS
table.   The  names  are  not case sensitive unless the CASESEN
parameter is set = true.  The  column  names should be separated by
commas or white space. If the first non-white character in the column
template is the negation  character  (-),  then the  new  FITS file  will
contain  all  the columns in the input file that are NOT listed in the
column template.  Otherwise, if the specified colname value is blank
or contains a single (-) character, then all the columns in the colfile
will be copied.  Instead of directly listing all the column  names,
one  may  specify the name of an ASCII file (preceded by the "@"
character) containing all of the column names to be copied,  one name
per  line  in  the  file.   The  flcol task may be used to generate a
column name template which may  then  be  edited  for input  to  this
task.  Note that a column will not be copied if a column with the same
name already exists in the other table.
.le
.ls (delkey = no) [boolean]
If set = yes, then any keywords with the same name as the copied
columns will be deleted from the header.  This feature may be
used to conform to the 'Greenbank convention' which does not
allow keywords to have the same name as a column.
.le
.ls (history = yes) [boolean]
Write a HISTORY keyword listing the name of the file from which the
column was copied?
.le
.ls (casesen = no) [boolean]
Should the column names be treated as case-sensitive?  This option is only
needed if two column names are identical except for the case.
.le 
.ih
EXAMPLES
.nf
1. faddcol target.fits col.fits time,x,y

The columns named time, x, and y will be copied from the first 
extension in the file col.fits to the first extension in the file 
target.fits.

2. faddcol target.fits[3] col.fits -time

All the column in the first extension in the file col.fits, except 
the 'time' column will be copied to the 3rd extension in the file 
target.fits.
.fi
.ih    
NOTES:
This task currently only supports character string columns that
are up to 1024 characters wide. Variable-length vector columns
in binary tables are not supported.
.ih
BUGS
.ih
SEE ALSO
ftpaste, ftcopy, ftlist. fv, the interactive FITS file editor, can also be
used to copy table columns.
.endhelp
