Error Handling

IDL Advanced Math and Stats uses IDL's built-in error handling mechanisms for most errors. This section describes areas in which IDL Advanced Math and Stats may provide a greater level of control than IDL itself.

Underflow and Overflow

In most cases, IDL Advanced Math and Stats routines are written so that computations are not affected by underflow, provided the system (hardware or software) replaces an underflow with the value zero. Normally, system error messages indicating underflow can be ignored.

IDL Advanced Math and Stats routines also are written to avoid overflow. A program that produces system error messages indicating overflow should be examined for programming errors such as incorrect input data, mismatch of parameter types, or improper dimensions.

In many cases, the documentation for a function points out common pitfalls that can lead to failure of the algorithm.

Missing Values

Some IDL Advanced Math and Stats routines allow input data to contain missing values. These routines recognize as a missing value the special floating-point value referred to as "Not a Number" or NaN. The actual value varies on different computers, but it can be obtained by reference to the IMSL_MACHINE function.

The manner in which missing values are treated depends on the individual function as described in the documentation for that function.

For more information on special floating-point values (including NaN), see Math Errors (Application Programming).

Errors in User Code

IDL Advanced Math and Stats functions attempt to detect user errors and handle them in a way that provides as much information to the user as possible. In addition to the basic IDL error-handling facility, five levels of Informational Error severity are recognized. The error levels are described in Table 1-1.

Error Levels and Default Actions

The IMSL numerical library categorizes library errors with one of five severity levels:

Table 1-1: Error levels generated by the IMSL numerical library
Type	Meaning
Note	A note is issued to indicate the possibility of a trivial error or simply to provide information about the computations. A note does not update !ERROR_STATE.
Alert	An alert indicates that the user should be advised about conditions that arise during computation. Underflow errors are generally categorized as alerts. An alert does not update !ERROR_STATE.
Warning	A warning indicates the existence of a condition that may require corrective action by the user or calling routine. A warning error may be issued because the results are accurate to only a few decimal places, because some of the output may be erroneous but most of the output is correct, or because some assumptions underlying the analysis technique are violated. Often no corrective action is necessary and the condition can be ignored. A warning does not update !ERROR_STATE.
Fatal	A fatal error indicates the existence of a condition that may be serious. In most cases, the user or calling routine must take corrective action to recover. A fatal error updates !ERROR_STATE.
Terminal	A terminal error is serious. It usually is the result of an incorrect specification, such as specifying a negative number as the number of equations. Terminal errors may also be caused by various programming errors that are impossible to diagnose correctly within the IMSL library. If a terminal error occurs, first check that the arguments passed to the routine are in the correct order and have the correct data types. A terminal error updates !ERROR_STATE.

Although the IDL Advanced Math and Stats module does not allow users to directly manipulate how these errors are interpreted internally, you can control which errors are printed to the IDL output log. All informational error messages are printed by default. Setting the system variable !QUIET to a nonzero value suppresses output of Notes, Alerts, and Warnings. Fatal and Terminal errors always halt execution of the IDL program and change the value of !ERROR_STATE.

Handling Errors in IMSL Routines

When a fatal or terminal error occurs in an IMSL routine, the value of !ERROR_STATE is updated to reflect the fact that the error occurred. If you have implemented a CATCH block to handle errors in your own routine, you can use the value of !ERROR_STATE to determine which fatal or terminal error occurred in the IMSL library.

To determine whether the most recent error was generated by the IMSL library, inspect the NAME field of the !ERROR_STATE structure. Errors generated by the IMSL library will populate the NAME field with the string:

IDL_M_IMSL_LIBRARYERROR

If the error was generated in the IMSL library, inspect the MSG field of the !ERROR_STATE structure for information on which specific fatal or terminal error occurred. For example, attempting to invert a matrix in which every element is zero will generate a fatal error with the following message:

IMSL Error: IMSL_INV: Fatal error: MATH_SINGULAR_MATRIX: The input 
matrix is singular.

You could, for example, use the following code fragment to test for this particular error:

IF (STRPOS(!error_state.msg,'MATH_SINGULAR_MATRIX') GE 0) THEN $ 
   BEGIN 
   Error handling code here... 
ENDIF