1ICFELL(3NCARG)                   NCAR GRAPHICS                  ICFELL(3NCARG)
2
3
4

NAME

6       ICFELL - Called to check for existing error conditions and (perhaps) to
7       update the current error message and error flag.
8

SYNOPSIS

10       NERR = ICFELL(MESSG,NERRF)
11

C-BINDING SYNOPSIS

13       #include <ncarg/ncargC.h>
14
15       int c_icfell(char *messg, int nerrf)
16

DESCRIPTION

18       ICFELL (which stands for "I Check For Errors on Lower Level") is used
19       to check for the occurrence of a recoverable error in a lower-level
20       routine and (perhaps) to update the current internal error message and
21       error flag.
22
23       The old value of the error flag is returned as the value of the
24       function ICFELL. If that value is zero, nothing else has been done. If
25       the value of ICFELL is non-zero, the following actions have been taken:
26
27        -  If MESSG is blank, the current error message has not been changed.
28
29        -  If MESSG is non-blank and its length is 6 or less, it should be the
30           name of the routine referencing ICFELL; the current error message
31           has been altered by prepending first a slash and then MESSG. (Note
32           that, if an error occurs several levels deep, the effect of using
33           ICFELL in this manner at each level is, effectively, to generate
34           traceback information in the error message.)
35
36        -  If MESSG is non-blank and its length is 7 or greater, its value has
37           become the new value of the current error message and the previous
38           error message has been printed. This is intended for use at the
39           beginning of an NCAR Graphics routine to check for an outstanding
40           error that the user has not recovered from and to ensure that the
41           message for the outstanding error gets printed.
42
43        -  If the expression NERRF has the value zero, the current error flag
44           has not been changed.
45
46        -  If the expression NERRF has a non-zero value, the value of the
47           current error flag has been made equal to that value.
48
49       An example: Assume that the routine "A" calls the routine "B" and that
50       "B" detects an error and calls SETER with error number "32" and error
51       message "B - ERROR HAS OCCURRED". If recovery mode is not in effect,
52       SETER prints the error message and STOPs; if recovery mode is in
53       effect, control returns from "SETER" to "B" and thence to "A". At that
54       point, the statement "IF (ICFELL('A',13).NE.0) RETURN" detects the fact
55       that an error has occurred in "B" and results in a return from "A" to
56       whatever routine called it. It also changes the current error message
57       to read 'A/B - ERROR HAS OCCURRED' and changes the error number from
58       "32" to "13".
59
60       Another example: Assume that the NCAR Graphics routine "A" is called
61       when recovery mode is set and that it detects an error, calls SETER,
62       and RETURNs to the user. If the user neglects to check the error state
63       and calls the routine "B" next, the statement "IF (ICFELL('B -
64       UNCLEARED PRIOR ERROR',1).NE.0) RETURN" ensures that the error message
65       from routine "A" will be printed, that it will be replaced by an error
66       message referring to the routine "B", and that "B" won't do anything
67       else.
68
69       The arguments of ICFELL are as follows:
70
71
72       MESSG       (an input variable or constant of type CHARACTER) - A
73                   character string saying what is to be done to the current
74                   error message (when an error has occurred).  If MESSG is
75                   blank, no change is to be made in the current error
76                   message. If the length of MESSG is six characters or fewer,
77                   a slash is prepended to the current error message and then
78                   MESSG is prepended to that. If the length of MESSG is seven
79                   characters or more, MESSG is a complete new error message
80                   to be substituted for the current one; it should be of the
81                   form "XXXXXX - TEXT DESCRIBING THE ERROR", where "XXXXXX"
82                   is the name of the routine in which the error occurred, and
83                   it should not be more than 113 characters long.
84
85       NERRF       (an input expression of type INTEGER) - A value in the
86                   range from -999 to +9999. If this value is zero, no change
87                   is made in the internal error flag; otherwise, it is the
88                   desired new value of that flag (when an error has
89                   occurred).
90

C-BINDING DESCRIPTION

92       The C-binding argument descriptions are the same as the FORTRAN
93       argument descriptions.
94

EXAMPLES

96       Use the ncargex command to see the following relevant examples: tseter,
97       arex02.
98

ACCESS

100       To use ICFELL or c_icfell, load the NCAR Graphics libraries ncarg,
101       ncarg_gks, and ncarg_c, preferably in that order.
102

SEE ALSO

104       Online: entsr, eprin, errof, error_handling, fdum, icloem, nerro,
105       retsr, semess, seter, ncarg_cbind
106

108       Copyright (C) 1987-2009
109       University Corporation for Atmospheric Research
110       The use of this Software is governed by a License Agreement.
111
112
113
114UNIX                              March 1994                    ICFELL(3NCARG)
Impressum