IMSL functions attempt to detect user errors and handle them in a way that provides as much information to the user as possible. To do this, various levels of severity of errors are recognized, and the extent of the error in the context of the purpose of the function also is considered; a trivial error in one situation can be serious in another. IMSL attempts to report as many errors as can reasonably be detected. Multiple errors present a difficult problem in error detection because input is interpreted in an uncertain context after the first error is detected.
What Determines Error Severity
In some cases, the user’s input may be mathematically correct, but because of limitations of the computer arithmetic and of the algorithm used, it is not possible to compute an answer accurately. In this case, the assessed degree of accuracy determines the severity of the error. In cases where the function computes several output quantities, some are not computable but most are, an error condition exists. The severity of the error depends on an assessment of the overall impact of the error.
Kinds of Errors and Default Actions
Five levels of severity of errors are defined in IMSL C/Stat/Library. Each level has an associated PRINT attribute and a STOP attribute. These attributes have default settings (YES or NO), but they may also be set by the user. The purpose of having multiple error types is to provide independent control of actions to be taken for errors of different levels of severity. Upon return from an IMSL function, exactly one error state exists. (A code 0 “error” is no error.) Even if more than one informational error occurs, only one message is printed (if the PRINT attribute is YES). Multiple errors for which no corrective action within the calling program is reasonable or necessary result in the printing of multiple messages (if the PRINT attribute for their severity level is YES). Errors of any of the severity levels except IMSLS_TERMINAL may be informational errors. The include file, imsls.h, defines each of IMSLS_NOTE, IMSLS_ALERT, IMSLS_WARNING, IMSLS_FATAL, IMSLS_TERMINAL, IMSLS_WARNING_IMMEDIATE, and IMSLS_FATAL_IMMEDIATE as enumerated data type Imsls_error.
IMSLS_NOTE.
A note is issued to indicate the possibility of a trivial error or simply
to provide information about the computations.
Default attributes: PRINT=NO,
STOP=NO
IMSLS_ALERT.
An alert indicates that a function value has been set to 0 due to
underflow.
Default attributes: PRINT=NO, STOP=NO
IMSLS_WARNING.
A warning indicates the existence of a condition that may require
corrective action by the user or calling function. 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. Usually no
corrective action is necessary, and the condition can be ignored.
Default
attributes: PRINT=YES, STOP=NO
IMSLS_FATAL.
A fatal error indicates the existence of a condition that may be serious.
In most cases, the user or calling function must take corrective action to
recover.
Default attributes: PRINT=YES, STOP=YES
IMSLS_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. These errors can also be caused by various programming errors impossible to diagnose correctly in C. The resulting error message may be perplexing to the user. In such cases, the user is advised to compare carefully the actual arguments passed to the function with the dummy argument descriptions given in the documentation. Special attention should be given to checking argument order and data types.
A terminal error is not an informational error, because
corrective action within the program is generally not reasonable. In normal use,
execution is terminated immediately when a terminal error occurs. Messages
relating to more than one terminal error are printed if they occur.
Default
attributes: PRINT=YES, STOP=YES
IMSLS_WARNING_IMMEDIATE.
An immediate warning error is identical to a warning error, except it is
printed immediately.
Default attributes: PRINT=YES, STOP=NO
IMSLS_FATAL_IMMEDIATE.
An immediate fatal error is identical to a fatal error, except it is
printed immediately.
Default attributes: PRINT=YES, STOP=YES
The user can set PRINT and STOP attributes by calling function imsls_error_options as described in Chapter 15, “Utilities.”
Errors in Lower-level Functions
It is possible that a user’s program may call an IMSL function that in turn calls a nested sequence of lower-level IMSL functions. If an error occurs at a lower level in such a nest of functions and if the lower-level function cannot pass the information up to the original user-called function, then a traceback of the functions is produced. The only common situation in which this can occur is when an IMSL function calls a user-supplied routine that in turn calls another IMSL function.
Functions for Error Handling
The user may interact in two ways with the IMSL error-handling system: (1) to change the default actions and (2) to determine the code of an informational error so as to take corrective action. The IMSL functions to use are imsls_error_options and imsls_error_code. Function imsls_error_options sets the actions to be taken when errors occur. Function imsls_error_code retrieves the integer code for an informational error. These functions are documented in Chapter 15, “Utilities;.”
Threads and Error Handling
If multiple threads are used then default settings are
valid for each thread
but can be altered for each individual thread. When
using threads it is
necessary to set options using imsls_error_options (excluding IMSLS_SET_SIGNAL_TRAPPING
) for each thread by calling imsls_error_options
from within each thread.
The IMSL signal-trapping mechanism must be disabled when multiple threads are used. The IMSL signal-trapping mechanism can be disabled by making the following call before any threads are created:
imsls_error_options(IMSLS_SET_SIGNAL_TRAPPING, 0, 0);
See Chapter 15, “Utilities”, examples 3 and 4 of imsls_error_options for multithreaded examples.
Use of Informational Error to Determine Program Action
In the program segment below, a factor analysis is to be performed on the matrix covariances. If it is determined that the matrix is singular (and often this is not immediately obvious), the program is to take a different branch.
x = imsls_f_factor_analysis
(nobs, covariances,
n_factors, 0);
if (imsls_error_code() ==
IMSLS_COV_IS_SINGULAR)
{
/* Handle
a singular matrix */
}
Additional Examples
See functions imsls_error_options and imsls_error_code in Chapter 15, “Utilities” for additional examples.
