Define_Error_Handler

Functions

void Define_Error_Handler (void(HC_CDECL *)(HC_ANY_ARGS) handler)
 Creates a legal name for an error handler that captures HOOPS error reports. More...
 
void UnDefine_Error_Handler (void(HC_CDECL *)(HC_ANY_ARGS) handler)
 Removes all settings established by a previous call to Define_Error_Handler(). More...
 

Detailed Description

Function Documentation

◆ Define_Error_Handler()

void Define_Error_Handler ( void(HC_CDECL *)(HC_ANY_ARGS)  handler)

Creates a legal name for an error handler that captures HOOPS error reports.

Parameters
handler- Address of a new error-handling routine, a routine returning nothing

DETAILS

There are many programming mistakes that HOOPS might trip over. Define_Error_Handler() allows the program to look at the error messages going by, and perhaps to do something about them.

You can define as many error handlers as you please. Each error handler is called for each message, from newest handler to oldest handler. When HOOPS is started up, the Report_Error() routine is defined for you as a default handler. Messages won't just fall on the floor without being seen. It prints out the message in a system-dependent way in a place the user can (hopefully) see it. If your own routine does the same job better, feel free to UnDefine the default handler.

When a fatal error happens (see below for details), HOOPS first calls all the declared error handlers, then exits to the operating system. To avoid this program exit your handler must do something drastic, such as calling Reset_System() and then the C routine "longjmp".

The parameters passed to the handler routine follow (in order):

---------------------------------------------------------------------------------------
category    An integer. Identifies the general category the error belongs to, out of      
            those defined in the hpserror.h include file. For example, memory errors      
            fall in the HEC_MEMORY error category.                                        
specific    An integer. Identifies the specific error out of those defined in the hps     
            error.h include file. For example, running out of memory.                     
            HES_OUT_OF_MEMORY, is a specific memory error in the                          
            HEC_MEMORY category.                                                          
severity    An integer. Indicates the seriousness of the offense. In particular, a "0"    
            means the message is just informational, a "1" means the message is a         
            warning (but the system is going to go ahead with the operation), a "2"       
            is a generic "error", and a "3" is a fatal error (indicating that something   
            is drastically amiss, and there's no reasonable way to continue.)             
msgc        An integer. Indicates how long msgv is.                                       
msgv        An array of pointers to character strings, with one string for each line of   
            the message.                                                                  
stackc      An integer. Indicates how long stackv is.                                     
stackv      An array of pointers to character strings, where each string is the name      
            of a currently active HOOPS routine. The originally called routine            
            would be the first one in the list.                                           
---------------------------------------------------------------------------------------

NOTES

If you want to capture some errors, but let Report_Error() take care of the rest, you might try removing Report_Error() as a handler, and then calling it manually from your own service routine as needed.

On some operating systems the handler routine may have to be written in C, no matter what the calling program is written in.

A warning is given for redefining an already existing handler.

RESTRICTIONS

See also
Report_Error, Define_System_Options.

◆ UnDefine_Error_Handler()

void UnDefine_Error_Handler ( void(HC_CDECL *)(HC_ANY_ARGS)  handler)

Removes all settings established by a previous call to Define_Error_Handler().

Parameters
handler- Address of a new error-handling routine, a routine returning nothing

DETAILS

No additional details. See Define_Error_Handler()