------------------------------------------------------------
lines 9-119 of file: include/cppad/utility/error_handler.hpp
------------------------------------------------------------

{xrst_begin ErrorHandler}
{xrst_spell
   msg
   test test
}

Replacing the CppAD Error Handler
#################################

Syntax
******
| # ``include <cppad/utility/error_handler.hpp>``
| ``ErrorHandler`` *info* ( *handler* )
| ``ErrorHandler::Call`` ( *known* , *line* , *file* , *exp* , *msg* )

Constructor
***********
When you construct a ``ErrorHandler`` object,
the current CppAD error handler is replaced by *handler* .
When the object is destructed, the previous CppAD error handler is restored.

Parallel Mode
=============
The ``ErrorHandler`` constructor and destructor cannot be called in
:ref:`parallel<ta_in_parallel-name>` execution mode.
If this rule is not abided by, a raw C++ ``assert`` ,
instead of one that uses this error handler, will be generated.

Call
****
When ``ErrorHandler::Call`` is called,
the current CppAD error handler is used to report an error.
This starts out as a default error handler and can be replaced
using the ``ErrorHandler`` constructor.

info
****
The object *info* is used to store information
that is necessary to restore the previous CppAD error handler.
This restoration is done when the destructor for *info* is called.

handler
*******
The argument *handler* has prototype

| |tab| ``void`` (* *handler* )
| |tab| |tab| ( ``bool`` , ``int`` , ``const char`` * , ``const char`` * , ``const char`` * );

When an error is detected,
it is called with the syntax

   *handler* ( *known* , *line* , *file* , *exp* , *msg* )

This routine should not return; i.e., upon detection of the error,
the routine calling *handler* does not know how to proceed.

known
*****
The *handler* argument *known* has prototype

   ``bool`` *known*

If it is true, the error being reported is from a know problem.

line
****
The *handler* argument *line* has prototype

   ``int`` *line*

It reports the source code line number where the error is detected.

file
****
The *handler* argument *file* has prototype

   ``const char`` * *file*

and is a ``'\0'`` terminated character vector.
It reports the source code file where the error is detected.

exp
***
The *handler* argument *exp* has prototype

   ``const char`` * *exp*

and is a ``'\0'`` terminated character vector.
It is a source code boolean expression that should have been true,
but is false,
and thereby causes this call to *handler* .

msg
***
The *handler* argument *msg* has prototype

   ``const char`` * *msg*

and is a ``'\0'`` terminated character vector.
It reports the meaning of the error from the C++ programmers point of view.
{xrst_toc_hidden
   example/utility/error_handler.cpp
   include/cppad/core/cppad_assert.hpp
}
Example
*******
The file
:ref:`error_handler.cpp-name`
contains an example and test a test of using this routine.

{xrst_end ErrorHandler}