GCC Code Coverage Report


Directory: ./
File: misc/xermsg.f
Date: 2022-01-11 19:19:34
Exec Total Coverage
Lines: 0 65 0.0%
Branches: 0 80 0.0%

Line Branch Exec Source
1 *DECK XERMSG
2 SUBROUTINE XERMSG (LIBRAR, SUBROU, MESSG, NERR, LEVEL)
3 IMPLICIT NONE
4 C***BEGIN PROLOGUE XERMSG
5 C***PURPOSE Process error messages for SLATEC and other libraries.
6 C***LIBRARY SLATEC (XERROR)
7 C***CATEGORY R3C
8 C***TYPE ALL (XERMSG-A)
9 C***KEYWORDS ERROR MESSAGE, XERROR
10 C***AUTHOR Fong, Kirby, (NMFECC at LLNL)
11 C***DESCRIPTION
12 C
13 C XERMSG processes a diagnostic message in a manner determined by the
14 C value of LEVEL and the current value of the library error control
15 C flag, KONTRL. See subroutine XSETF for details.
16 C
17 C LIBRAR A character constant (or character variable) with the name
18 C of the library. This will be 'SLATEC' for the SLATEC
19 C Common Math Library. The error handling package is
20 C general enough to be used by many libraries
21 C simultaneously, so it is desirable for the routine that
22 C detects and reports an error to identify the library name
23 C as well as the routine name.
24 C
25 C SUBROU A character constant (or character variable) with the name
26 C of the routine that detected the error. Usually it is the
27 C name of the routine that is calling XERMSG. There are
28 C some instances where a user callable library routine calls
29 C lower level subsidiary routines where the error is
30 C detected. In such cases it may be more informative to
31 C supply the name of the routine the user called rather than
32 C the name of the subsidiary routine that detected the
33 C error.
34 C
35 C MESSG A character constant (or character variable) with the text
36 C of the error or warning message. In the example below,
37 C the message is a character constant that contains a
38 C generic message.
39 C
40 C CALL XERMSG ('SLATEC', 'MMPY',
41 C *'THE ORDER OF THE MATRIX EXCEEDS THE ROW DIMENSION',
42 C *3, 1)
43 C
44 C It is possible (and is sometimes desirable) to generate a
45 C specific message--e.g., one that contains actual numeric
46 C values. Specific numeric values can be converted into
47 C character strings using formatted WRITE statements into
48 C character variables. This is called standard Fortran
49 C internal file I/O and is exemplified in the first three
50 C lines of the following example. You can also catenate
51 C substrings of characters to construct the error message.
52 C Here is an example showing the use of both writing to
53 C an internal file and catenating character strings.
54 C
55 C CHARACTER*5 CHARN, CHARL
56 C WRITE (CHARN,10) N
57 C WRITE (CHARL,10) LDA
58 C 10 FORMAT(I5)
59 C CALL XERMSG ('SLATEC', 'MMPY', 'THE ORDER'//CHARN//
60 C * ' OF THE MATRIX EXCEEDS ITS ROW DIMENSION OF'//
61 C * CHARL, 3, 1)
62 C
63 C There are two subtleties worth mentioning. One is that
64 C the // for character catenation is used to construct the
65 C error message so that no single character constant is
66 C continued to the next line. This avoids confusion as to
67 C whether there are trailing blanks at the end of the line.
68 C The second is that by catenating the parts of the message
69 C as an actual argument rather than encoding the entire
70 C message into one large character variable, we avoid
71 C having to know how long the message will be in order to
72 C declare an adequate length for that large character
73 C variable. XERMSG calls XERPRN to print the message using
74 C multiple lines if necessary. If the message is very long,
75 C XERPRN will break it into pieces of 72 characters (as
76 C requested by XERMSG) for printing on multiple lines.
77 C Also, XERMSG asks XERPRN to prefix each line with ' * '
78 C so that the total line length could be 76 characters.
79 C Note also that XERPRN scans the error message backwards
80 C to ignore trailing blanks. Another feature is that
81 C the substring '$$' is treated as a new line sentinel
82 C by XERPRN. If you want to construct a multiline
83 C message without having to count out multiples of 72
84 C characters, just use '$$' as a separator. '$$'
85 C obviously must occur within 72 characters of the
86 C start of each line to have its intended effect since
87 C XERPRN is asked to wrap around at 72 characters in
88 C addition to looking for '$$'.
89 C
90 C NERR An integer value that is chosen by the library routine's
91 C author. It must be in the range -99 to 999 (three
92 C printable digits). Each distinct error should have its
93 C own error number. These error numbers should be described
94 C in the machine readable documentation for the routine.
95 C The error numbers need be unique only within each routine,
96 C so it is reasonable for each routine to start enumerating
97 C errors from 1 and proceeding to the next integer.
98 C
99 C LEVEL An integer value in the range 0 to 2 that indicates the
100 C level (severity) of the error. Their meanings are
101 C
102 C -1 A warning message. This is used if it is not clear
103 C that there really is an error, but the user's attention
104 C may be needed. An attempt is made to only print this
105 C message once.
106 C
107 C 0 A warning message. This is used if it is not clear
108 C that there really is an error, but the user's attention
109 C may be needed.
110 C
111 C 1 A recoverable error. This is used even if the error is
112 C so serious that the routine cannot return any useful
113 C answer. If the user has told the error package to
114 C return after recoverable errors, then XERMSG will
115 C return to the Library routine which can then return to
116 C the user's routine. The user may also permit the error
117 C package to terminate the program upon encountering a
118 C recoverable error.
119 C
120 C 2 A fatal error. XERMSG will not return to its caller
121 C after it receives a fatal error. This level should
122 C hardly ever be used; it is much better to allow the
123 C user a chance to recover. An example of one of the few
124 C cases in which it is permissible to declare a level 2
125 C error is a reverse communication Library routine that
126 C is likely to be called repeatedly until it integrates
127 C across some interval. If there is a serious error in
128 C the input such that another step cannot be taken and
129 C the Library routine is called again without the input
130 C error having been corrected by the caller, the Library
131 C routine will probably be called forever with improper
132 C input. In this case, it is reasonable to declare the
133 C error to be fatal.
134 C
135 C Each of the arguments to XERMSG is input; none will be modified by
136 C XERMSG. A routine may make multiple calls to XERMSG with warning
137 C level messages; however, after a call to XERMSG with a recoverable
138 C error, the routine should return to the user. Do not try to call
139 C XERMSG with a second recoverable error after the first recoverable
140 C error because the error package saves the error number. The user
141 C can retrieve this error number by calling another entry point in
142 C the error handling package and then clear the error number when
143 C recovering from the error. Calling XERMSG in succession causes the
144 C old error number to be overwritten by the latest error number.
145 C This is considered harmless for error numbers associated with
146 C warning messages but must not be done for error numbers of serious
147 C errors. After a call to XERMSG with a recoverable error, the user
148 C must be given a chance to call NUMXER or XERCLR to retrieve or
149 C clear the error number.
150 C***REFERENCES R. E. Jones and D. K. Kahaner, XERROR, the SLATEC
151 C Error-handling Package, SAND82-0800, Sandia
152 C Laboratories, 1982.
153 C***ROUTINES CALLED FDUMP, J4SAVE, XERCNT, XERHLT, XERPRN, XERSVE
154 C***REVISION HISTORY (YYMMDD)
155 C 880101 DATE WRITTEN
156 C 880621 REVISED AS DIRECTED AT SLATEC CML MEETING OF FEBRUARY 1988.
157 C THERE ARE TWO BASIC CHANGES.
158 C 1. A NEW ROUTINE, XERPRN, IS USED INSTEAD OF XERPRT TO
159 C PRINT MESSAGES. THIS ROUTINE WILL BREAK LONG MESSAGES
160 C INTO PIECES FOR PRINTING ON MULTIPLE LINES. '$$' IS
161 C ACCEPTED AS A NEW LINE SENTINEL. A PREFIX CAN BE
162 C ADDED TO EACH LINE TO BE PRINTED. XERMSG USES EITHER
163 C ' ***' OR ' * ' AND LONG MESSAGES ARE BROKEN EVERY
164 C 72 CHARACTERS (AT MOST) SO THAT THE MAXIMUM LINE
165 C LENGTH OUTPUT CAN NOW BE AS GREAT AS 76.
166 C 2. THE TEXT OF ALL MESSAGES IS NOW IN UPPER CASE SINCE THE
167 C FORTRAN STANDARD DOCUMENT DOES NOT ADMIT THE EXISTENCE
168 C OF LOWER CASE.
169 C 880708 REVISED AFTER THE SLATEC CML MEETING OF JUNE 29 AND 30.
170 C THE PRINCIPAL CHANGES ARE
171 C 1. CLARIFY COMMENTS IN THE PROLOGUES
172 C 2. RENAME XRPRNT TO XERPRN
173 C 3. REWORK HANDLING OF '$$' IN XERPRN TO HANDLE BLANK LINES
174 C SIMILAR TO THE WAY FORMAT STATEMENTS HANDLE THE /
175 C CHARACTER FOR NEW RECORDS.
176 C 890706 REVISED WITH THE HELP OF FRED FRITSCH AND REG CLEMENS TO
177 C CLEAN UP THE CODING.
178 C 890721 REVISED TO USE NEW FEATURE IN XERPRN TO COUNT CHARACTERS IN
179 C PREFIX.
180 C 891013 REVISED TO CORRECT COMMENTS.
181 C 891214 Prologue converted to Version 4.0 format. (WRB)
182 C 900510 Changed test on NERR to be -9999999 < NERR < 99999999, but
183 C NERR .ne. 0, and on LEVEL to be -2 < LEVEL < 3. Added
184 C LEVEL=-1 logic, changed calls to XERSAV to XERSVE, and
185 C XERCTL to XERCNT. (RWC)
186 C 920501 Reformatted the REFERENCES section. (WRB)
187 C***END PROLOGUE XERMSG
188 CHARACTER*(*) LIBRAR, SUBROU, MESSG
189 CHARACTER*8 XLIBR, XSUBR
190 CHARACTER*72 TEMP
191 CHARACTER*20 LFIRST
192 INTEGER NERR, LEVEL, LKNTRL
193 INTEGER J4SAVE, MAXMES, KDUMMY, I, KOUNT, LERR, LLEVEL
194 INTEGER MKNTRL, LTEMP
195 C***FIRST EXECUTABLE STATEMENT XERMSG
196 LKNTRL = J4SAVE (2, 0, .FALSE.)
197 MAXMES = J4SAVE (4, 0, .FALSE.)
198 C
199 C LKNTRL IS A LOCAL COPY OF THE CONTROL FLAG KONTRL.
200 C MAXMES IS THE MAXIMUM NUMBER OF TIMES ANY PARTICULAR MESSAGE
201 C SHOULD BE PRINTED.
202 C
203 C WE PRINT A FATAL ERROR MESSAGE AND TERMINATE FOR AN ERROR IN
204 C CALLING XERMSG. THE ERROR NUMBER SHOULD BE POSITIVE,
205 C AND THE LEVEL SHOULD BE BETWEEN 0 AND 2.
206 C
207 IF (NERR.LT.-9999999 .OR. NERR.GT.99999999 .OR. NERR.EQ.0 .OR.
208 * LEVEL.LT.-1 .OR. LEVEL.GT.2) THEN
209 CALL XERPRN (' ***', -1, 'FATAL ERROR IN...$$ ' //
210 * 'XERMSG -- INVALID ERROR NUMBER OR LEVEL$$ '//
211 * 'JOB ABORT DUE TO FATAL ERROR.', 72)
212 CALL XERSVE (' ', ' ', ' ', 0, 0, 0, KDUMMY)
213 CALL XERHLT (' ***XERMSG -- INVALID INPUT')
214 RETURN
215 ENDIF
216 C
217 C RECORD THE MESSAGE.
218 C
219 I = J4SAVE (1, NERR, .TRUE.)
220 CALL XERSVE (LIBRAR, SUBROU, MESSG, 1, NERR, LEVEL, KOUNT)
221 C
222 C HANDLE PRINT-ONCE WARNING MESSAGES.
223 C
224 IF (LEVEL.EQ.-1 .AND. KOUNT.GT.1) RETURN
225 C
226 C ALLOW TEMPORARY USER OVERRIDE OF THE CONTROL FLAG.
227 C
228 XLIBR = LIBRAR
229 XSUBR = SUBROU
230 LFIRST = MESSG
231 LERR = NERR
232 LLEVEL = LEVEL
233 CALL XERCNT (XLIBR, XSUBR, LFIRST, LERR, LLEVEL, LKNTRL)
234 C
235 LKNTRL = MAX(-2, MIN(2,LKNTRL))
236 MKNTRL = ABS(LKNTRL)
237 C
238 C SKIP PRINTING IF THE CONTROL FLAG VALUE AS RESET IN XERCNT IS
239 C ZERO AND THE ERROR IS NOT FATAL.
240 C
241 IF (LEVEL.LT.2 .AND. LKNTRL.EQ.0) GO TO 30
242 IF (LEVEL.EQ.0 .AND. KOUNT.GT.MAXMES) GO TO 30
243 IF (LEVEL.EQ.1 .AND. KOUNT.GT.MAXMES .AND. MKNTRL.EQ.1) GO TO 30
244 IF (LEVEL.EQ.2 .AND. KOUNT.GT.MAX(1,MAXMES)) GO TO 30
245 C
246 C ANNOUNCE THE NAMES OF THE LIBRARY AND SUBROUTINE BY BUILDING A
247 C MESSAGE IN CHARACTER VARIABLE TEMP (NOT EXCEEDING 66 CHARACTERS)
248 C AND SENDING IT OUT VIA XERPRN. PRINT ONLY IF CONTROL FLAG
249 C IS NOT ZERO.
250 C
251 IF (LKNTRL .NE. 0) THEN
252 TEMP(1:21) = 'MESSAGE FROM ROUTINE '
253 I = MIN(LEN(SUBROU), 16)
254 TEMP(22:21+I) = SUBROU(1:I)
255 TEMP(22+I:33+I) = ' IN LIBRARY '
256 LTEMP = 33 + I
257 I = MIN(LEN(LIBRAR), 16)
258 TEMP(LTEMP+1:LTEMP+I) = LIBRAR (1:I)
259 TEMP(LTEMP+I+1:LTEMP+I+1) = '.'
260 LTEMP = LTEMP + I + 1
261 CALL XERPRN (' ***', -1, TEMP(1:LTEMP), 72)
262 ENDIF
263 C
264 C IF LKNTRL IS POSITIVE, PRINT AN INTRODUCTORY LINE BEFORE
265 C PRINTING THE MESSAGE. THE INTRODUCTORY LINE TELLS THE CHOICE
266 C FROM EACH OF THE FOLLOWING THREE OPTIONS.
267 C 1. LEVEL OF THE MESSAGE
268 C 'INFORMATIVE MESSAGE'
269 C 'POTENTIALLY RECOVERABLE ERROR'
270 C 'FATAL ERROR'
271 C 2. WHETHER CONTROL FLAG WILL ALLOW PROGRAM TO CONTINUE
272 C 'PROG CONTINUES'
273 C 'PROG ABORTED'
274 C 3. WHETHER OR NOT A TRACEBACK WAS REQUESTED. (THE TRACEBACK
275 C MAY NOT BE IMPLEMENTED AT SOME SITES, SO THIS ONLY TELLS
276 C WHAT WAS REQUESTED, NOT WHAT WAS DELIVERED.)
277 C 'TRACEBACK REQUESTED'
278 C 'TRACEBACK NOT REQUESTED'
279 C NOTICE THAT THE LINE INCLUDING FOUR PREFIX CHARACTERS WILL NOT
280 C EXCEED 74 CHARACTERS.
281 C WE SKIP THE NEXT BLOCK IF THE INTRODUCTORY LINE IS NOT NEEDED.
282 C
283 IF (LKNTRL .GT. 0) THEN
284 C
285 C THE FIRST PART OF THE MESSAGE TELLS ABOUT THE LEVEL.
286 C
287 IF (LEVEL .LE. 0) THEN
288 TEMP(1:20) = 'INFORMATIVE MESSAGE,'
289 LTEMP = 20
290 ELSEIF (LEVEL .EQ. 1) THEN
291 TEMP(1:30) = 'POTENTIALLY RECOVERABLE ERROR,'
292 LTEMP = 30
293 ELSE
294 TEMP(1:12) = 'FATAL ERROR,'
295 LTEMP = 12
296 ENDIF
297 C
298 C THEN WHETHER THE PROGRAM WILL CONTINUE.
299 C
300 IF ((MKNTRL.EQ.2 .AND. LEVEL.GE.1) .OR.
301 * (MKNTRL.EQ.1 .AND. LEVEL.EQ.2)) THEN
302 TEMP(LTEMP+1:LTEMP+14) = ' PROG ABORTED,'
303 LTEMP = LTEMP + 14
304 ELSE
305 TEMP(LTEMP+1:LTEMP+16) = ' PROG CONTINUES,'
306 LTEMP = LTEMP + 16
307 ENDIF
308 C
309 C FINALLY TELL WHETHER THERE SHOULD BE A TRACEBACK.
310 C
311 IF (LKNTRL .GT. 0) THEN
312 TEMP(LTEMP+1:LTEMP+20) = ' TRACEBACK REQUESTED'
313 LTEMP = LTEMP + 20
314 ELSE
315 TEMP(LTEMP+1:LTEMP+24) = ' TRACEBACK NOT REQUESTED'
316 LTEMP = LTEMP + 24
317 ENDIF
318 CALL XERPRN (' ***', -1, TEMP(1:LTEMP), 72)
319 ENDIF
320 C
321 C NOW SEND OUT THE MESSAGE.
322 C
323 CALL XERPRN (' * ', -1, MESSG, 72)
324 C
325 C IF LKNTRL IS POSITIVE, WRITE THE ERROR NUMBER AND REQUEST A
326 C TRACEBACK.
327 C
328 IF (LKNTRL .GT. 0) THEN
329 WRITE (TEMP, '(''ERROR NUMBER = '', I8)') NERR
330 DO 10 I=16,22
331 IF (TEMP(I:I) .NE. ' ') GO TO 20
332 10 CONTINUE
333 C
334 20 CALL XERPRN (' * ', -1, TEMP(1:15) // TEMP(I:23), 72)
335 CALL FDUMP
336 ENDIF
337 C
338 C IF LKNTRL IS NOT ZERO, PRINT A BLANK LINE AND AN END OF MESSAGE.
339 C
340 IF (LKNTRL .NE. 0) THEN
341 CALL XERPRN (' * ', -1, ' ', 72)
342 CALL XERPRN (' ***', -1, 'END OF MESSAGE', 72)
343 CALL XERPRN (' ', 0, ' ', 72)
344 ENDIF
345 C
346 C IF THE ERROR IS NOT FATAL OR THE ERROR IS RECOVERABLE AND THE
347 C CONTROL FLAG IS SET FOR RECOVERY, THEN RETURN.
348 C
349 30 IF (LEVEL.LE.0 .OR. (LEVEL.EQ.1 .AND. MKNTRL.LE.1)) RETURN
350 C
351 C THE PROGRAM WILL BE STOPPED DUE TO AN UNRECOVERED ERROR OR A
352 C FATAL ERROR. PRINT THE REASON FOR THE ABORT AND THE ERROR
353 C SUMMARY IF THE CONTROL FLAG AND THE MAXIMUM ERROR COUNT PERMIT.
354 C
355 IF (LKNTRL.GT.0 .AND. KOUNT.LT.MAX(1,MAXMES)) THEN
356 IF (LEVEL .EQ. 1) THEN
357 CALL XERPRN
358 * (' ***', -1, 'JOB ABORT DUE TO UNRECOVERED ERROR.', 72)
359 ELSE
360 CALL XERPRN(' ***', -1, 'JOB ABORT DUE TO FATAL ERROR.', 72)
361 ENDIF
362 CALL XERSVE (' ', ' ', ' ', -1, 0, 0, KDUMMY)
363 CALL XERHLT (' ')
364 ELSE
365 CALL XERHLT (MESSG)
366 ENDIF
367 RETURN
368 END
369