===================
Warnings and errors
===================

In any application, error situations will inevitably arise. When an error occurs, HOOPS Visualize uses the ``Report_Error`` function to report warning, error, and informational messages back to the application.


Error reporting
===============

The ``Report_Error`` function attempts to display errors, warnings, and other information messages to the user.  Although ``Report_Error`` is normally called by the system, you can determine what types of message you would like to receive via ``Define_System_Options``.  The system options has settings for fatal errors, errors, warnings, and informational messages. You can enable or disable each category as a whole. In the following code snippet, we disable all warnings and errors:

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../../hoops_3df/demo/common/sanity/0700_docs_0006.cpp
		   :start-after: //! [error_reporting1]
		   :end-before: //! [error_reporting1]
		   
You can also specifically allow some messages as well as have other messages reported only once.  To enable/disable a particular message, please indicate its category and specific number when calling ``Define_System_Options``.  A list of error codes can be found in hpserror.h.  In the code sample below, we disable all errors except the error 1/3, which indicates the error with category 1 and specific number three. The error 21/9 will only be reported once.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../../hoops_3df/demo/common/sanity/0700_docs_0006.cpp
		   :start-after: //! [error_reporting2]
		   :end-before: //! [error_reporting2]
		   
Note that the basic on/off setting overrides all previous settings.  In the above case, if the off setting were placed at the end, all errors would be turned off.

Once an error is reported and displayed, HOOPS usually returns control back to the application.  However, when some errors arises, they tend to lead to a cascade of errors.  Thus, it might be sometime before your application can retain control again.  To mitigate an error cascade, you can set a message limit via ``Define_System_Options``.  This message limit is monitored in ``Report_Error``. When the limit is met, HOOPS will return control to the application. The message counter in ``Report_Error`` is reset whenever ``Define_System_Options`` is called again with another message limit setting.


Error handlers
==============

When HOOPS starts up, ``Report_Error`` is defined as the default error handler.  ``Report_Error`` displays error and warnings.  You can, however, define your own error handlers to process and respond to errors, warnings and information coming from HOOPS.  To do this simply, create a function which takes the same parameters as defined in ``Report_Error``.  This includes the category, specific number, severity, message and call stack.  Then register your handler with HOOPS using the ``Define_Error_Handler`` function as shown in the code sample below::

	extern "C" {
	typedef void (*him_function)(HC_ANY_ARGS);
	}
	#define HIM_FUNCTION(function) (him_function)(function)

	void error_monitor (int category,int specific,int severity,int msgc,char **msgv,int stackc,char **stackv); 

	HC_Define_Error_Handler (HIM_FUNCTION(error_monitor));

If you want to let ``Report_Error`` handle most errors while your error handler responds to some key errors, you can unregister ``Report_Error`` via ``UnDefine_Error_Handler``.  Then, call ``Report_Error`` directly in your function.  The following code sample shows how to perform a search for a specific registered error handler and then unregister it::

	HC_Begin_Error_Handler_Search();
		{
			int count = 0;
			HC_Show_Error_Handler_Count(&count);
			void (*func)(HC_ANY_ARGS);
			while(HC_Find_Error_Handler(&func)){
				if(HIM_FUNCTION(func) == HIM_FUNCTION(HC_ReportError)){
					HC_UnDefine_Error_Handler (HIM_FUNCTION(func));
				}
			}
		}
	HC_End_Error_Handler_Search();
