1Error_handling(3NCARG) NCAR GRAPHICS Error_handling(3NCARG)
2
6 Error_handling - A set of routines for error handling in NCAR Graphics.
7
9 ENTSR - Enters recovery mode.
10 EPRIN - Prints the current error message.
11 ERROF - Turns off the internal error flag.
12 FDUM - A dump routine - the default version just RETURNS.
13 ICFELL - Checks for an outstanding error condition.
14 ICLOEM - Computes the real length of its character-string argument
15 (ignoring blanks on the end)
16 NERRO - Gets the current value of the internal error flag.
17 RETSR - Restores a previous value of the internal error flag.
18 SEMESS - Gets a specified portion of the current error message.
19 SETER - Called by NCAR Graphics routines to report error conditions.
20
22 #include <ncarg/ncargC.h>
23 c_entsr
25 c_eprin
26 c_errof
27 c_icfell
28 c_icloem
29 c_nerro
30 c_retsr
31 c_semess
32 c_seter
33
36 There are specific conventions for the use of SETER within NCAR
37 Graphics, as follows:
38 - All detectable errors shall be recoverable, in the sense described
40 above. (That is, in every call to SETER, the final argument shall
41 be a 1, rather than a 2.) This is by request of the folks doing
42 NCAR Interactive, who rightly consider STOPs in the utilities
43 undesirable. The idea is to let the user decide what is to be done
44 about the various error conditions.
45 - Whenever an NCAR Graphics routine calls a lower-level routine that
47 might detect an error and call SETER, it should subsequently use
48 ICFELL to check the error state; if a recoverable error has
49 occurred, it should first do required clean-up chores, if possible,
50 and then pass control back to the routine that called it. In all
51 such uses of ICFELL, the first argument should be the name of the
52 routine referencing ICFELL and the second argument should be a new
53 number for the error, reflecting the position of the reference to
54 the lower-level routine in the upper-level routine.
55 - Any NCAR Graphics routine that can be called by a user and that can
57 potentially yield a call to SETER must immediately check the error
58 state and, if that error state is non-zero, return control without
59 doing anything else. This is most conveniently done using a
60 reference to ICFELL; see the second example in the "Usage" section
61 of the description of ICFELL. All such references should have a
62 first argument of the form 'XXXXXX - UNCLEARED PRIOR ERROR', where
63 "XXXXXX" is the name of the routine in which the reference occurs,
64 and a second argument equal to "1".
65 - It is recommended that, within a given utility routine, the error
67 numbers in references to SETER and ICFELL should start at 1 and
68 increment by 1. These numbers generally have no intrinsic meaning
69 in and of themselves: they are merely intended to allow a
70 consultant to find the reference that generated a given error.
71 - NCAR Graphics routines are not required to turn recovery mode on
73 before calling a lower-level routine that might call SETER (which
74 was the convention in the PORT library, as described in the PORT
75 document). Instead, the assumption is that it is the
76 responsibility of the user of NCAR Graphics to set recovery mode if
77 he/she desires to do recovery. Since, by default, recovery mode is
78 turned off, all NCAR Graphics calls to SETER will be treated as
79 fatal: the error message will be printed and execution will be
80 terminated. Once the user turns recovery mode on, however, no NCAR
81 Graphics error will be treated in this way except for one that the
82 user fails to recover from.
83 Note: These conventions are being adopted as of December 2, 1993, and
85 represent a goal for the future. The current situation is somewhat
86 muddled: In some utilities, all SETER calls are fatal ones. In other
87 utilities, some SETER calls are fatal and some are not. In other
88 utilities, no SETER calls are fatal. In general, errors at a lower
89 level are not detected and passed back up the call chain. Users have
90 complained (and rightly so) that error recovery is, in general, not
91 possible; observance of these conventions should help to fix the
92 situation.
93 Further note: As of March 30, 1994, the situation has improved
95 markedly. CONPACK and all utilities referenced by it have been updated
96 to follow the guidelines given above and work is proceeding on other
97 utilities.
98 There is one sticky area in which questions remains to be answered:
100 Sometimes, when an error condition occurs during execution of a utility
101 routine that has changed the internal state of GKS or SPPS, it has not
102 been possible to restore the state of those packages to exactly what it
103 was before that routine was entered. In some cases, better bookkeeping
104 would allow restoration to be done; in other cases, though, restoration
105 would involve calling a routine that could generate a call to SETER,
106 which would cause a STOP. In the latter cases, I have not yet worked
107 out a good solution. For the moment, therefore, the situation is this:
108 if you call an NCAR Graphics utility with recovery mode turned on and,
109 when you get control back, you find that an error has occurred, you
110 must be prepared to deal with the possibility that at least the
111 following things might been changed: 1) the current SET call; 2) the
112 current polyline color index; 3) the current polymarker color index; 4)
113 the current text color index; 5) the current fill area color index; 6)
114 the current dash pattern.
115
117 To use the Error_handling C or Fortran routines, load the NCAR Graphics
118 libraries ncarg, ncarg_gks, and ncarg_c, preferably in that order.
119
122 Online: entsr, eprin, errof, fdum, icfell, icloem, nerro, retsr,
123 semess, seter, ncarg_cbind
124
126 Copyright (C) 1987-2007
127 University Corporation for Atmospheric Research
128 This documentation is free software; you can redistribute it and/or
130 modify it under the terms of the GNU General Public License as
131 published by the Free Software Foundation; either version 2 of the
132 License, or (at your option) any later version.
133 This software is distributed in the hope that it will be useful, but
135 WITHOUT ANY WARRANTY; without even the implied warranty of
136 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
137 General Public License for more details.
138 You should have received a copy of the GNU General Public License along
140 with this software; if not, write to the Free Software Foundation,
141 Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
142UNIX March 1994 Error_handling(3NCARG)