This routine is not thread-safe ***PURPOSE Process error messages for SLATEC and other libraries.
***LIBRARY SLATEC (XERROR)
***CATEGORY R3C
***TYPE ALL (XERMSG-A)
***KEYWORDS ERROR MESSAGE, XERROR
***AUTHOR Fong, Kirby, (NMFECC at LLNL)
***DESCRIPTION
XERMSG processes a diagnostic message in a manner determined by the
value of LEVEL and the current value of the library error control
flag, KONTRL. See subroutine XSETF for details.
LIBRAR A character constant (or character variable) with the name
of the library. This will be 'SLATEC' for the SLATEC
Common Math Library. The error handling package is
general enough to be used by many libraries
simultaneously, so it is desirable for the routine that
detects and reports an error to identify the library name
as well as the routine name.
SUBROU A character constant (or character variable) with the name
of the routine that detected the error. Usually it is the
name of the routine that is calling XERMSG. There are
some instances where a user callable library routine calls
lower level subsidiary routines where the error is
detected. In such cases it may be more informative to
supply the name of the routine the user called rather than
the name of the subsidiary routine that detected the
error.
MESSG A character constant (or character variable) with the text
of the error or warning message. In the example below,
the message is a character constant that contains a
generic message.
CALL XERMSG ('SLATEC', 'MMPY',
*'THE ORDER OF THE MATRIX EXCEEDS THE ROW DIMENSION',
*3, 1)
It is possible (and is sometimes desirable) to generate a
specific message--e.g., one that contains actual numeric
values. Specific numeric values can be converted into
character strings using formatted WRITE statements into
character variables. This is called standard Fortran
internal file I/O and is exemplified in the first three
lines of the following example. You can also catenate
substrings of characters to construct the error message.
Here is an example showing the use of both writing to
an internal file and catenating character strings.
CHARACTER*5 CHARN, CHARL
WRITE (CHARN,10) N
WRITE (CHARL,10) LDA
10 FORMAT(I5)
CALL XERMSG ('SLATEC', 'MMPY', 'THE ORDER'//CHARN//
* ' OF THE MATRIX EXCEEDS ITS ROW DIMENSION OF'//
* CHARL, 3, 1)
There are two subtleties worth mentioning. One is that
the // for character catenation is used to construct the
error message so that no single character constant is
continued to the next line. This avoids confusion as to
whether there are trailing blanks at the end of the line.
The second is that by catenating the parts of the message
as an actual argument rather than encoding the entire
message into one large character variable, we avoid
having to know how long the message will be in order to
declare an adequate length for that large character
variable. XERMSG calls XERPRN to print the message using
multiple lines if necessary. If the message is very long,
XERPRN will break it into pieces of 72 characters (as
requested by XERMSG) for printing on multiple lines.
Also, XERMSG asks XERPRN to prefix each line with ' * '
so that the total line length could be 76 characters.
Note also that XERPRN scans the error message backwards
to ignore trailing blanks. Another feature is that
the substring '$$' is treated as a new line sentinel
by XERPRN. If you want to construct a multiline
message without having to count out multiples of 72
characters, just use '$$' as a separator. '$$'
obviously must occur within 72 characters of the
start of each line to have its intended effect since
XERPRN is asked to wrap around at 72 characters in
addition to looking for '$$'.
NERR An integer value that is chosen by the library routine's
author. It must be in the range -99 to 999 (three
printable digits). Each distinct error should have its
own error number. These error numbers should be described
in the machine readable documentation for the routine.
The error numbers need be unique only within each routine,
so it is reasonable for each routine to start enumerating
errors from 1 and proceeding to the next integer.
LEVEL An integer value in the range 0 to 2 that indicates the
level (severity) of the error. Their meanings are
-1 An error message. An error mesage is reported but no
abort is performed. This is used in mpi_mod before calling
MPI_ABORT.
0 A warning message. This is used if it is not clear
that there really is an error, but the user's attention
may be needed.
1 A recoverable error. This is used even if the error is
so serious that the routine cannot return any useful
answer. If the user has told the error package to
return after recoverable errors, then XERMSG will
return to the Library routine which can then return to
the user's routine. The user may also permit the error
package to terminate the program upon encountering a
recoverable error.
2 A fatal error. XERMSG will not return to its caller
after it receives a fatal error. This level should
hardly ever be used; it is much better to allow the
user a chance to recover. An example of one of the few
cases in which it is permissible to declare a level 2
error is a reverse communication Library routine that
is likely to be called repeatedly until it integrates
across some interval. If there is a serious error in
the input such that another step cannot be taken and
the Library routine is called again without the input
error having been corrected by the caller, the Library
routine will probably be called forever with improper
input. In this case, it is reasonable to declare the
error to be fatal.
Each of the arguments to XERMSG is input; none will be modified by
XERMSG. A routine may make multiple calls to XERMSG with warning
level messages; however, after a call to XERMSG with a recoverable
error, the routine should return to the user. Do not try to call
XERMSG with a second recoverable error after the first recoverable
error because the error package saves the error number. The user
can retrieve this error number by calling another entry point in
the error handling package and then clear the error number when
recovering from the error. Calling XERMSG in succession causes the
old error number to be overwritten by the latest error number.
This is considered harmless for error numbers associated with
warning messages but must not be done for error numbers of serious
errors. After a call to XERMSG with a recoverable error, the user
must be given a chance to call NUMXER or XERCLR to retrieve or
clear the error number.
***REFERENCES R. E. Jones and D. K. Kahaner, XERROR, the SLATEC
Error-handling Package, SAND82-0800, Sandia
Laboratories, 1982. 