.help fcreate Nov97 ftools.futils
.ih
NAME
fcreate --  Create a FITS table extension from ASCII files
describing the  format and content of the table.
.ih
USAGE
fcreate cdfile datafile outfile	
.ih
DESCRIPTION
This  task  creates a new FITS file containing a table extension
(either ASCII or binary) by reading two ASCII format files containing
(1) a description  of the table column formats and (2) the data
contents of the table.  Optionally, a third ASCII file may be specified
(the headfile parameter) which lists additional keywords to be added to the
header of the FITS table.  Options are provided to skip a specified
number of rows at the beginning of the data file and to process only a
specified number of rows in the data file.  By default all the rows will
be processed and written to the FITS table.  The data file may be read
either in free format (default) or fixed format.

.ih
PARAMETERS
.ls cdfile = "" [file name]
The name  of the input column description file.
This is a free-format ASCII file containing one line for each column
(up to 999 columns) in the FITS table to be created.  Each line
contains up to 5 values (tokens) specifying the attributes of the
particular column: column name, datatype, units, column starting
position, and column width.  Every line must have a column name and a
data type token; the other three tokens are optional.  Column names
and units are case sensitive, however, data types are not.  A template
for this file can be created by the 'flcol' task which produces an
output file of column description data that can be edited and used as
input to the fcreate task.

The column name token is a character string which is written to the FITS file
as the value of the appropriate TTYPEn keyword.  The FITS standard 
recommends that only letters, digits, and underscore be used in this
field.  Each column of the table should have a unique name.

The datatype token must conform to the FITS rules for the
TFORM keyword for ASCII and binary tables, whichever is being created.  
The legal datatypes for FITS binary table extensions are:
.nf
       rL - logical
       rAw- character string of unit length w, but total width r
       rX - On/Off bits
       rB - unsigned 8-bit byte
       rI - 16-bit integer
       rJ - 32-bit integer
       rE - single precision floating point
       rD - double precision floating point 
       rC - single precision complex value
       rM - double precision complex value
.fi
where r is an optional numerical value giving the number of elements
in a vector column.  Multi-dimensional arrays can be produced by
including a TDIMn keyword in the optional header file (see below).
For strings, r is the full character width of the column (assumed 1 if
not present) and w is the width of each element, so the number of
elements is r/w.  Without w, the column is treated as a single string
of length r.  This task supports up to a total of 999 elements per
row.  Note that variable length arrays are not currently supported by
this task.

For FITS ASCII table extensions, the following formats are allowed:
.nf
       Aw   - character string, 
       Iw   - integer
       Fw.d - single precision, fixed decimal point 
       Ew.d - single precision, exponential notation
       Dw.d - double precision, exponential notation
.fi
where 'w' is an integer specifying
the width of the FITS table field, and 'd' is the number of decimal digits
to be displayed.  Vector columns and complex values are not allowed
in ASCII table extensions.

The units token is an optional character string that is written to the
FITS file as the value of the appropriate TUNITn keyword; if it
contains embedded spaces, then the whole token should be enclosed in
quote characters.  The value of NONE may be specified as a place
holder (required if the following column position and width token are
specified).

The column position and width tokens are optional integers which
specify how to read the input data file using fixed format.  These
give the starting position of the column (beginning at 1) and the
width of the column in the data file.  For vector columns, the
starting position points to the first element of the column and the
width is that for each individual element; the elements must thus be
consecutive and uniformly spaced within the data file.  This also
applies to complex number pairs.  If position and width tokens are not
specified for ALL the columns then the data file will be read in free
format.
                 
.le 
.ls datafile = "" [file name] 
The name   of  the  input  ASCII  formatted
data file which is to be processed and copied to the FITS table.  If
datafile="-", the data will be read from STDIN.

For fixed format data files (in which column starting positions
and column widths are specified in the column  description file)
each line of the data file corresponds to one row of the FITS table.
Each line must contain a data value for every column of the table (and
every element in a vector column) in the same order as given in the
cdfile.  Any blank lines or lines beginning with '#' will be ignored.
The data file will be read in free format unless the column starting
position and width have been specified for every column (see the
'cdfile' parameter description).  Each line of the ASCII data file may be
up to 30000 characters long and may contain up to 999 data 
values.
        

For free format data files, each line of data may contain any number of
data values; the data values for a single row of a FITS table may be
wrapped around onto multiple rows of the ASCII template file, or
multiple FITS table rows may be present on a single row of the template
file.  Fcreate will continue reading values from subsequent rows until
it reachs the end of the ASCII file, or until 'nrows' lines of data
have been read  If there is only a partial row of data at the end of
the data file it will be ignored. Each line of the ASCII data file may be
up to 30000 characters long and may contain up to 999 data values. 

Bit vector (nX) column data must be entered as the equivalent
n-bit integer value.  For example to set all 3 bits of a '3X'
column one would enter the decimal value 7, and not an array
of 3 1s.

Logical datatypes are represented by the letters T and F (or t and f).
The datatype of numerical columns does not have to correspond to the
datatype of the FITS column (e.g., integer vs. real) because this task
will perform implicit datatype conversion if required.   ASCII string
data values may be enclosed in single quotes, but this is only required
if the string contains  embedded blanks.  To include a single quote in
the string, use two single quotes in a row.

Any undefined  elements in the input data file should be signified by
the string 'INDEF' (with or without the quotes).
These elements are represented in a floating point
column in a FITS binary table with the IEEE Not-a-Number (NaN) value.
If undefined values need to be written to integer columns in a
binary table, or to any column in an ASCII table, then the the 'inull'
or 'anull' parameters must also be defined.
.le
.ls outfile = "" [FITS file name]
The name of the output FITS file.  The FITS file will
have an empty primary array followed by an ASCII or binary table
extension (as specified by the 'tbltype' parameter).  If preceeded by a !,
an existing file of the same name will be overwritten.
.le
.ls (headfile = "")  [file name]
The name  of  the  optional  file  of header
keywords.  Each  line  of this file defines one
keyword, except that blank lines and lines beginning with #
will  be  ignored.   Each line  should usually contain three tokens:
(1) the KEYNAME, (2) the VALUE, and (3) the COMMENT string and
must adhere to the following format rules:

.ls
The KEYNAME token must begin in columns 1-8 and be a maximum  of 8 characters long.  If the first 8 characters of the  line are
blank then the remainder of the line is considered to be a FITS
comment (with a blank keyword name).  A legal FITS keyword name
may only contain the characters A-Z, 0-9, and '-' (minus sign)
and '_' (underscore).  This task will automatically convert any
lowercase characters to uppercase in the FITS file.  If
KEYNAME = 'COMMENT' or 'HISTORY' then the remainder of the line
is considered to be a FITS COMMENT or HISTORY record,
respectively.

The VALUE token must be separated from the KEYNAME token by one or
more
spaces and/or an '=' character.  The datatype of the VALUE
token (numeric, logical, or character string) is automatically
determined and  the output FITS header record is formatted
accordingly.   Logical keyword values are represented by a T or F
(not enclosed in quotes).
The value token may be forced to be interpreted
as a string (e.g. if it is a string of numeric digits) by
enclosing it in single quotes.

The COMMENT token is optional, but if present must be separated from
the VALUE token by at least one blank space.  A leading '/'
character may be used to mark the beginning of the comment
field, otherwise the comment field begins with the first
non-blank character following the value token.
.le
.le
.ls (tbltype = "binary") 
Type of FITS table extension: binary or ASCII.
.le
.ls (nskip = 0) 
Number of rows at the beginning of the data template file to skip inclusive
of any blank rows or rows beginning with '#'.
.le
.ls (nrows = 0) 
No. of rows in the data template file to read inclusive of any blank rows or
rows beginning with '#'.  If nrows = 0 (the default) then the entire
table will be read.
.le
.ls (history = TRUE)
If TRUE than a HISTORY keyword will be appended to the output FITS file
stating that the file was created with the fcreate task.
.le
.ls (morehdr = 0)
Reserve space in the FITS header for this many more keywords to be added
at a later time.  One can always add more keywords to a FITS file, but
it is more efficient to reserve space for them in advance, rather than
having to create more space later on.
.le
.ls (extname = "") 
Name for the output FITS extension, i.e., the value written to the
EXTNAME keyword.
.le
.ls (anull = "") 
The string to be used to represent undefined data values in any column
of an ASCII table.  If this parameter is not set to a blank (default) then
the appropriate TNULLn keyword will be added to the FITS file header
for all the columns.  This parameter should only be defined if the data
actually contains undefined values (represented by "INDEF" character
string).
.le
.ls (inull = 0) 
The value to be used to represent undefined data values in any integer
column (data type = B, I, or J) in an output FITS binary table.  If
this parameter is not set to a zero (default) then the appropriate
TNULLn keyword will be added to the FITS file header for all the
integer columns.  This parameter should only be defined if the data
actually contains undefined values (represented by "INDEF" character
string).
.le
.ls (clobber = no) [boolean]
If true, an existing file with the same name as the requestion output file
will be overwritten.
.le
.ih
EXAMPLES
1. Create a  FITS file called 'outtab.fits' with a binary table
extension  from a column description file called 'coldesc.lis', a
free-format data file called 'data.lis' and a header file called
'keywords.lis'.
.nf

     ft> fcreate coldesc.lis data.lis outtab.fits headfile=keywords.lis


     The column description file (coldesc.lis) could contain:

	name 12A
	ra  E  degrees
	dec E  degrees
	rank  B  

     The data file (data.lis) could contain:

	'Alpha Boot' 15.345   -12.346 3
	Vega       123.225  39.245  7
	'RR Lyrae'  34.46788 -36.9  1

     The optional header file (keywords.lis) could contain:

	INSTRUME  ROSAT  /    name of instrument 
	OBS-DATE  23/08/92    date of the observation
	observer    'I. Newton'   principle investigator
	tempdet 98.6   /  temperature of the detector
	history This file was created with the ftools fcreate task
	

.fi
.ih
BUGS
Variable length array columns are not currently supported by this
task.
.ih
SEE ALSO
ftcreate, ftlist, fthedit
.endhelp
