NAME¶
ICFELL - Called to check for existing error conditions and (perhaps) to update
the current error message and error flag.
SYNOPSIS¶
NERR = ICFELL(MESSG,NERRF)
C-BINDING SYNOPSIS¶
#include <ncarg/ncargC.h>
int c_icfell(char *messg, int nerrf)
DESCRIPTION¶
ICFELL (which stands for "I Check For Errors on Lower Level") is used
to check for the occurrence of a recoverable error in a lower-level routine
and (perhaps) to update the current internal error message and error flag.
The old value of the error flag is returned as the value of the function ICFELL.
If that value is zero, nothing else has been done. If the value of ICFELL is
non-zero, the following actions have been taken:
- -
- If MESSG is blank, the current error message has not been changed.
- -
- If MESSG is non-blank and its length is 6 or less, it should be the name
of the routine referencing ICFELL; the current error message has been
altered by prepending first a slash and then MESSG. (Note that, if an
error occurs several levels deep, the effect of using ICFELL in this
manner at each level is, effectively, to generate traceback information in
the error message.)
- -
- If MESSG is non-blank and its length is 7 or greater, its value has become
the new value of the current error message and the previous error message
has been printed. This is intended for use at the beginning of an NCAR
Graphics routine to check for an outstanding error that the user has not
recovered from and to ensure that the message for the outstanding error
gets printed.
- -
- If the expression NERRF has the value zero, the current error flag has not
been changed.
- -
- If the expression NERRF has a non-zero value, the value of the current
error flag has been made equal to that value.
An example: Assume that the routine "A" calls the routine
"B" and that "B" detects an error and calls SETER with
error number "32" and error message "B - ERROR HAS
OCCURRED". If recovery mode is not in effect, SETER prints the error
message and STOPs; if recovery mode is in effect, control returns from
"SETER" to "B" and thence to "A". At that point,
the statement "IF (ICFELL('A',13).NE.0) RETURN" detects the fact
that an error has occurred in "B" and results in a return from
"A" to whatever routine called it. It also changes the current error
message to read 'A/B - ERROR HAS OCCURRED' and changes the error number from
"32" to "13".
Another example: Assume that the NCAR Graphics routine "A" is called
when recovery mode is set and that it detects an error, calls SETER, and
RETURNs to the user. If the user neglects to check the error state and calls
the routine "B" next, the statement "IF (ICFELL('B - UNCLEARED
PRIOR ERROR',1).NE.0) RETURN" ensures that the error message from routine
"A" will be printed, that it will be replaced by an error message
referring to the routine "B", and that "B" won't do
anything else.
The arguments of ICFELL are as follows:
- MESSG
- (an input variable or constant of type CHARACTER) - A character string
saying what is to be done to the current error message (when an error has
occurred). If MESSG is blank, no change is to be made in the current error
message. If the length of MESSG is six characters or fewer, a slash is
prepended to the current error message and then MESSG is prepended to
that. If the length of MESSG is seven characters or more, MESSG is a
complete new error message to be substituted for the current one; it
should be of the form "XXXXXX - TEXT DESCRIBING THE ERROR",
where "XXXXXX" is the name of the routine in which the error
occurred, and it should not be more than 113 characters long.
- NERRF
- (an input expression of type INTEGER) - A value in the range from -999 to
+9999. If this value is zero, no change is made in the internal error
flag; otherwise, it is the desired new value of that flag (when an error
has occurred).
C-BINDING DESCRIPTION¶
The C-binding argument descriptions are the same as the FORTRAN argument
descriptions.
EXAMPLES¶
Use the ncargex command to see the following relevant examples: tseter, arex02.
ACCESS¶
To use ICFELL or c_icfell, load the NCAR Graphics libraries ncarg, ncarg_gks,
and ncarg_c, preferably in that order.
SEE ALSO¶
Online: entsr, eprin, errof, error_handling, fdum, icloem, nerro, retsr, semess,
seter, ncarg_cbind
COPYRIGHT¶
Copyright (C) 1987-2009
University Corporation for Atmospheric Research
The use of this Software is governed by a License Agreement.