Previous Up Next

Chapter 5  Basic Interface Routines

This section defines a basic set of subroutines that can be used to perform the most common types of read and write operations on FITS files. New users should start with these subroutines and then, as needed, explore the more advance routines described in the following chapter to perform more complex or specialized operations.

A right arrow symbol (>) is used to separate the input parameters from the output parameters in the definition of each routine. This symbol is not actually part of the calling sequence. Note that the status parameter is both an input and an output parameter and must be initialized = 0 prior to calling the FITSIO subroutines.

Refer to Chapter 9 for the definition of all the parameters used by these interface routines.

5.1 FITSIO Error Status Routines

1
Return the current version number of the fitsio library. The version number will be incremented with each new release of CFITSIO. The 3 fields of the version string M.xx.yy are converted to a float as: M + .01*xx + .0001*yy. 
        FTVERS( > version)
2
Return the descriptive text string corresponding to a FITSIO error status code. The 30-character length string contains a brief description of the cause of the error. 
        FTGERR(status, > errtext)
3
Return the top (oldest) 80-character error message from the internal FITSIO stack of error messages and shift any remaining messages on the stack up one level. Any FITSIO error will generate one or more messages on the stack. Call this routine repeatedly to get each message in sequence. The error stack is empty when a blank string is returned. 
        FTGMSG( > errmsg)
4
The FTPMRK routine puts an invisible marker on the CFITSIO error stack. The FTCMRK routine can then be used to delete any more recent error messages on the stack, back to the position of the marker. This preserves any older error messages on the stack. FTCMSG simply clears the entire error message stack. These routines are called without any arguments. 
        FTPMRK
        FTCMRK
        FTCMSG
5
Print out the error message corresponding to the input status value and all the error messages on the FITSIO stack to the specified file stream (stream can be either the string ’STDOUT’ or ’STDERR’). If the input status value = 0 then this routine does nothing. 
       FTRPRT (stream, > status)
6
Write an 80-character message to the FITSIO error stack. Application programs should not normally write to the stack, but there may be some situations where this is desirable. 
        FTPMSG(errmsg)

5.2 File I/O Routines

1
Open an existing FITS file with readonly or readwrite access. This routine always opens the primary array (the first HDU) of the file, and does not move to a following extension, if one was specified as part of the filename. Use the FTNOPN routine to automatically move to the extension. This routine will also open IRAF images (.imh format files) and raw binary data arrays with READONLY access by first converting them on the fly into virtual FITS images. See the ‘Extended File Name Syntax’ chapter for more details. The FTDKOPN routine simply opens the specified file without trying to interpret the filename using the extended filename syntax. 
        FTOPEN(unit,filename,rwmode, > blocksize,status)
        FTDKOPN(unit,filename,rwmode, > blocksize,status)
2
Open an existing FITS file with readonly or readwrite access and move to a following extension, if one was specified as part of the filename. (e.g., ’filename.fits+2’ or ’filename.fits[2]’ will move to the 3rd HDU in the file). Note that this routine differs from FTOPEN in that it does not have the redundant blocksize argument. 
        FTNOPN(unit,filename,rwmode, > status)
3
Open an existing FITS file with readonly or readwrite access and then move to the first HDU containing significant data, if a) an HDU name or number to open was not explicitly specified as part of the filename, and b) if the FITS file contains a null primary array (i.e., NAXIS = 0). In this case, it will look for the first IMAGE HDU with NAXIS > 0, or the first table that does not contain the strings ‘GTI’ (Good Time Interval) or ‘OBSTABLE’ in the EXTNAME keyword value. FTTOPN is similar, except it will move to the first significant table HDU (skipping over any image HDUs) in the file if a specific HDU name or number is not specified. FTIOPN will move to the first non-null image HDU, skipping over any tables. 
        FTDOPN(unit,filename,rwmode, > status)
        FTTOPN(unit,filename,rwmode, > status)
        FTIOPN(unit,filename,rwmode, > status)
4
Open and initialize a new empty FITS file. A template file may also be specified to define the structure of the new file (see section 4.2.4). The FTDKINIT routine simply creates the specified file without trying to interpret the filename using the extended filename syntax. 
        FTINIT(unit,filename,blocksize, > status)
        FTDKINIT(unit,filename,blocksize, > status)
5
Close a FITS file previously opened with ftopen or ftinit 
        FTCLOS(unit, > status)
6
Move to a specified (absolute) HDU in the FITS file (nhdu = 1 for the FITS primary array) 
        FTMAHD(unit,nhdu, > hdutype,status)
7
Create a primary array (if none already exists), or insert a new IMAGE extension immediately following the CHDU, or insert a new Primary Array at the beginning of the file. Any following extensions in the file will be shifted down to make room for the new extension. If the CHDU is the last HDU in the file then the new image extension will simply be appended to the end of the file. One can force a new primary array to be inserted at the beginning of the FITS file by setting status = -9 prior to calling the routine. In this case the existing primary array will be converted to an IMAGE extension. The new extension (or primary array) will become the CHDU. The FTIIMGLL routine is identical to the FTIIMG routine except that the 4th parameter (the length of each axis) is an array of 64-bit integers rather than an array of 32-bit integers. 
        FTIIMG(unit,bitpix,naxis,naxes, > status)
        FTIIMGLL(unit,bitpix,naxis,naxesll, > status)
8
Insert a new ASCII TABLE extension immediately following the CHDU. Any following extensions will be shifted down to make room for the new extension. If there are no other following extensions then the new table extension will simply be appended to the end of the file. The new extension will become the CHDU. The FTITABLL routine is identical to the FTITAB routine except that the 2nd and 3rd parameters (that give the size of the table) are 64-bit integers rather than 32-bit integers. Under normal circumstances, the nrows and nrowsll paramenters should have a value of 0; CFITSIO will automatically update the number of rows as data is written to the table. 
        FTITAB(unit,rowlen,nrows,tfields,ttype,tbcol,tform,tunit,extname, >
               status)
        FTITABLL(unit,rowlenll,nrowsll,tfields,ttype,tbcol,tform,tunit,extname, >
               status)
9
Insert a new binary table extension immediately following the CHDU. Any following extensions will be shifted down to make room for the new extension. If there are no other following extensions then the new bintable extension will simply be appended to the end of the file. The new extension will become the CHDU. The FTIBINLL routine is identical to the FTIBIN routine except that the 2nd parameter (that gives the length of the table) is a 64-bit integer rather than a 32-bit integer. Under normal circumstances, the nrows and nrowsll paramenters should have a value of 0; CFITSIO will automatically update the number of rows as data is written to the table. 
        FTIBIN(unit,nrows,tfields,ttype,tform,tunit,extname,varidat > status)
        FTIBINLL(unit,nrowsll,tfields,ttype,tform,tunit,extname,varidat > status)

5.3 Keyword I/O Routines

1
Put (append) an 80-character record into the CHU. 
        FTPREC(unit,card, > status)
2
Put (append) a new keyword of the appropriate datatype into the CHU. The E and D versions of this routine have the added feature that if the ’decimals’ parameter is negative, then the ’G’ display format rather then the ’E’ format will be used when constructing the keyword value, taking the absolute value of ’decimals’ for the precision. This will suppress trailing zeros, and will use a fixed format rather than an exponential format, depending on the magnitude of the value. 
        FTPKY[JKLS](unit,keyword,keyval,comment, > status)
        FTPKY[EDFG](unit,keyword,keyval,decimals,comment, > status)
3
Get the nth 80-character header record from the CHU. The first keyword in the header is at key_no = 1; if key_no = 0 then this subroutine simple moves the internal pointer to the beginning of the header so that subsequent keyword operations will start at the top of the header; it also returns a blank card value in this case. 
        FTGREC(unit,key_no, > card,status)
4
Get a keyword value (with the appropriate datatype) and comment from the CHU 
        FTGKY[EDJKLS](unit,keyword, > keyval,comment,status)
5
Delete an existing keyword record. 
        FTDKEY(unit,keyword, > status)

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)

Previous Up Next