6.4. Reporting Errors

Information about errors is vital to allow you as the developer to track down the source of the error and to take steps to prevent it from happening again. The traditional method of reporting an error is to simply display a message box, but you can also create a log on the user's machine.

6.4.1. Reporting to the User

Include enough information both to inform the user that an error has occurred, and to aid the developer to get to the real root of the problem. Your error message should report:

• The name of the module

• The name of the procedure

• The error number

• The error description

• The error source

It's entirely up to you how you style your message box. Figures Figure 6.1 and Figure 6.2 illustrate two very different methods. You will probably find that nontechnical users can assimilate—and therefore both remember and recount—the information in the style of Figure 6.1 much more readily than the impersonal style of Figure 6.2.

6.4.2. Adding Help

The MsgBox function from Version 5 of Visual Basic on includes the option to display a Help button on the message box dialog, as shown in Figure 6.3. By including the vbMsgBoxHelpButton constant for the Button parameter, VB automatically displays the Help button. If your application provides context-sensitive help, you can specify the help filename and a context ID as parameters, which allows the user to navigate directly to the particular help section for the error:

MsgBox prompt:="Error Number: " & Err.Number & vbCrLf _
       & Err.Description, _
       buttons:=vbCritical + vbMsgBoxHelpButton, _
       Title:="Error!", _
       HelpFile:=Err.HelpFile, _
       context:=Err.HelpContext

One word of warning here, though. If your users are nontechnical, I would suggest that you make the display of the Help button conditional on the error number. The reason for this is that internal VB errors try to display the VB help section, which probably won't be loaded on an end user's machine. Therefore, only display the Help button for your own error codes when you have written a specific section about the error in your application's help file.

6.4.3. Silent Reporting: Logging the Error Event

Your efforts to resolve issues within an application are often frustrated by users not reporting errors. The user simply clicks past the message box reporting the error and continues. Either they forget or can't be bothered to contact the MIS department or the software developer to report the issue. There is a way you can store information about the error on the user's machine without having to go to the trouble of coding a file open/write/close routine that itself could cause a fatal error within the error handler.

The App object includes a method called LogEvent whose operation depends on the operating system being used. On NT the LogEvent method writes to the machine's event log, whereas in Windows 9x a log file is created or an existing log file appended to. Logging only takes place in compiled VB applications.

You can specify an event log file using the StartLogging method, which takes two parameters, the log filename and the log mode. (The App object's LogPath and LogMode properties, which you would expect to set before beginning logging, are read-only and can only be set by calling the StartLogging method.)

Note that the log mode constants were missing from Version 5 of VB, so you either have to enter their literal values, or you have to define your own constants.

In Windows NT, if you call the StartLogging method but don't specify a log file, or in Windows 95, if you don't call the StartLogging method at all, VB creates a file called vbevents.log, which is placed in the Windows directory. To use event logging, you don't necessarily need to use the StartLogging method.

The LogEvent method itself takes two parameters. The first is a string containing all the detail you wish to store about the error or event. The second is an EventType constant, which denotes an error, information, or a warning. In NT, this event type value displays the correct icon in the event log, whereas in Windows 95, the word "Error," "Information," or "Warning" appears at the start of the item in the event log file.

In Section 6.3, you saw how to force MsgBox prompts to be automatically written to an event log by selecting the Unattended Application option. But which event log? The MsgBox function doesn't take a parameter to specify an optional event log, so VB will write the string contained within the Prompt parameter to the default vbevents.log in Windows 9x or to the application event log in Windows NT. However, you can place a call to the app object's StartLogging method in the class's Initialize event, thereby specifying a log file for all Msgbox and LogEvent calls.

Once you have an event log for your application, you can look back through the history of the application any time you choose. If you are networked to the user's machine, you can open the user's event log from your machine and detect problems without even leaving your desk.