If an error occurs in an AST function (for example, if you supply an invalid argument, such as a pointer to the wrong class of Object), an error message will be written to the standard error stream and the function will immediately return.
To indicate than an error has occurred, an AST error status value is used. This integer value is stored internally by AST and is initially clear (i.e. set to zero10to indicate no error). If an error occurs, it becomes set to a different error value, which allows you to detect the error, as follows:
zoommap = astZoomMap( 2, 5.0, "Title=My ZoomMap" ); if ( !astOK ) { <an error has occurred> }
The macro astOK is used to test whether the AST error status is still OK. In this example it would not be, because we have attempted to set a value for the Title attribute of a ZoomMap and a ZoomMap does not have such an attribute. The actual value of the AST error status can be obtained using the astStatus macro, as follows:
int status; ... status = astStatus;
A consequence of the AST error status being set is that almost all AST functions will subsequently cease to function and will instead simply return without action. This means that you do not need to use astOK to check for errors very frequently. Instead, you can usually simply invoke a succession of AST functions. If an error occurs in any of them, the following ones will do nothing and you can check for the error at the end, for example:
astFunctionA( ... ); astFunctionB( ... ); astFunctionC( ... ); if ( !astOK ) { <an error has occurred> }
There are, however, a few functions which do not adhere to this general rule and which will attempt to execute if the AST error status is set. These functions, such as astAnnul, are concerned with cleaning up and recovering resources. For example, in the following:
zoommap = astZoomMap( 2, 5.0, "" ); astFunctionX( ... ); astFunctionY( ... ); astFunctionZ( ... ); zoommap = astAnnul( zoommap ); if ( !astOK ) { <an error has occurred> }
astAnnul will execute normally in order to recover the resources
associated with the ZoomMap that was created earlier, regardless of
whether an error has occurred in any of the intermediate functions.
Functions which behave in this way are noted in the relevant
descriptions in .
If a serious error occurs, you will probably want to abort your program, but sometimes you may want to recover and carry on. Because very few AST functions will execute once the AST error status has been set, you must first clear this status by using the astClearStatus macro, as follows:
astClearStatus;
This will restore the AST error status to its OK value, so that AST functions execute normally again.
Occasionally, you may also need to set the AST error status to an
explicit error value (see for an
example). This is done using astSetStatus and can be used to
communicate to AST that an error has occurred in some other item of
software, for example:
int new_status; ... astSetStatus( new_status );
The effect is that most AST routines will subsequently return without
action, just as if an error had occurred within the AST library
itself.
AST A Library for Handling World Coordinate Systems in Astronomy