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 ObjectObject), 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 zero[*]to indicate no error). If an error occurs, it becomes set to a different error value, which allows you to detect the error, as follows:


\begin{terminalv}
zoommap = astZoomMap( 2, 5.0, ''Title=My ZoomMap'' );
if ( !astOK ) {
<an error has occurred>
}
\end{terminalv}

The macro astOKastOK 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 TitleTitle attribute of a ZoomMapZoomMap and a ZoomMap does not have such an attribute. The actual value of the AST error status can be obtained using the astStatusastStatus macro, as follows:


\begin{terminalv}
int status;
\par
...
\par
status = astStatus;
\end{terminalv}

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:


\begin{terminalv}
astFunctionA( ... );
astFunctionB( ... );
astFunctionC( ... );
if ( !astOK ) {
<an error has occurred>
}
\end{terminalv}

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 astAnnulastAnnul, are concerned with cleaning up and recovering resources. For example, in the following:


\begin{terminalv}
zoommap = astZoomMap( 2, 5.0, '''' );
\par
astFunctionX( ... )...
... astAnnul( zoommap );
if ( !astOK ) {
<an error has occurred>
}
\end{terminalv}

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 Appendix B.

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 astClearStatusastClearStatus macro, as follows:


\begin{terminalv}
astClearStatus;
\end{terminalv}

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 ยง15.14 for an example). This is done using astSetStatusastSetStatus and can be used to communicate to AST that an error has occurred in some other item of software, for example:


\begin{terminalv}
int new_status;
\par
...
\par
astSetStatus( new_status );
\end{terminalv}

The effect is that most AST routines will subsequently return without action, just as if an error had occurred within the AST library itself.