Error Message Handling and Control for Fortran Routines
DESCRIPTION:
Error summaries, printing limits and output files for Fortran subroutines called from S-PLUS which invoke the standard SLATEC xerror package routines XERROR or XERRWV can be obtained or manipulated by these S-PLUS functions. xerror.summary outputs the internal table of error messages encountered, together with their error number, severity level and occurance counts. xerror.clear will clear, and optionally output the internal table. xerror.maxpr limits the number of times any single error message will be output. xerror.setfile establishes one or more of stderr and stdout to receive xerror generated output.
USAGE: 
xerror.summary()
xerror.clear(doprint=F)
xerror.maxpr(times=10)
xerror.setfile(files="stderr")
OPTIONAL ARGUMENTS:
doprint:
Logical value controlling the output of the current contents of the internal xerror table of accumulated errors before clearing the table. In the default case the table is cleared but no output is generated.
times:
Integer value which limits the number of times any one error message will be output. If the internal table records more than times previous occurances of a message, no output is generated.
files:
A character vector with entries stderr or stdout, specifying the files to which xerror generated output will be sent. If stdout appears in the vector, then any use of sink(filename) will cause xerror messages destined for stdout to appear in filename.
VALUE:
Only xerror.setfiles returns any value: a vector of integers designating the currently open xerror output files: 0 -- stderr, 1 -- stdout.
SIDE EFFECTS:
All of these functions are primarily invoked for their output effects and their modification of various internal
DETAILS:
From within S-PLUS the actions and tables of the adapted xerror package can be controlled and accessed by the functions listed above under xerror.

xerror.summary: prints out the current state of the internal error message summary table, listing the initia segment of the message, the error number, the severity level and the repetition count for each message processed.

xerror.clear: clears the internal error message table. If doprint is T the table is printed before it is cleared.

xerror.maxpr: limits to times the number of times any specific message will be queued or printed. The initial (default) value for times is 10. The internal table is still updated after times occurances of a message, but no ouput is generated.

xerror.setfile: sets the (list of) files to which the xerror messages will be sent.

Output of any specific error message is controlled by the interaction options()$warn and the severity level of the particular message, as 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 warn only once only once

* -- message passed to S-PLUS warning queue ** -- message passed once to S-PLUS warning queue When messages are passed to the S-PLUS warning queue, they may be printed at the termination of the outer-most S-PLUS function. Note that recover level messages are promoted to fatal when warn is 2 or -2. Also all output is supressed if warn is negative. In addition, no single message will be printed (or passed to the warning queue) more than maxpr times.

Refer to the documentation for XERROR, XERRWV and the SLATEC xerror package for further details.

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

Netlib reference.

SEE ALSO:
XERROR , XERRWV .
EXAMPLES: 
        #normal use of xerror.clear and xerror.summary to
        #control a subroutine package that uses xerror control
          function(arg1,.....) {
                #process args
                ...
                xerror.clear() #initialize the error tables
                #invoke the routines using xerror or xerrwv
                .Fortran("routinename",...)
                ...
                #if errors have been hidden, print summary
                if(options()$warn==0) xerror.summary()
                ...
        }