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:

C++

    HC_Define_System_Options("errors=off, warnings=off");

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.

C++

    HC_Define_System_Options("errors=(off, enable=1/3, once = 21/9");

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();