Introduction
The errors discussed in this section are exclusively those issued by the IMSL Mathematics and Statistics libraries. These are distinct from errors issued by PV-WAVE and do not affect the PV-WAVE system variables !ERR, !ERROR, and !ERR_STR. Errors originating from the IMSL libraries are stored in their own PV_WAVE system variables:
!CMAST_ERR - the code for the last error issued by the IMSL libraries.
!CMAST_ERR_STRING - A string containing the last error message issued by the IMSL libraries.
!CMAST_ERR_TYPE - The severity of the last error issued by the IMSL libraries.( "Note", "Alert", "Warning", "Fatal error" or "Terminal error")
User Errors
PV‑WAVE 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, the functions recognize various levels of severity of errors, and also consider the extent of the error in the context of the purpose of the function; a trivial error in one situation may be serious in another. Functions attempt to report as many errors as they can reasonably detect. 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, if some are not computable but most are, an error condition exists; and its severity 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 the PV‑WAVE IMSL Statistics Library. Each level has an associated PRINT attribute and a STOP attribute. These attributes have default settings, 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 a PV‑WAVE 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 1). 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 1). Errors of any of the severity levels except Terminal may be informational errors.
Note—A note is issued to indicate the possibility of a trivial error or simply to provide information about the computations. Default attributes: PRINT=0, STOP=0.
Alert—An alert indicates that a function value has been set to 0 due to underflow. Default attributes: PRINT=0, STOP=0.
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. Usually no corrective action is necessary, and the condition can be ignored. Default attributes: PRINT=1, STOP=0.
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. Default attributes: PRINT=1, STOP=1.
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 may 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 usage, 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=1, STOP=1.
The user can set PRINT and STOP attributes by calling the CMAST_ERR_PRINT Function and CMAST_ERR_STOP Function.
Errors in Lower-Level Functions
It is possible that a user’s program may call an PV‑WAVE IMSL Statistics Library function that in turn calls a nested sequence of lower-level 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 PV‑WAVE IMSL Statistics Library function calls a user-supplied routine that in turn calls another PV‑WAVE IMSL Statistics Library function.
Functions for Error Handling
There are two ways in which the user may interact with the error handling system: (1) to change the default actions and (2) to determine the type and/or code of an informational error so as to take corrective action. The functions to use are the CMAST_ERR_TRANS Function, CMAST_ERR_TRANS Function, and CMAST_ERR_TRANS Function. The ERROR_TYPE Function retrieves the Imsl_error enum error type value. The CMAST_ERR_TRANS function retrieves the integer code for an informational error. The ERROR_MESSAGE function retrieves the error message string.