NAME

fcreate -- Create a FITS table extension from ASCII files describing the format and content of the table.


USAGE

        fcreate cdfile datafile outfile        

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.


PARAMETERS

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:

                    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

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:

                    Aw   - character string, 
                    Iw   - integer
                    Fw.d - single precision, fixed decimal point 
                    Ew.d - single precision, exponential notation
                    Dw.d - double precision, exponential notation

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.

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.

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.

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

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.

(tbltype = "binary")
Type of FITS table extension: binary or ASCII.

(nskip = 0)
Number of rows at the beginning of the data template file to skip inclusive of any blank rows or rows beginning with '#'.

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

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

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

(extname = "")
Name for the output FITS extension, i.e., the value written to the EXTNAME keyword.

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

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

(clobber = no) [boolean]
If true, an existing file with the same name as the requestion output file will be overwritten.


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

     
          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
             
     


BUGS

Variable length array columns are not currently supported by this task.


SEE ALSO

ftcreate, ftlist, fthedit

CATEGORY

Nov97 ftools.futils