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.

UNIX                                               March 1994                                     ICFELL(3NCARG)