ESRI ErrorHandler Generator
This Visual Basic add-in automates the generation of error handling code. To access the add-in select the ESRI ErrorHandler Generator menu item on the Add-Ins menu in Visual Basic. There are two parts to this add-in: the generation of the error handling code, and the execution of the code when a runtime error is created.
The add-in creates the error handlers automatically; you don’t ever have to write the error handler manually (unless a specialized handler is required). It is often better to wrap particular function calls with a specialized handler, but still have the generic handler in use for the majority of the function.
The add-in can generate the error handlers in one of three ways:
- Generate an error handler for the current function.
- Generate error handlers for all the functions within the current module.
- Generate error handler for all source files within the active project.
The message box shown below asks for the method to use. This message box can be bypassed by pressing a combination of the Ctrl and Shift keys when clicking the ESRI ErrorHandler Generator menu item on the Add-Ins menu. The message box also allows the setting of four options.
Error Handler Add-in dialog box
- Update Error Handlers—Default is True. Forces the error handlers, generated by the Add-In, in the function(s) to be rewritten even if they are already there. Use this option to ensure that the error handlers match the latest version or if you make a change to the dependency requirements. This ensures the correct arguments are passed to the ErrorHandler function.
- Update Error Module—Default is True. Regenerates the ErrorHandler.bas module added to the project each time the add-in is executed. Typically this would be toggled off if you change the strings used by the various user interfaces. This should be toggled on if there is a change in the dependency requirements.
- No Dependency—Default is False. Error handler has no runtime dependency on the ErrorHandlerUI.DLL file. The error log user interface is not available, but the error is simply handled and the call stack displayed to the user in a message box.
- Parent Error Forms—Default is False. Parents the various forms, using the m_ParentHWND module variable.
In addition to the error handler it adds to the functions, the add-in, depending on the options, declares one or two variables in the module; c_ModuleFileName and m_ParentHWND. The first, a constant, holds a string identifying the filename of the module on disk. If the add-in is executed before the file is saved this string will be blank. To update the constant you can either enter the name manually, or run the add-in again—this will update the constant value. The second is a variable that can hold a window handle that will be used to parent the various user interfaces used by the runtime error handlers. By default all the error handler interfaces use the desktop as their parent window. Setting the member variable m_ParentHWND defined at the top of the module to a valid window handle will parent the error dialogs to this window. By default the member variable m_ParentHWND is not added to the module, and all interfaces use the desktop as their parent.
The error handling code makes use of the same generic error handler module that is included with the Interface implementation add-in. By default every time the Error Handler add-in executes this module is regenerated. This means that any changes made to the module will be lost. The generic error handling function HandleError takes ten arguments.
| Name | Data Type | Description |
|---|---|---|
| bTopProcedure | Boolean | States whether the error handling function was called from a top-level function or not. Public methods, events and properties and friends are all top-level functions. Private methods called from within the same module are not top-level functions |
| sProcedureName | string | Encapsulates the function and module name, and any line number information available |
| IErrNumber | long | ErrorNumber (retrieved from Err object) |
| sErrSource | string | ErrorSource (retrieved from Err object) |
| sErrDescription | string | ErrorDescription (retrieved from Err object) |
| version | long | VersionOfFunction (optional Default 1) |
| parentHWND | long | Parent hWnd for error dialogs, NULL is valid (option is NULL) |
| reserved1 | variant | Reserved |
| reserved2 | variant | Reserved |
| reserved3 | variant | Reserved |
Depending on the first parameter, the HandleError function either presents the error to the user using a variety of interfaces, or raises the error. A top-level error handler will eventually catch this raised error. In this way, the call stack can be created. For this mechanism to function correctly, all functions should implement this error handler.
The sixth parameter controls the user interface. You can choose to display either a simple Message Box, as shown in the figure below, with the error information contained within it (Version 1), or a more comprehensive error handling facility (Version 3). Version 2 is provided for backward compatibility but its use is deprecated. The message box displayed when an error is raised using Version 1 is shown in the dialog below. Notice the call stack and the original error description.
Version 1 error log
Version 4 of the Error Handler displays a message box to the user informing the user that an unexpected error has occured, along with the error log showing the error message, number and call stack. Neither of these forms are modal. The forms are implemented as singleton objects, meaning that no matter how many modules make use of the error handler, the errors will all be written to the same error log. If the Error log is already displayed the information message box is not shown. The error log is brought to the front of the display and the error appended to the text already there.
Version 4 information message box
Version 4 error log
The contents of the error log can either be saved to a text file for later viewing or printed out. Save and print options are available on the File menu.
Although the call stack information is useful the error log displays the most information when combined with Line numbers. In order to obtain line number information in the error log the source files must be annotated using the Line Number Generator add-in. If line number information is available the error log displays data similar to that shown below.
Error log with line number information