NAME

faddcol -- copies a list of columns from one FITS table extension to another.

USAGE

        faddcol infile colfile colname

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.

PARAMETERS

infile [file name]

Name of the input file (including optional extension number in square brackets) to be updated. The default extension number is 1.

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.

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.

(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.

(history = yes) [boolean]

Write a HISTORY keyword listing the name of the file from which the column was copied?

(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.

EXAMPLES

1. 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. faddcol target.fits col.fits time,x,y

2. 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. faddcol target.fits[3] col.fits -time

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.

BUGS

SEE ALSO

ftpaste, ftcopy, ftlist. fv, the interactive FITS file editor, can also be used to copy table columns.

CATEGORY