QuickStart: Getting Started (VBA)

To add vbWatchdog to your project, you need to add the vbWatchdog class modules into your application.   You do this by using the vbWatchdog developer Addin that is provided.  If you haven't yet installed the vbWatchdog developer AddIn, then you can get it in the Downloads section.  Registered users: use the download link in your receipt e-mail!

To use the addin, simply locate the "Add-Ins" menu in the Visual Basic editor, choose "vbWatchdog", and then select "Add vbWatchdog to this project".  Now you should find that you've got five ErrEx class modules added to your project.

PLEASE NOTE: vbWatchdog is a VBA addin, and as such you won't find it listed in the Access/Excel (or any other) Addins menu or ribbon! You will find it only listed in the VBA window, Add-Ins menu.

vbWatchdog now needs to be enabled before you can use any of its features.  We create a simple routine that enables vbWatchdog:

Note: any code listed on this page should be added to a standard code module (either an existing module, or a new one).

Public Function EnableWatchdog()
    
    ErrEx.Enable "GlobalErrorTrap"
     
End Function

ErrEx is a global class object and as such needs no specific class instantiation with the New operator.  The "GlobalErrorTrap" parameter tells vbWatchdog to call the subroutine named GlobalErrorTrap whenever an exception is detected in your VB code.  If you don't want to use a global error trap, then you can leave that string blank.

TIP: Don't try to enable vbWatchdog just yet!  You need to also add the GlobalErrorTrap procedure code, which we will come to shortly...

ErrEx.Enable() actually performs a self-test on itself to ensure that the activation was successful.  In the unlikely event that the activation of vbWatchdog fails, then an exception will be raised here (which can be caught with local error handling).

Tip: You will note that we have declared the routine as a Function rather than a Sub.  That is purely so that we can call the code directly from an Access Macro for convenience.

There is no specific need to disable vbWatchdog explicitly, but if you want to do so, then just call:

Public Function DisableWatchdog()

    ErrEx.Disable 

End Function

This completely de-activates the watchdog and all of it's features.

In order for vbWatchdog to be initialized when your application is loaded, you should create a new Access macro named AutoExec.  You should then add the macro line RunCode EnableWatchdog(), like this:

Tip: If you already have an AutoExec routine, just add the EnableWatchdog() call to it, or find an alternative way to ensure it has been activated (such as using VBA code behind a switchboard form).

To test if you've installed vbWatchdog correctly, let's try it out.  Add a simple global error trap routine:

Public Sub GlobalErrorTrap()

    LogErrorToFile

End Sub

Public Sub LogErrorToFile()
    
    Dim FilePath As String
    Dim FileNum As Long
    Dim LogLine As String
    
    On Error Resume Next ' If this procedure fails, something fairly major has gone wrong.
    
    ' We will write to a simple text file called SampleErrorLog in our MyDocuments folder
    FilePath = CreateObject("WScript.Shell").SpecialFolders("MYDOCUMENTS") & "\SampleErrorLog.txt"

    ' If you're new to vbWatchdog, don't worry about what follows just yet.
    ' It is basically iterating through the call stack to get more details about the error.

    FileNum = FreeFile
    Open FilePath For Append Access Write Lock Write As FileNum

        Print #FileNum, Now() & " - " & CStr(ErrEx.Number) & " - " & CStr(ErrEx.Description)
            
        'We will separate the call stack onto separate lines in the log
	With ErrEx.CallStack
            Do
                Print #FileNum, "       --> " & .ProjectName & "." & _
                                .ModuleName & "." & _
                                .ProcedureName & ", " & _
                                "#" & .LineNumber & ", " & _
                                .LineCode & vbCrLf
            Loop While .NextLevel
	End With

    Close FileNum

End Sub

Public Sub SimulateAnError()

    Debug.Print 1 / 0    ' This will cause a division by zero error

End Sub

The GlobalErrorTrap routine calls the LogErrorToFile routine which simply creates a sample error log file in your My Documents folder.

Now, make sure that vbWatchdog has been enabled (by calling EnableWatchdog from earlier in the immediate window).  Once enabled, force an exception by typing "SimulateAnError" {ENTER} into the VBE immediate window

Now, you should see the vbWatchdog Error Dialog in all of it's glory:

Also, check out the error log file in your My Documents folder:

Cool, eh? It is interesting to note that all the features used by the error dialog as shown here are available programmatically as well - so for example, you can also log the values of all variables used in the procedures that led up to exception as well.  We won't go over that just now as it's quite complex -- see the various parts of the manual relating to those specific features if you want to investigate further.

NEXT:   QuickStart: The Global Error Trap