SLATEC Routines --- XERMSG ---
*DECK XERMSG
SUBROUTINE XERMSG (LIBRAR, SUBROU, MESSG, NERR, LEVEL)
C***BEGIN PROLOGUE XERMSG
C***PURPOSE Process error messages for SLATEC and other libraries.
C***LIBRARY SLATEC (XERROR)
C***CATEGORY R3C
C***TYPE ALL (XERMSG-A)
C***KEYWORDS ERROR MESSAGE, XERROR
C***AUTHOR Fong, Kirby, (NMFECC at LLNL)
C***DESCRIPTION
C
C XERMSG processes a diagnostic message in a manner determined by the
C value of LEVEL and the current value of the library error control
C flag, KONTRL. See subroutine XSETF for details.
C
C LIBRAR A character constant (or character variable) with the name
C of the library. This will be 'SLATEC' for the SLATEC
C Common Math Library. The error handling package is
C general enough to be used by many libraries
C simultaneously, so it is desirable for the routine that
C detects and reports an error to identify the library name
C as well as the routine name.
C
C SUBROU A character constant (or character variable) with the name
C of the routine that detected the error. Usually it is the
C name of the routine that is calling XERMSG. There are
C some instances where a user callable library routine calls
C lower level subsidiary routines where the error is
C detected. In such cases it may be more informative to
C supply the name of the routine the user called rather than
C the name of the subsidiary routine that detected the
C error.
C
C MESSG A character constant (or character variable) with the text
C of the error or warning message. In the example below,
C the message is a character constant that contains a
C generic message.
C
C CALL XERMSG ('SLATEC', 'MMPY',
C *'THE ORDER OF THE MATRIX EXCEEDS THE ROW DIMENSION',
C *3, 1)
C
C It is possible (and is sometimes desirable) to generate a
C specific message--e.g., one that contains actual numeric
C values. Specific numeric values can be converted into
C character strings using formatted WRITE statements into
C character variables. This is called standard Fortran
C internal file I/O and is exemplified in the first three
C lines of the following example. You can also catenate
C substrings of characters to construct the error message.
C Here is an example showing the use of both writing to
C an internal file and catenating character strings.
C
C CHARACTER*5 CHARN, CHARL
C WRITE (CHARN,10) N
C WRITE (CHARL,10) LDA
C 10 FORMAT(I5)
C CALL XERMSG ('SLATEC', 'MMPY', 'THE ORDER'//CHARN//
C * ' OF THE MATRIX EXCEEDS ITS ROW DIMENSION OF'//
C * CHARL, 3, 1)
C
C There are two subtleties worth mentioning. One is that
C the // for character catenation is used to construct the
C error message so that no single character constant is
C continued to the next line. This avoids confusion as to
C whether there are trailing blanks at the end of the line.
C The second is that by catenating the parts of the message
C as an actual argument rather than encoding the entire
C message into one large character variable, we avoid
C having to know how long the message will be in order to
C declare an adequate length for that large character
C variable. XERMSG calls XERPRN to print the message using
C multiple lines if necessary. If the message is very long,
C XERPRN will break it into pieces of 72 characters (as
C requested by XERMSG) for printing on multiple lines.
C Also, XERMSG asks XERPRN to prefix each line with ' * '
C so that the total line length could be 76 characters.
C Note also that XERPRN scans the error message backwards
C to ignore trailing blanks. Another feature is that
C the substring '$$' is treated as a new line sentinel
C by XERPRN. If you want to construct a multiline
C message without having to count out multiples of 72
C characters, just use '$$' as a separator. '$$'
C obviously must occur within 72 characters of the
C start of each line to have its intended effect since
C XERPRN is asked to wrap around at 72 characters in
C addition to looking for '$$'.
C
C NERR An integer value that is chosen by the library routine's
C author. It must be in the range -99 to 999 (three
C printable digits). Each distinct error should have its
C own error number. These error numbers should be described
C in the machine readable documentation for the routine.
C The error numbers need be unique only within each routine,
C so it is reasonable for each routine to start enumerating
C errors from 1 and proceeding to the next integer.
C
C LEVEL An integer value in the range 0 to 2 that indicates the
C level (severity) of the error. Their meanings are
C
C -1 A warning message. This is used if it is not clear
C that there really is an error, but the user's attention
C may be needed. An attempt is made to only print this
C message once.
C
C 0 A warning message. This is used if it is not clear
C that there really is an error, but the user's attention
C may be needed.
C
C 1 A recoverable error. This is used even if the error is
C so serious that the routine cannot return any useful
C answer. If the user has told the error package to
C return after recoverable errors, then XERMSG will
C return to the Library routine which can then return to
C the user's routine. The user may also permit the error
C package to terminate the program upon encountering a
C recoverable error.
C
C 2 A fatal error. XERMSG will not return to its caller
C after it receives a fatal error. This level should
C hardly ever be used; it is much better to allow the
C user a chance to recover. An example of one of the few
C cases in which it is permissible to declare a level 2
C error is a reverse communication Library routine that
C is likely to be called repeatedly until it integrates
C across some interval. If there is a serious error in
C the input such that another step cannot be taken and
C the Library routine is called again without the input
C error having been corrected by the caller, the Library
C routine will probably be called forever with improper
C input. In this case, it is reasonable to declare the
C error to be fatal.
C
C Each of the arguments to XERMSG is input; none will be modified by
C XERMSG. A routine may make multiple calls to XERMSG with warning
C level messages; however, after a call to XERMSG with a recoverable
C error, the routine should return to the user. Do not try to call
C XERMSG with a second recoverable error after the first recoverable
C error because the error package saves the error number. The user
C can retrieve this error number by calling another entry point in
C the error handling package and then clear the error number when
C recovering from the error. Calling XERMSG in succession causes the
C old error number to be overwritten by the latest error number.
C This is considered harmless for error numbers associated with
C warning messages but must not be done for error numbers of serious
C errors. After a call to XERMSG with a recoverable error, the user
C must be given a chance to call NUMXER or XERCLR to retrieve or
C clear the error number.
C***REFERENCES R. E. Jones and D. K. Kahaner, XERROR, the SLATEC
C Error-handling Package, SAND82-0800, Sandia
C Laboratories, 1982.
C***ROUTINES CALLED FDUMP, J4SAVE, XERCNT, XERHLT, XERPRN, XERSVE
C***REVISION HISTORY (YYMMDD)
C 880101 DATE WRITTEN
C 880621 REVISED AS DIRECTED AT SLATEC CML MEETING OF FEBRUARY 1988.
C THERE ARE TWO BASIC CHANGES.
C 1. A NEW ROUTINE, XERPRN, IS USED INSTEAD OF XERPRT TO
C PRINT MESSAGES. THIS ROUTINE WILL BREAK LONG MESSAGES
C INTO PIECES FOR PRINTING ON MULTIPLE LINES. '$$' IS
C ACCEPTED AS A NEW LINE SENTINEL. A PREFIX CAN BE
C ADDED TO EACH LINE TO BE PRINTED. XERMSG USES EITHER
C ' ***' OR ' * ' AND LONG MESSAGES ARE BROKEN EVERY
C 72 CHARACTERS (AT MOST) SO THAT THE MAXIMUM LINE
C LENGTH OUTPUT CAN NOW BE AS GREAT AS 76.
C 2. THE TEXT OF ALL MESSAGES IS NOW IN UPPER CASE SINCE THE
C FORTRAN STANDARD DOCUMENT DOES NOT ADMIT THE EXISTENCE
C OF LOWER CASE.
C 880708 REVISED AFTER THE SLATEC CML MEETING OF JUNE 29 AND 30.
C THE PRINCIPAL CHANGES ARE
C 1. CLARIFY COMMENTS IN THE PROLOGUES
C 2. RENAME XRPRNT TO XERPRN
C 3. REWORK HANDLING OF '$$' IN XERPRN TO HANDLE BLANK LINES
C SIMILAR TO THE WAY FORMAT STATEMENTS HANDLE THE /
C CHARACTER FOR NEW RECORDS.
C 890706 REVISED WITH THE HELP OF FRED FRITSCH AND REG CLEMENS TO
C CLEAN UP THE CODING.
C 890721 REVISED TO USE NEW FEATURE IN XERPRN TO COUNT CHARACTERS IN
C PREFIX.
C 891013 REVISED TO CORRECT COMMENTS.
C 891214 Prologue converted to Version 4.0 format. (WRB)
C 900510 Changed test on NERR to be -9999999 < NERR < 99999999, but
C NERR .ne. 0, and on LEVEL to be -2 < LEVEL < 3. Added
C LEVEL=-1 logic, changed calls to XERSAV to XERSVE, and
C XERCTL to XERCNT. (RWC)
C 920501 Reformatted the REFERENCES section. (WRB)
C***END PROLOGUE XERMSG