ErrReport DLL by Jim Pragit


Introduction:
ErrReport provides an easy way to add centralized error reporting capabilities to applications written in Visual Basic.  ErrReport has the following features:

- Thorough diagnostic information.  In addition to the usual error number and error description properties, ErrReport provides information on the user's system configuration, call stack, memory drive usage and more. 
- Screenshots.  ErrReport can take a screenshot of the entire screen at the time of the error.  This lets you know exactly what the user was doing when the error occurred.  This can help you track down bugs quickly.
- Automatic logging.  All error information is automatically logged to a text file for later retrieval.  Screenshots can also be saved to the drive of your choice.
- Print feature.  Clicking the Print button sends the error report (and screenshot) to the printer.  If you have remote users who aren't computer-savvy but can operate a fax machine, this feature comes in very handy when tracking down bugs.
- Flexibility.  Many of these features can be turned on or off, depending on your preference.  You can also add your own custom information to the error report.
- Fast.  There is absolutely no overhead when building the call stack unless an error actually occurs.  
- Ease of use.  One of the primary design goals of ErrReport was to make error handling as simple as possible.  Aside from the prerequisite 'On Error GoTo...' code, ErrReport needs only 1 line of code per procedure.


Installation:
ErrReport is an ActiveX DLL.  You will need to register it using a tool such as RegSvr32.  For example, enter this at a command prompt:

	RegSvr32 "C:\Windows\System32\ErrRpt62.dll"

Because other applications may also be using ErrReport, it is highly recommended that ErrRpt62.dll be installed in the \Windows\System32\ directory.


Upgrading:
In order to avoid any potential conflicts with previous versions, ErrReport 6.2 is compiled without binary compatability to previous versions.  This allows you to safely install multiple versions of ErrReport on the same computer.  To upgrade your application from a previous version of ErrReport, simply change your project's reference to ErrReport DLL 6.2.


Usage:
The first thing your program needs to do is initialize the ErrReport object.  My recommendation is to create a subroutine called SetupErrorHandling to do this.  At the bare minimum, it should look like this:

Private Sub SetupErrorHandling()
	Set AppObject = App
	Set ErrObject = Err  
End Sub

Most likely, you will want to enable and customize ErrReport.  A more typical SetupErrorHandling may look like this:

Private Sub SetupErrorHandling()

	On Error GoTo Err_Handler

	Set AppObject = App
	Set ErrObject = Err
	CallStack = True
	DriveInfo = True
	LogFileMenu = True
	LogSizeMax = 10000
	MemInfo = True
	OptionsMenu = True
	ScreenshotPrint = True
	ScreenshotSave = True
	SysInfo = True

	Exit Sub

Err_Handler:
	Call AddToCallStack(Me.Name, "SetupErrorHandling")
	Err.Raise Err.Number
End Sub

Then call this subroutine from Sub Main or the Form_Load event of your main form, whichever is your startup object.  This is all you need to do to setup ErrReport.

Note: ErrReport is a GlobalMultiUse class.  Explicitly specifying the object is not necessary.   However, if you prefer, the following syntax is also valid:

Private Sub SetupErrorHandling()
	Set ErrReport.AppObject = App
	Set ErrReport.ErrObject = Err  
End Sub

Once you've setup ErrReport, it is ready to go.  There are two basic error handling styles to using ErrReport.

Style 1 (No CallStack). This is the simplest use of ErrReport.  Simply call the ErrorReport method in each event procedure's error handler:

'event procedure
Private Sub Form_Load()
    On Error GoTo Err_Handler

    'do something

    Exit Sub

Err_Handler:
    Call ErrorReport
End Sub

Style 2 (CallStack).  If you wish to build a call stack, you need to call AddToCallStack in each routine's error handler.  AddToCallStack builds the call stack by appending the module name and procedure name to Err.Source:

'event procedure
Private Sub Form_Load()
	On Error GoTo Err_Handler

	Call DoSomething

	Exit Sub

Err_Handler:
	Call AddToCallStack(Me.Name, "Form_Load")
	Call ErrorReport
End Sub

'non-event procedure
Private Sub DoSomething()
	On Error GoTo Err_Handler

	'do something

	Exit Sub

Err_Handler:
	Call AddToCallStack(Me.Name, "DoSomething")
	Err.Raise Err.Number
End Sub


Properties & Methods:
AddToCallStack - This builds the call stack.  It accepts two parameters.  The first is the name of the module.  Rather than hard coding this value, use Me.Name for forms and TypeName(Me) for classes and user controls.  For standard modules, use a private module level constant (such as MODULE_NAME).  The second parameter is the name of the procedure.  Unfortunately, VB provides no elegant way to determine this.  You must hard code the procedure name in the call.  In order to get an accurate call stack, this routine must be called from the error handler in every single procedure you code.

AppObject - Gives ErrReport access to your application's App object.  This is how ErrReport knows your app's name, version number, path, etc.

CallStack - This turns on the CallStack feature, a list of all procedures that led to the error.  This is used in conjunction with the AddToCallStack method.

CustomInfo - This lets you add any additional information you want displayed/logged when calling ErrorReport.

DriveInfo - Set this to True to have ErrReport give diagnostic information on the user's drives.

EnvironmentInfo - Set this to True to have ErrReport list out all environment variables and their values.

ErrObject - Gives ErrReport access to your application's Err object.  

ErrorReport - This the 'main' method of ErrReport. It builds a formatted error message which is saved to a text file and displayed in a message dialog box.  

LineNumber - If your source code contains line numbers, this will return the line number where the error occurred.  This should work, but is *not officially supported*.

LogFileMenu - This turns on the LogFile menu which gives your users the ability to view, edit and clear the log file.

LogPath - This sets the location where the log file and screenshot are saved.

LogSizeMax - This lets you set a maximum size (in bytes) for the log file.  The filename of the log file is AppObject.EXEName & "_ErrLog.txt".  Zero means no maximum.

MemInfo - Set this to True to have ErrReport give diagnostic information on the user's memory (how much RAM they have, how much is used, etc.).

OptionsMenu - This turns on the Options menu.

ProcInfo - Set this to Ture to have ErrReport list all the programs currently running in memory with their complete pathname and version number.

ScreenshotPrint - If set to True, the screen shot will be sent to the printer when the user clicks the Print button.

ScreenshotSave - If set to True, the screen shot will be saved to the user's hard drive as a bitmap file.  Only one screenshot can be saved at a time.  The filename of the screen shot is AppObject.EXEName & "_ErrPic.bmp".

SilentMode - When True, calling the ErrorReport method will not display a dialog on screen. 

SysInfo - Set this to True to have ErrReport give diagnostic information on the user's system configuration (CPU, OS, etc.).


Resources:
Mark Hurst has written an excellent article on Visual Basic error handling.  It is both thorough and easy to understand, a rare combination.  It is highly recommended.

http://www.keysound.com/html/the_x_files.htm


Licensing Agreement:
The ErrReport DLL, demo program and documentation is provided 'as is'.  It comes with no warrantee or guarantee of any kind.  By installing or using ErrReport DLL, you indicate your agreement.


Source Code:
The source code for the ErrReport DLL is available for purchase.  For more information, contact me at emunews@msn.com.


History:

Version 6.1
  - Added LogSizeMax
  - Updated for Pentium III CPUs
  - DriveInfo will now give the complete UNC path for remote drives
  - Added LogPath
  - Added CustomInfo
  - Fixed GlobalMultiUse issue

Version 6.1.1
  - Fixed bug in LogPath
  - Fixed bug in Form_Terminate when EXE and DLL use ErrReport
  - New PrintImage routine will automatically fit screenshot to page when printing

Version 6.1.2
  - Fixed bugs in ErrObject's and AppObject's Property Get procedures.

Version 6.2
  - Added SilentMode
  - Code reorganization results in smaller memory footprint, especially for multi-project applications
  - Added DLL Error Msg
  - Added EnvironmentInfo 
  - Added ProcListInfo

Feedback:
Suggestions, bug reports, and constructive criticism are all welcomed.  Source code is sold separately.  Send e-mail to Jim Pragit at emunews@msn.com.
