.help ftabcopy Jan92 ftools.futils
.ih
NAME
ftabcopy -- Copy specified columns and rows from a FITS table to a new FITS 
table.
.ih
USAGE
ftabcopy infile[ext#] outfile columns rows
.ih
DESCRIPTION
This task will create a new FITS file (with a binary or ASCII table
extension) containing a subset of the columns and rows in an existing
FITS table extension.  The desired column names are given as a column
name template.  Row ranges could also be given and there could be as
much as 15 ranges at present.  By default it is '-' which is all rows
of the input file.  Also, it copies the following WCS related keywords:
TLMIN, TLMAX, TCTYP, TCRCL, TCDLT, TCRPX, TCROT, and TCRVL.
.ih
PARAMETERS
.ls infile [filename]
Name of the FITS table extension (including  optional  extension
number in square brackets) from which the columns are to be copied.
.le                                                                 
.ls outfile [filename]
Name of the new FITS file to contain the copied columns.
By default, the output file will consist
of a null primary array followed by an ASCII or binary table extension,
depending on the type of input file extension.  If preceded by !, an 
existing file of the same name is overwritten.
.le
.ls columns [string]
List of column names in the order to be copied 
from the input FITS table into the
new FITS file.  The names are case sensitive.  The column names
should be separated by commas or white space.  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.  If the first non-white character in the column
template is the negation character (-), the new FITS file will contain
all the columns in the input file that are NOT listed in the column
template.
.le
.ls rows [string]
List of row ranges separated by comma (,) to be copied from input file.
At most 15 ranges can be accomodated at present.  By default all rows
are copied.
.le
.ls (outtype = SAME) [string]
Specify the type of output extension - ASCII or BINARY.  If outtype is
SAME, the output extension type will be the same as the input extension
type.
.le
.ls (inull = -999) [integer]
Value to use for NULL in integer columns for ASCII->BINARY translation.
Used only if the defined NULL is illegal or undefined.
.le
.ls (snull = "UNDEF") [string]
Value to use for NULL in column in BINARY->ASCII translation.  Used only
if the defined NULL is illegal or undefined.
.le
.ls (unique = no) [boolean]
Eliminate duplicate rows from the output FITS file?
If 'unique' is set to "yes", only one of each set of duplicate rows is included
in the output FITS table.  All columns in the output FITS table must be 
identical for the row to be removed.  String comparisons are case sensitive.
.le
.ls (copyprime = yes) [boolean]
If true, the primary header and array of the input file will be
copied to the output file.
.le
.ls (copyall = no) [boolean]
Copy all other extensions (and the primary array) from input FITS file
to the output FITS file?  If true, the value of copyprime is ignored.
.le
.ls (copykeys = yes) [boolean]
Copy all the additional non-required keywords from the input
FITS table header to the output table header?   If false, then only 
the essential keywords needed to define the structure and WCS
of the table columns will be copied.
.le
.ls (history=yes) [boolean]
When this parameter is true, FTABCOPY will add a history record to 
indicate that it acted on the file.
.le
.ls (clobber=no) [boolean]
If true, an existing file with the same name as the requested output file
is overwritten.
.le
.ih
EXAMPLES
1. Copy the name, mag, and color columns from the starcat.fits file:

     ft> ftabcopy starcat.fits starmag.fits name,mag,color

2. Copy all the columns except the 'error' column:

     ft> ftabcopy meas.fits nomeas.fits -error

3. Copy the rows 1-10, 35, 105 etc:
 
     ft> ftabcopy rows=1-10, 35, 105

.ih
NOTES:
In the BINARY->ASCII translation, complex and logical data types, 
variable length arrays and vector columns are not supported.  
Bit and Byte columns are mapped to integer.
.ih
BUGS
NULLs in ASCII columns are not retained in either translation.
.ih
SEE ALSO
ftcopy, ftlist, ftselect, ftverify. fv, the interactive FITS file
editor, can also be used to copy columns to a new table.
.endhelp
