IERCD and N1RTY
The last two routines for interacting with the error handling system, IERCD and N1RTY, are INTEGER functions and are described in the following material.
IERCD retrieves the integer code for an informational error. Since it has no arguments, it may be used in the following way:
ICODE = IERCD( )
The function retrieves the code set by the most recently called IMSL routine.
N1RTY retrieves the error type set by the most recently called IMSL routine. It is used in the following way:
ITYPE = N1RTY(1)
ITYPE = 1, 2, 4, and 5 correspond to error severity levels 1, 2, 4, and 5, respectively. ITYPE = 3 and ITYPE = 6 are both warning errors, error severity level 3. While ITYPE = 3 errors are informational errors (IERCD( ) ≠ 0), ITYPE = 6 errors are not informational errors (IERCD( ) = 0).
For software developers requiring additional interaction with the IMSL error handling system, see Aird and Howell (1991).
Examples
Changes to default actions
Some possible changes to the default actions are illustrated below. The default actions remain in effect for the kinds of errors not included in the call to ERSET.
To turn off printing of warning error messages:
CALL ERSET (3, 0, ‑1)
To stop if warning errors occur:
CALL ERSET (3, ‑1, 1)
To print all error messages:
CALL ERSET (0, 1, ‑1)
To restore all default settings:
CALL ERSET (0, 2, 2)
Use of informational error to determine program action
In the program segment below, the Cholesky factorization of a matrix is to be performed. If it is determined that the matrix is not nonnegative definite (and often this is not immediately obvious), the program is to take a different branch.
.
.
.
CALL CHFAC (A, IRANK, R)
IF (IERCD() .EQ. 1) THEN
! Handle matrix that is not nonnegative definite
.
.
.
END IF
Examples of All Types of Errors
The program below illustrates each of the different types of errors detected by the STAT/LIBRARY routines. If the call to ERSET was not made, messages for errors of levels 1 and 2 would not be printed.
The error messages refer to the argument names that are used in the documentation for the routine, rather than the user’s name of the variable used for the argument. In the messages generated by IMSL routine CHFAC in this example, references are made to LDA and LDR, whereas in the program literals were used for these arguments. Note that error codes are printed as part of the messages for informational errors.
USE IMSL_LIBRARIES
! Specifications for local variables
INTEGER IDO, IOPT, IRANK, N, NMISS, NOBS, NPOP, NROW, NUM
REAL A(2,2), CHSQ, CONPER, DF, PR, R(2,2), RCOEF, STAT(20), &
SUMRY(11), TOL, X(10), XMEAN, Y(10)
!
DATA X/-5.0, -4.0, -3.0, -2.0, -1.0, 1.0, 2.0, 3.0, 4.0, 5.0/
DATA Y/3.0, 5.0, 4.0, 5.0, 6.0, 7.0, 6.0, 8.0, 7.0, 9.0/
DATA A/2.0, 0.0, 0.0, -3.0/
! Turn on printing and turn off
! stopping for all error types.
CALL ERSET (0, 1, 0)
! Generate level 1 informational error.
DF = 1000.0
CHSQ = -1.0
PR = CHIDF(CHSQ,DF)
! Generate level 2 informational error.
DF = 1000.0
CHSQ = 10.0
PR = CHIDF(CHSQ,DF)
! Generate level 3 informational error.
NUM = 11
CALL LETTR (X, SUMRY, NMISS, NUM=NUM)
! Generate level 4 informational error.
N = 2
TOL = 0.0001
CALL CHFAC (A, IRANK, R, TOL=TOL)
! Generate several level 5 errors.
CALL CHFAC (A, IRANK, R, TOL=TOL, LDR = -2)
! Generate several warning errors that
! do not allow corrective action
! (because no codes are listed for
! these errors in the document for the
! routine).
NROW = 10
NPOP = 100
IOPT = 1
CONPER = 0.95
CALL SMPRR (NROW, X, Y, NPOP, XMEAN, STAT, IOPT=IOPT, CONPER=CONPER)
END
Output
*** NOTE ERROR 1 from CHIDF. Since CHSQ = -1.000000E+00 is less than
*** zero, the distribution function is zero at CHSQ.
*** ALERT ERROR 3 from CHIDF. The normal distribution is used for large
*** degrees of freedom. However, it has produced underflow.
*** Therefore, the probability is set to 0.
*** WARNING ERROR 3 from LETTR. NUM = 11 and the number of observations =
*** 10. Since NUM is greater than the number of observations, it
*** is likely that the results are not useful.
*** WARNING ERROR 1 from CHFAC. The leading 2 by 2 submatrix of the input
*** matrix is not nonnegative definite within the tolerance
*** definedby TOL = 1.000000E-04.
*** TERMINAL ERROR 3 from CHFAC. N = 2 and LDA = 1. N must be less than or
*** equal to LDA.
*** TERMINAL ERROR 5 from CHFAC. LDR = -2. LDR must be greater than or
*** equal to 1.
*** WARNING ERROR 1 from SMPRR. CONPER = 9.500000E-01. The confidence
*** percentage is less than 50.0. Commonly used confidence
*** percentages are: 90.0, 95.0 or 99.0.
*** WARNING ERROR 3 from SMPRR. The sample size, STAT(19) = 10. This is
*** less than 30. The confidence limits, which are computed using
*** a normal approximation, may not be very accurate.
*** WARNING ERROR 7 from SMPRR. The coefficient of variation of one or
*** both of the variables exceeds 10%. The confidence limits,
*** which are computed using a normal approximation, may not be
*** very accurate.
Example of Traceback
The next program illustrates a situation in which a traceback is produced. Although the traceback shows an error code associated with a terminal error, this code has no meaning to the user; the printed message contains all relevant information and it is not assumed that the user would take corrective action based on knowledge of the code.
USE IMSL_LIBRARIES
! Specifications for local variables
REAL A, B, ERRABS, ERRREL, RESULT, ERREST
! Specifications for common variables
REAL PIN, QIN, SAMP
COMMON PIN, QIN, SAMP
! Specifications for functions
EXTERNAL F
REAL F
! Compute the expected value of the
! maximum order statistic in a sample
! of size SAMP from a beta distribution.
A = 0.0
B = 1.0
ERRABS = 0.0
ERRREL = 0.001
! Initialize parameters for the beta
! order statistic of interest.
SAMP = 10.0
PIN = 2.0
QIN = -3.0
! The parameters for the beta must be
! nonnegative -- hence, the preceeding
! assignment causes an error.
CALL QDAGS (F, A, B, RESULT, ERRABS=ERRABS, ERREST=ERREST)
!
WRITE (*, *) RESULT, ERREST
END
!
REAL FUNCTION F (X)
USE BETDF_INT
REAL X, PIN, QIN, SAMP
COMMON PIN, QIN, SAMP
!
F = X*BETDF(X,PIN,QIN)**(SAMP-1.0)
RETURN
END
Output
*** TERMINAL ERROR 4 from BETDF. QIN = -3.000000E+00 must be greater than
*** 0.0.
Here is a traceback of subprogram calls in reverse order:
Routine name Error type Error code
------------ ---------- ----------
BETDF 5 4
Q2AGS 0 0 (Called internally)
QDAGS 0 0
USER 0 0
