Back To Software Index
Nearly all the CFITSIO routines return an error status value in 2 ways: as the value of the last parameter in the function call, and as the returned value of the function itself. This provides some flexibility in the way programmers can test if an error occurred, as illustrated in the following 2 code fragments:
if ( fits_write_record(fptr, card, &status) )
printf(" Error occurred while writing keyword.");
or,
fits_write_record(fptr, card, &status);
if ( status )
printf(" Error occurred while writing keyword.");
A listing of all the CFITSIO status code values and their symbolic
mnemonics is given at the end of this document. Programmers are
encouraged to use the symbolic mnemonics (defined in fitsio.h) rather
than the actual integer status values to improve the readability of
their code.
The CFITSIO library uses an `inherited status' convention for the status parameter which means that if a routine is called with a positive input value of the status parameter as input, then the routine will exit immediately without changing the value of the status parameter. Thus, if one passes the status value returned from each CFITSIO routine as input to the next CFITSIO routine, then whenever an error is detected all further CFITSIO processing will cease. This convention can simplify the error checking in application programs because it is not necessary to check the value of the status parameter after every single CFITSIO routine call. If a program contains a sequence of several CFITSIO calls, one can just check the status value after the last call. Since the returned status values are generally distinctive, it should be possible to determine which routine originally returned the error status.
CFITSIO also maintains an internal stack of error messages (80-character maximum length) which in many cases provide a more detailed explanation of the cause of the error than is provided by the error status number alone. It it recommended that the error message stack be printed out whenever a program detects a CFITSIO error. To do this, call the ffgmsg routine repeatedly to get the successive messages on the stack. When the stack is empty ffgmsg will return a null value (and a null string). Note that this is a `First In -- First Out' stack, so the oldest error message is returned first by ffgmsg.
In some situations programs may encounter a non-fatal CFITSIO error and will want to continue processing. An example is when a program fails to find an optional keyword in the header and CFITSIO returns status = KEY_NO_EXIST (202). The program may ignore this error and reset status = 0, however this may still leave error messages on the stack. To clear the entire message stack in this situation, call the ffcmsg routine.
Back To Software Index