Getting Started

The program cookbook.cxx, analogous to the cookbook.c program supplied with cfitsio, was generated to test the correct functioning of the parts of the library and to provide a demonstration of its usage.

The code for cookbook is reproduced here with commentary as worked example of the usage of the library.

Driver Program

// The CCfits headers are expected to be installed in a subdirectory of
// the include path.

// The <CCfits> header file contains all that is necessary to use both the CCfits
// library and the cfitsio library (for example, it includes fitsio.h) thus making
// all of cfitsio's macro definitions available.

#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

// this includes 12 of the CCfits headers and will support all CCfits operations.
// the installed location of the library headers is $(ROOT)/include/CCfits

// to use the library either add -I$(ROOT)/include/CCfits or #include <CCfits/CCfits>
// in the compilation target.

#include <CCfits>

#include <cmath>

// The library is enclosed in a namespace.
using namespace CCfits;




int main();
int writeImage();
int writeAscii();
int writeBinary();
int copyHDU();
int selectRows();
int readHeader(); 
int readImage();
int readTable();
int readExtendedSyntax();

int main()
{

     FITS::setVerboseMode(true);

     try
     {

        if (!writeImage()) std::cerr << " writeImage() \n";
        if (!writeAscii()) std::cerr << " writeAscii() \n";
        if (!writeBinary()) std::cerr << " writeBinary()  \n";
        if (!copyHDU()) std::cerr << " copyHDU() \n";
        if (!readHeader()) std::cerr << " readHeader() \n";
        if (!readImage()) std::cerr << " readImage() \n";
        if (!readTable()) std::cerr << " readTable() \n";
        if (!readExtendedSyntax()) std::cerr << " readExtendedSyntax() \n";
        if (!selectRows()) std::cerr << " selectRows() \n";

     }
     catch (FitsException&) 
     // will catch all exceptions thrown by CCfits, including errors
     // found by cfitsio (status != 0)
     {
        std::cerr << " Fits Exception Thrown by test function \n";
     }
     
    return 0;
}

The simple driver program illustrates the setting of verbose mode for the library, which makes all internal exceptions visible to the programmer. This is primarily for debugging purposes; exceptions are in some cases used to transfer control in common circumstances (e.g. testing whether a file should be created or appended to in write operations). Most of the exceptions will not produce a message unless this flag is set.

Nearly all of the exceptions thrown by CCfits are derived from FitsException, which is caught by reference in the above example. This includes all nonzero status codes returned by cfitsio by the following construct (recall that in the cfitsio library, nearly all functions return a non-zero status code on error, and have a final argument status of type int):

if ( [cfitsio call](args,...,&status)) throw FitsError(status);

FitsError, derived from FitsException, uses a cfitsio library call to convert the status code to a string message.

The few exceptions that are not derived from FitsException indicate fatal conditions implying bugs in the library. These print a message suggesting the user contact HEASARC to report the problem.

Note also the lack of statements for closing files in any of the following routines, The destructor (dtor) for the FITS object does this when it falls out of scope. A call

FITS::destroy() throw()

is provided for closing files explicitly; destroy() is also responsible for cleaning up the FITS object and deallocating its resources.

When the data are being read instead of written, the user is expected to copy the data into other program variables [rather than use references to the data contained in the FITS object].

The routines in this program test the following functionality:

• writeImage() Writing Primary Images and Image Extensions
• writeAscii() Creating and Writing to an Ascii Table Extension
• writeBinary() Creating and Writing to a Binary Table Extension
• copyHDU() Copying an Extension between Files
• selectRows() Selecting Table Data
• readHeader() Reading Header information from a HDU
• readImage() Reading an Image
• readTable() Reading a Table Extension
• readExtendedSyntax() Reading with Extended File Name Syntax