Error Output and Termination for Fortran Routines
DESCRIPTION:
Any Fortran subroutine called from S-PLUS can invoke the standard SLATEC xerror package routines XERROR or XERRWV which will cause S-PLUS to ouput a Fortran character string (message) and, in the case of XERRWV, up to two optional integers and/or two optional real numbers to its standard error or standard output files. In addition, a severity level and error number assigned to the message can be used to delay or suppress output, control error driven termination of the subroutine and summarize all errors encountered.
USAGE: 
XERROR(MESSAGE, LENMESS, NERROR, LEVEL)
XERRWV(MESSAGE, LENMESS, NERROR, LEVEL, NI, I1, I2, NR, R1, R2)
REQUIRED ARGUMENTS:
MESSAGE:
a Fortran character string containing the desired error message.
LENMESS:
integer giving the actual number of characters in MESSAGE. If MESSAGE is a quoted string, then LENMESS can be given as len(MESSAGE); e.g. XERRWV('Tolerance EPS (R1) can not be obtained', len('Tolerance EPS (R1) can not be obtained'),1,0,0,0,0,1,2e-16,0.0)
NERROR:
a positive error number to be (uniquely) associated with this MESSAGE; NERROR must not be zero.
LEVEL:
integer severity level: = 2 -- a fatal error = 1 -- a recoverable error = 0 -- a warning message =-1 -- a single warning which will be output at most once.
NI:
the number of integers to be output (0 to 2) along with MESSAGE.
I1,I2:
the first and second integer values to be output.
NR:
the number of reals to be output (0 to 2) along with MESSAGE.
R1,R2:
the first and second real values to be output; these must be single precision and can be in the form SNGL(...) to assure proper precision.
SIDE EFFECTS:
These subroutines are always called for their side effects: output of error messages to the currently active xerror files, accumulation of error number occurance data and abnormal termination of the S-PLUS function calling the Fortran routine which has invoked XERROR or XERRWV. Details of these are given below and in the description of the xerror related routines.
DETAILS:
The standard xerror package, available through Netlib, and documented in reference 1 below, provides standardized diagnostic message output and termination control for Fortran routines. As adapted to work with S-PLUS, any Fortran subroutine called by an S-PLUS function may invoke one of the two Fortran subroutines XERROR and XERRWV to produce error output, control its abnormal termination, and update a table of errors encountered. Each time one of these is invoked, the error number is noted and the occurance count for that message is incremented in an internal table. On the first occurance of an error number, the error number and an initial segment (first 40 characters) of the message is recorded in the table. (The table is limited to tracking 10 different error numbers.) In addition, the full message may be output immediately or passed to the S-PLUS warning message queue, and the current S-PLUS function call may be stopped, depending on the settings of options()$warn and the severity LEVEL of the message. The interaction of warn and LEVEL are shown in the following table: warn type LEVEL 0 1 2 value fatal 2 stop stop stop recover 1 not printed* printed stop warning 0 not printed* printed printed single -1 not printed** printed printed warning only once only once

* - passed to S-PLUS warning queue **- passed once to S-PLUS warning queue Note that recover level messages are promoted to fatal when warn is 2 or -2. Also all output is supressed if warn is negative.

REFERENCES:
Jones R. E., Kahaner D. K., Xerror, the Slatec Error-handling Package, sand82-0800, Sandia Laboratories, 1982.

Netlib reference.

SEE ALSO:
DBLEPR , INTPR , REALPR , xerror , xerror.clear , xerror.maxpr , xerror.setfile , xerror.summary .
EXAMPLES: 
C examples from the XERROR prolog - offered as Fortran comments
c        call xerror('smooth -- num was zero.',23,1,2)
c        call xerror('integ  -- less than full accuracy achieved.',
c    1                43,2,1)
c        call xerror('rooter -- actual zero of f found before interval f
c    1ully collapsed.',65,3,0)
c        call xerror('exp    -- underflows being set to zero.',39,1,-1)
C examples for  XERRWV
c        call xerrwv('smooth -- num (=i1) was zero.',29,1,2,
c    1   1,num,0,0,0.,0.)
c        call xerrwv('dodesl -- By T (r1) mxit (i1) steps taken without
c    1reaching tfinal (r2)',70,3,1,mxit,0,2,sngl(t),sngl(tfinal))
c        call xerrwv('quadxy -- requested error (r1) less than minimum (
c    1r2).',54,77,1,0,0,0,2,errreq,errmin)


From the ddriv2 code from Netlib:
      CHARACTER*100 MSG
      ....
C Fatal error if method flag, MINT, out of range
      IF (MINT .LT. 1 .OR. MINT .GT. 3) THEN
        MSG = 'DDRIV21FE Illegal input.  Improper value for'//
     1' the integration method flag, MINT (I1)'
        LMSG = len(
     1'DDRIV21FE Illegal input.  Improper value for'//
     1' the integration method flag, MINT (I1)')
        CALL XERRWV(MSG,LMSG,21,2,1,MINT,0,0,0.0,0.0)
        RETURN
      END IF
      ....
C Warn if more than maximum number of steps taken
        IF ((IWORK(INSTEP)-NSTEPL) .GT. MXSTEP) THEN
          MSG ='DDRIV33WRN At T (R1), MXSTEP (I1) steps have been taken'
     1//' without reaching TOUT (R2).'
          LMSG = len(
     1'DDRIV33WRN At T (R1), MXSTEP (I1) steps have been taken'
     1//' without reaching TOUT (R2).')
          CALL XERRWV(MSG, LMSG, 3, 0, 1, MXSTEP, 0, 2, SNGL(T),
     1         SNGL(TOUT))
          NSTATE = 3
          GO TO 560
        END IF