Index

NAME

bterrors.h - definition of error and warning message functions

INCLUDE

include "bterrors.h"

KEYWORDS

errors, error messages, warning messages

DESCRIPTION

Error and warning messages in a program should be reported at the
places where they occur. This is performed by calling an error or
warning  message  function  through a function pointer. There are
three such pointers: 1) errorFP, reporting an error, 2)  fataler­
rorFP,  reporting  a  fatal  error  and 3) warningFP, reporting a
warning.  A warning reports an undesired situation,  but  further
execution is anticipated to be harmless. An error reports a fail­
ure, but further execution might be possible.  Finally,  a  fatal
error  reports  a  state  where further execution is meaningless,
which then forces an abort.

The error functions throw C++ execptions (of type DpException  or
its   subclasses).  If  the  command-line  argument  --exceptions
LIBRARY (default) is given, the error functions  also  catch  the
exceptions  and  writes  the  error  message  on  the  screen. If
--exceptions USER is given as command-line options  to  the  pro­
gram, the error functions just throw an exception and it is up to
the application programmer to catch it properly. If the exception
is  not  caught,  the  btquit() routine is called and the program
aborts.

The error/warning message functions take a  char*  as  the  first
argument.  This is the name of the function in which the error or
warning has occured. If the function is a member  function  of  a
class, the complete name should be given (see the example below).
The next arguments follow the same syntax as the arguments to the
standard  printf  C function.  That is, a string, with formatting
indications, and possibly  some  variables  can  be  given.  This
allows  the programmer to report the contents of variables. Exam­
ples are given below.  In parameterized classes it may be  conve­
nient  to use an oform type of function to format the name of the
function where the error was found.  However, the error functions
also  use oform so care must be taken.  The programmer should use
the eform function, which is equivalent to oform except that  the
resulting  formatted  string is allocated separately and not as a
part  of  the  oform  buffer.  In  other   words,   a   grep   on
errorFP(oform)  should  not result in any output! The aform func­
tion  could  be  used,  but  then  a  cast  and  a  call  to  the
String::chars()  function  are  required  -  it is simpler to use
eform (actually, the e stands for error and indicates  that  this
is  the  version  of  oform that is suited for use in conjunction
with the error functions).

The function pointers errorFP, fatalerrorFP and warningFP are set
at  compile  time to default values which correspond to functions
that write the messages to standard  output.  Other  choices  are
possible,  for example, the pointers can be set to functions that
report the messages in windows. The functions  setErrorMessageIn­
Windows() and setErrorMessageOnStdout() set the function pointers
to the two possible choices: window messages or messages on stan­
dard  output. In addition, the function setMaxWarnings is used to
force program exit after a given  number  of  warnings  has  been
issued.

After  1000 warnings the program is automatically terminated. The
programmer can change the number of allowed warnings  by  calling
the  setMaxWarnings  function  or  using  the command-line option
--nowarnings.

EXAMPLES

Suppose that i is an index in an array. If i is less  than  zero,
it  is out of bounds and a fatal error message with program abor­
tion should be issued. On the other hand, other programmers would
perhaps  consider  an index out of bounds to be an error, further
execution is allowed if the user wants.  If  i  is  greater  than
1000  one  expects  that  something may be wrong and a warning is
issued.

  if (i < 0)
    fatalerrorFP("myfunction","i is negative (i=%d)",i);

  void MyClass:: test ()
    {
      real r; int s;
      // some code ....
      if (i)
        errorFP("MyClass::test","wrong      status,      r=%5.2f,
s=%d",r,s);
    }