next up previous 264
Next: Sharing the Error Status
Up: An AST Object Primer
Previous: C Pointer Types


Error Detection

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.


next up previous 264
Next: Sharing the Error Status
Up: An AST Object Primer
Previous: C Pointer Types

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
R.F. Warren-Smith & D.S. Berry
7th December 2012
E-mail:starlink@jiscmail.ac.uk

Copyright (C) 2012 Science \& Technology Facilities Council