If an error occurs in an AST routine (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 that an error has occurred, each AST routine that can
potentially fail has a final integer error status argument
called STATUS. This is both an input and an output argument.
Normally, you should declare a single error status variable and pass
it as the STATUS argument to every AST routine you invoke. This
variable must initially be cleared (i.e set to
zero to indicate no
error). If an error occurs, the STATUS argument is returned set to a
different error value, which allows you to detect the error, as
follows:
STATUS = 0
...
ZOOMMAP = AST_ZOOMMAP( 2, 5.0D0, 'Title=My ZoomMap', STATUS )
IF ( STATUS .NE. 0 ) THEN
<an error has occurred>
END IF
In this example, an error would be detected because we have attempted to set a value for the Title attribute of a ZoomMap and a ZoomMap does not have such an attribute.
A consequence of the error status variable STATUS being set to an error value is that almost all AST routines will subsequently cease to function and will instead simply return without action. This means that you do not need to check for errors very frequently. Instead, you can usually simply invoke a succession of AST routines. 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:
STATUS = 0
...
CALL AST_ROUTINEA( ... , STATUS )
CALL AST_ROUTINEB( ... , STATUS )
CALL AST_ROUTINEC( ... , STATUS )
IF ( STATUS .NE. 0 ) THEN
<an error has occurred>
END IF
There are, however, a few routines which do not adhere to this general rule and which will attempt to execute if their STATUS argument is initially set. These routines, such as AST_ANNUL, are concerned with cleaning up and recovering resources. For example, in the following:
STATUS = 0
...
ZOOMMAP = AST_ZOOMMAP( 2, 5.0D0, ' ', STATUS )
CALL AST_ROUTINEX( ... , STATUS )
CALL AST_ROUTINEY( ... , STATUS )
CALL AST_ROUTINEZ( ... , STATUS )
CALL AST_ANNUL( ZOOMMAP, STATUS )
IF ( STATUS .NE. 0 ) THEN
<an error has occurred>
END IF
AST_ANNUL 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 routines.
Routines 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. This is simply done by resetting your error status variable to zero, whereupon the AST routines you pass it to will execute normally again.
AST A Library for Handling World Coordinate Systems in Astronomy