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