5.4 Data I/O Routines

The following routines read or write data values in the current HDU of the FITS file. Automatic datatype conversion will be attempted for numerical datatypes if the specified datatype is different from the actual datatype of the FITS array or table column.

1

Write elements into the primary data array or image extension.

        FTPPR[BIJKED](unit,group,fpixel,nelements,values, > status)

2

Read elements from the primary data array or image extension. Undefined array elements will be returned with a value = nullval, unless nullval = 0 in which case no checks for undefined pixels will be performed. The anyf parameter is set to true (= .true.) if any of the returned elements were undefined.

        FTGPV[BIJKED](unit,group,fpixel,nelements,nullval, > values,anyf,status)

3

Write elements into an ASCII or binary table column. The `felem' parameter applies only to vector columns in binary tables and is ignored when writing to ASCII tables.

        FTPCL[SLBIJKEDCM](unit,colnum,frow,felem,nelements,values, > status)

4

Read elements from an ASCII or binary table column. Undefined array elements will be returned with a value = nullval, unless nullval = 0 (or = ' ' for ftgcvs) in which case no checking for undefined values will be performed. The ANYF parameter is set to true if any of the returned elements are undefined.

Any column, regardless of it's intrinsic datatype, may be read as a string. It should be noted however that reading a numeric column as a string is 10 - 100 times slower than reading the same column as a number due to the large overhead in constructing the formatted strings. The display format of the returned strings will be determined by the TDISPn keyword, if it exists, otherwise by the datatype of the column. The length of the returned strings can be determined with the ftgcdw routine. The following TDISPn display formats are currently supported:

    Iw.m   Integer
    Ow.m   Octal integer
    Zw.m   Hexadecimal integer
    Fw.d   Fixed floating point
    Ew.d   Exponential floating point
    Dw.d   Exponential floating point
    Gw.d   General; uses Fw.d if significance not lost, else Ew.d

where w is the width in characters of the displayed values, m is the minimum number of digits displayed, and d is the number of digits to the right of the decimal. The .m field is optional.

        FTGCV[SBIJKEDCM](unit,colnum,frow,felem,nelements,nullval, >
                       values,anyf,status)

5

Get the table column number and full name of the column whose name matches the input template string. See the `Advanced Interface Routines' chapter for a full description of this routine.

        FTGCNN(unit,casesen,coltemplate, > colname,colnum,status)