The other guaranteed way of locating bugs is to release your application into production. Out there in a hostile world, surrounded by other unruly applications and subject to the vagaries of exotic hardware devices and unusual Registry settings, it's perhaps of little surprise that the production environment can find even the most subtle of weaknesses in your program. Then there are your users, many of whom will gleefully inform you that "your program crashed" without even attempting to explain the circumstances leading up to the crash. Trying to extract the details from them is at best infuriating, at worst impossible. So we need some simple method of trapping all possible errors and logging them in such a way as to be able to reconstruct the user's problem. Here we'll examine the minimum requirements needed to trap and report errors and thus help your user retain some control over what happens to his or her data after a program crash.
The first point to note about Visual Basic 6's error handling capabilities is that they are somewhat deficient when compared with those of most compiled languages. There is no structured exception handling, and the only way to guarantee a chance of recovery from an error is to place an error trap and an error handler into every procedure. To understand why, we need to look in detail at what happens when a run-time error occurs in your program.
Your program is riding happily down the information highway, and suddenly it hits a large pothole in the shape of a run-time error. Perhaps your user forgot to put a disk into drive A, or maybe the Windows Registry became corrupted. In other words, something fairly common happened. Visual Basic 6 first checks whether you have an error trap enabled in the offending procedure. If it finds one, it will branch to the enabled error handler. If not, it will search backward through the current procedure call stack looking for the first error trap it can locate. If none are found, your program will terminate abruptly with a rude error message, which is normally the last thing you want to happen. Losing a user's data in this manner is a fairly heinous crime and is not likely to endear you to either your users or the technical support people. So at the very least you need to place an error handler in the initial procedure of your program.
Unfortunately, this solution is not very satisfactory either, for two reasons. Another programmer could come along later and modify your code, inserting his or her own local error trap somewhere lower in the call stack. This means that the run-time error could be intercepted, and your "global" error trap might never get the chance to deal with it properly. Instead, your program has to be happy with some fly-by-night error handler dealing with what could be a very serious error. The other problem is that even if, through good luck, your global error trap receives the error, Visual Basic 6 provides no mechanism for retrying or bypassing an erroneous statement in a different procedure. So if the error was something as simple as being unable to locate a floppy disk, you're going to look a little silly when your program can't recover. The only way of giving your user a chance of getting around a problem is to handle it in the same procedure in which it occurred.
There is no getting away from the fact that you need to place an error trap and an error handler in every single procedure if you want to be able to respond to and recover from errors in a sensible way. The task then is to provide a minimalist method of protecting every procedure while dealing with all errors in a centralized routine. That routine must be clever enough to discriminate between the different types of errors, log each error, interrogate the user (if necessary) about which action to take, and then return control back to the procedure where the problem occurred. The other minimum requirement is to be able to raise errors correctly to your clients when you are writing ActiveX components.
Adding the following code to every procedure in your program is a good start:
Private Function AnyFunction() As Integer
On Error GoTo LocalError
' Normal procedure code goes here.
Exit Function
LocalError:
If Fatal("Module.AnyFunction") = vbRetry Then
Resume
Else
Resume Next
End If
End Function
This code can provide your program with comprehensive error handling, as long as the Fatal function is written correctly. Fatal will receive the names of the module and procedure where the error occurred, log these and other error details to a disk log file for later analysis, and then inform the program's operator about the error and ask whether it ought to retry the statement in error, ignore it, or abort the whole program. If the user chooses to abort, the Fatal function needs to perform a general cleanup and then shutdown the program. If the user makes any other choice, the Fatal function returns control back to the procedure in error, communicating what the user has chosen. The code needed for the Fatal function can be a little tricky. You need to think about the different types of error that can occur, including those raised by ActiveX components. You also need to think about what happens if an error ever occurs within the Fatal function itself. (Again, see Chapter 1 for a more detailed analysis of this type of error handling.) Here I'll examine a couple of pitfalls that can occur when handling or raising Visual Basic 6 errors that involve the use of vbObjectError.
When creating an ActiveX component, you often need to either propagate errors specific to the component back to the client application or otherwise deal with an error that occurs within the component. One accepted method for propagating errors is to use Error.Raise. To avoid clashes with Visual Basic 6's own range of errors, add your error number to the vbObjectError constant. Don't raise any errors within the range vbObjectError through vbObjectError + 512, as Visual Basic 6 remaps some error messages between vbObjectError and vbObjectError + 512 to standard Automation run-time errors. User-defined errors should therefore always be in the range vbObjectError + 512 to vbObjectError + 65536. Note that if you're writing a component that in turn uses other components, it is best to remap any errors raised by these subcomponents to your own errors. Developers using your component will normally want to deal only with the methods, properties, and errors that you define, rather than being forced to deal with errors raised directly by subcomponents.
When using a universal error handler to deal with many different types of problems, always bear in mind that you might be receiving errors that have been raised using the constant vbObjectError. You can use the And operator (Err.Number And vbObjectError) to check this. If True is returned, you should subtract vbObjectError from the actual error number before displaying or logging the error. Because vbObjectError is mainly used internally for interclass communications, there is seldom any reason to display it in its natural state.
In any error handler that you write, make sure that the first thing it does is to save the complete error context, which is all the properties of the Err object. Otherwise it's all too easy to lose the error information. In the following example, if the Terminate event of MyObject has an On Error statement (as it must if it's to handle any error without terminating the program), the original error context will be lost and the subsequent Err.Raise statement will itself generate an "Illegal function call" error. Why? Because you're not allowed to raise error 0!
Private Sub AnySub()
On Error GoTo LocalError
' Normal code goes here
Exit Sub
LocalError:
Set MyObject = Nothing ' Invokes MyObject's Terminate event
Err.Raise Err.Number, , Err.Description
End Sub
Another point to be careful about is raising an error in a component that might become part of a Microsoft Transaction Server (MTS) package. Any error raised by an MTS object to a client that is outside MTS causes a rollback of any work done within that process. This is the so-called "failfast" policy, designed to prevent erroneous data from being committed or distributed. Instead of raising an error, you will have to return errors using the Windows API approach, in which a function returns an error code rather than raising an error.
A final warning for you: never use the Win32 API function GetLastError to determine the error behind a zero returned from a call to a Win32 API function. A call to this function isn't guaranteed to be the next statement executed. Use instead the Err.LastDLLErr property to retrieve the error details.
Staying compatible
An innocuous set of radio buttons on the Component tab of the Project Properties dialog box allows you to control possibly one of the most important aspects of any component that you write-public interfaces. The Visual Basic documentation goes into adequate, sometimes gory, detail about how to deal with public interfaces and what happens if you do it wrong, but they can be a rather confusing area and the source of many defects.
When you compile your Visual Basic 6 component, the following Globally Unique Identifiers (GUIDs) are created:
- An ID for the type library
- A CLSID (class ID) for each creatable class in the type library
- An IID (interface ID) for the default interface of each Public class in the type library, and also one for the outgoing interface (if the class raises events)
- A MID (member ID) for each property, method, and event of each class
When a developer compiles a program that uses your component, the class IDs and interface IDs of any objects the program creates are included in the executable. The program uses the class ID to request that your component create an object, and then queries the object for the interface ID. How Visual Basic generates these GUIDs depends on the setting of the aforementioned radio buttons.
The simplest setting is No Compatibility. Each time you compile the component, new class and interface IDs are generated. There is no relation between versions of the component, and programs compiled to use one version of the component cannot use later versions. This means that any time you test your component, you will need to close and reopen your test (client) program in order for it to pick up the latest GUIDs of your component. Failing to do this will result in the infamous error message "Connection to type library or object library for remote process has been lost. Press OK for dialog to remove reference."
The next setting is Project Compatibility. In Visual Basic 5, this setting kept the type library ID constant from version to version, although all the other IDs could vary randomly. This behavior has changed in Visual Basic 6, with class IDs now also constant regardless of version. This change will help significantly with your component testing, although you might still occasionally experience the error mentioned above. If you're debugging an out-of-process component, or an in-process component in a separate instance of Visual Basic, this error typically appears if the component project is still in design mode. Running the component, and then running the test program, should eliminate the problem. If you are definitely already running the component, you might have manually switched the setting from No Compatibility to Project Compatibility. This changes the component's type library ID, so you'll need to clear the missing reference to your component from the References dialog box, then open the References dialog box again and recheck your component.
It is a good idea to create a "compatibility" file as early as possible. This is done by making a compiled version of your component and pointing the Project Compatibility dialog box at this executable. Visual Basic will then use this executable file to maintain its knowledge about the component's GUIDs from version to version, thus preventing the referencing problem mentioned above.
Binary Compatibility is the setting to use if you're developing an enhanced version of an existing component. Visual Basic will then give you dire warnings if you change your interface in such a way as to make it potentially incompatible with existing clients that use your component. Ignore these warnings at your peril! You can expect memory corruptions and other wonderful creatures if you blithely carry on. Visual Basic will not normally complain if, say, you add a new method to your interface, but adding an argument to a current method will obviously invalidate any client program that expects the method to remain unchanged.