1ICFELL(3NCARG) NCAR GRAPHICS ICFELL(3NCARG)
2
6 ICFELL - Called to check for existing error conditions and (perhaps) to
7 update the current error message and error flag.
8
10 NERR = ICFELL(MESSG,NERRF)
11
13 #include <ncarg/ncargC.h>
14 int c_icfell(char *messg, int nerrf)
16
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 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 - If MESSG is blank, the current error message has not been changed.
28 - 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 - 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 - If the expression NERRF has the value zero, the current error flag
44 has not been changed.
45 - 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 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 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 The arguments of ICFELL are as follows:
70 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 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
92 The C-binding argument descriptions are the same as the FORTRAN
93 argument descriptions.
94
96 Use the ncargex command to see the following relevant examples: tseter,
97 arex02.
98
100 To use ICFELL or c_icfell, load the NCAR Graphics libraries ncarg,
101 ncarg_gks, and ncarg_c, preferably in that order.
102
104 Online: entsr, eprin, errof, error_handling, fdum, icloem, nerro,
105 retsr, semess, seter, ncarg_cbind
106
108 Copyright (C) 1987-2007
109 University Corporation for Atmospheric Research
110 This documentation is free software; you can redistribute it and/or
112 modify it under the terms of the GNU General Public License as
113 published by the Free Software Foundation; either version 2 of the
114 License, or (at your option) any later version.
115 This software is distributed in the hope that it will be useful, but
117 WITHOUT ANY WARRANTY; without even the implied warranty of
118 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
119 General Public License for more details.
120 You should have received a copy of the GNU General Public License along
122 with this software; if not, write to the Free Software Foundation,
123 Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
124UNIX March 1994 ICFELL(3NCARG)