The latest version of this document and full HuntERR download package is located here.
Your feedback is welcome: feedback@urfinjus.net


HuntERR

Error-Handling Solution For Visual Basic

Version 3.12

Library Reference


  Copyright URFIN JUS (www.urfinjus.net), 2001-2003. All rights reserved.

 

Contents

Library Files

Conditional Compilation Constants

Module HuntERR31.Bas
     Enum ENUM_ERRMAP
     Enum ENUM_ERROR_ACTION

     ErrorIn Function
     Check Sub

     ErrPreserve Sub
     ErrRestore Sub
     ErrContinue Sub
     ErrGetFromServer Sub
     IsException Function
     InException Function
     InPropagation Function

     ErrReport Property
     ErrReportHTML Property
     ErrNumber Property
     ErrSource Property
     ErrDescription Property
     ErrOrigSource Property
     ErrOrigDescription Property
     ErrAccumBuffer Property
     ErrExtractFromReport Function

     ErrMessageSource Property
     ErrRlsObjs Sub
     ErrCloseFiles Sub

     ErrMustStop Function
     ErrStopFlag Property

     ErrSaveToEventLog Function
     ErrSaveToFile Function
     ErrSaveToDB Function

     ErrInIDE Function

Module HuntERR31SysH.Bas
     ErrSysHandlerWasSet Property
     ErrSysHandlerSet Sub
     ErrSysHandlerRelease Sub

ujTransaction.Cls Class
     CreateInstance Function
     SetComplete Sub
     SetAbort Sub

ujEEDomDoc.Cls Class
     Extract Function

frmShowError.frm Form
     ErrorReport Property


Library Files

Source File Description
 HuntERR31.Bas

Main HuntERR library file. Include it into all projects where you are going to use HuntERR for error handling.

 HuntERR31SysH.Bas

System exceptions handling methods. Include it if you are going to use this functionality. Define H_SYSH=1 conditional compilation constant if you include this file.

 ujTransaction.Cls

Transaction control class. Include this file into COM DLL project if you are going to control COM+ transactions using special class in the way described in COM+ Transactions section of HuntERR Guide. Make sure its MTSTransactionMode property in VB and Transactional property in COM+ is set to Requires (New) Transaction

 ujEEDomDoc.Cls

Error extractor for MSXML DOMDocument COM Class. Include it if you are going to use MSXML libray. For specific COM servers that your application uses you'll have to create your own custom extractor classes.

 frmShowError.frm

A simple form to show error report to developer. Include it during development into your EXE project or EXE application that you use to test your COM Server. Assign frmShowError.ErrorReport = Err.Description in your error resolution method.

Contents




Conditional Compilation Constants

To set conditional compilation arguments used by HuntERR right-click on your project in Project Explorer in VB, and select Properties from popup menu. Switch to Make tab. Enter argument assigment in the box Conditional Compilation Arguments .

Argument Definition Description
 H_NOCOMPLUS=1

Identifies that project doesn't use COM+ services, so source lines in HuntERR that use these services will be excluded.

 H_NOENUMS=1

Identifies that you have Enum ENUM_ERROR_MAP declared in some public class, so it should be excluded from HuntERRxx.Bas during compilation.

 H_EXTBASE=1

Identifies that ERRMAP_BASE constant (base number for error ranges) is defined in some BAS module by application. You have to redefine ERRMAP_BASE if you use some third-party components that use error numbers in range that may interfere with ranges used by HuntERR. For example, you have to do it if you use OracleObjects.

 H_NOSTOP=1

Disables Stop-On-Error-In-IDE operators.

Use colon (:) to separate definitions if you have more than one:

    H_NOCOMPLUS=1 : H_NOENUMS=1 : H_NOSTOP=1
Contents




Module HuntERR31.Bas

Main library module. Provides most of library's functionality.

ENUM_ERRMAP Enum

Description

Enumeration defining ranges of error numbers.

Declaration

Public Enum ENUM_ERRMAP
        ERR_ACCUMULATE = 0                          'Check Sub accumulates messages
    ERRMAP_FIRST = ERRMAP_BASE
    ERRMAP_RESERVED_FIRST = ERRMAP_FIRST            'Errors reserved for HuntERR and UJ apps.
       ERR_SYSEXCEPTION                             'System exception
    ERRMAP_RESERVED_LAST = ERRMAP_RESERVED_FIRST + 100
    ERRMAP_EXC_FIRST = ERRMAP_RESERVED_LAST + 1     'Exceptions - reraised by ErrorIn
        EXC_GENERAL = ERRMAP_EXC_FIRST              'Use it if you don't need specific number
        EXC_VALIDATION                              'User input validation exception
        EXC_MULTIPLE                                'Multiple messages in error description
        EXC_CANCELLED                               'Cancelled operation, silent exception
    ERRMAP_EXC_LAST = ERRMAP_EXC_FIRST + 1000
    ERRMAP_APP_FIRST
        ERR_GENERAL = ERRMAP_APP_FIRST              'Use it if you don't need specific number
        'Application errors here
End Enum

Comments

The first range [ERRMAP_RESERVED_FIRST .. ERRMAP_RESERVED_LAST] is reserved by URFIN JUS and HuntERR. ERR_SYSEXCEPTION is used for System Exception error.

The second range [ERRMAP_EXC_FIRST .. ERRMAP_EXC_LAST] is for exceptions. You can define custom exceptions for your application in this range. Exceptions are re-raised by ErrorIn "as is" (additionally current transaction may be aborted if necessary). Application may use EXC_GENERAL if specific number is not needed.

Error numbers above ERRMAP_APP_FIRST are for custom application errors. Application can use ERR_GENERAL when unique error number is not needed

Contents



ENUM_ERROR_ACTION Enum

Description

Enumeration defining flags specifying actions performed by ErrorIn function.

Declaration

Public Enum ENUM_ERROR_ACTION
    EA_RERAISE = 1         'Reraise error
    EA_ADVANCED = 2        'Build Error report
    EA_SET_ABORT = 4       'Call SetAbort on current object's context.
    EA_DISABLE_COMMIT = 8  'Call DisableCommit on current objects' context. Recommended.
    EA_ROLLBACK = &H10     'Call Connection.Rollback
    EA_WEBINFO = &H20      'Add web request information
    EA_CONN_CLOSE = &H40   'Close connection
    EA_DEFAULT = EA_ADVANCED + EA_RERAISE + EA_WEBINFO + EA_DISABLE_COMMIT 'Default
    'The following constants are defined for convenience
    EA_NORERAISE = EA_ADVANCED + EA_WEBINFO + EA_DISABLE_COMMIT
    EA_DFTRBK = EA_ADVANCED + EA_RERAISE + EA_WEBINFO + EA_ROLLBACK
    EA_DFTRBKCLS = EA_ADVANCED + EA_RERAISE + EA_WEBINFO + EA_ROLLBACK + EA_CONN_CLOSE
End Enum

Comments

ErrorAction parameter of ErrorIn function expects set of flags specifying actions that it should perform. This enumeration defines these flags.

Contents



HuntERR31.ErrorIn Function

Description

Processes the error/exception in error handler.

Declaration

Public Function ErrorIn(ByVal MethodHeader As String, _
                        Optional ByVal arrArgs, _
                        Optional ByVal ErrorAction As Long = EA_DEFAULT, _
                        Optional ByVal DBObject As Object, _
                        Optional ByVal EnvVarNames As String, _
                        Optional ByVal arrEnvVars, _
                        Optional ByVal TransControlObject As Object) As String

Parameters

MethodHeader Required. ErrorIn expects here the name of procedure from which ErrorIn is called followed by optional list of parameter names in parenthesis. Procedure name may be in qualified form: ModuleName.ProcName
arrArgs

Optional. Variant array of values of method parameters

ErrorAction

Optional. ErrorAction is a set of flags that specify what ErrorIn should do. ENUM_ERROR_ACTION public enumeration defines available flag values

DbObject

Optional. ADO object that was used to execute database operation, if procedure executes one. It can be either Connection, Command, or Recordset object, whatever is used by application to perform database operation. Or it can be any custom object with Connection property that returns ADODB.Connection object. What ErrorIn actually uses is ADODB.Connection object, and it knows how to get it if application provides Command or Recordset instances. Connection is used by ErrorIn for two purposes: first, to retrieve ADO errors (if there are any) from Connection.Errors collection and to add them to error report; second, to abort the transaction by calling Connection.RollbackTrans (if instructed to do so with flag EA_ROLLBACK).

EnvVarNames

Optional. Specifies comma-delimited list of global or module-level variable names

arrEnvVars

Optional. Variant array of values of variables whose names are specified by EnvVarNames

TransControlObject

Optional. Provides a way to abort current transaction when application uses separate object to control COM+ transactions. If this parameter is provided, ErrorIn attempts to call its SetAbort method.

Comments

Main super-function of HuntERR library. Should be called in error handlers to process errors. Read HuntERR Guide for more information.

Contents



HuntERR31.Check Sub

Description

Checks if logical condition is true, and if not raises exception with specified number and description.

Declaration

Public Sub Check(ByVal Cond As Boolean, _
                 ByVal AnErrNumber As Long, _
                 ByVal AnErrDescr As String, _
                 Optional ByVal Values, _
                 Optional ByVal AHelpFile, _
                 Optional ByVal AHelpContext)

Parameters

Cond

Logical condition to be tested

ErrNumber

Error Number to raise if Cond is False. If this parameter is ERR_ACCUMULATE then error is not raised if Cond is false; error description is appended to ErrAccumBuffer internal buffer.

ErrDescr

Description of error to raise if Cond is False. May include placeholders referring to Values array (%1, %2, etc.)

Values

Array of values or single value to be inserted into error description. Application can use Array VB function to create array on-the-fly.

AHelpFile

String. Value to be put in Err.HelpFile property when raising error.

AHelpContext

Variant. Value to be put into Err.HelpContext property when raising error.

Comments

Check provides a convenient way to implement a checkpoint in application code. You can raise errors or exceptions using Check.

Contents



HuntERR31.ErrPreserve Sub

Description

Preserves Number, Source and Description properties of Err object in internal variables.

Declaration

Public Sub ErrPreserve()

Parameters

None.

Comments

Application can call this Sub to preserve Err object properties if it needs to execute some extra actions in error handler before calling ErrorIn. Err properties may be cleared as side effect of these actions. ErrPreserve saves properties values in HuntERR internal variables and sets internal flag indicating that properties were saved. All following calls to ErrPreserve will be ignored. ErrorIn after including error properties into error report clears this flag.

Contents



HuntERR31.ErrRestore Sub

Description

Restores Err object properties from values saved by ErrPreserve.

Declaration

Public Sub ErrRestore()

Parameters

None.

Comments

None.

Contents



HuntERR31.ErrContinue Sub

Description

Continues interrupted stack-unwinding process.

Declaration

Public Sub ErrContinue(ByVal AnErrNum As Long, ByVal AnErrReport)

Parameters

AnErrNum

Error number for continuation.

AnErrReport

Error Report for continuation.

Comments

Provides easy way to continue stack-unwind process interrupted for some reason. For example, some method built for scripting environment may stop propagation and return value indicating failure. If error report is available to the caller it can continue process using this method.

Contents



HuntERR31.ErrGetFromServer Sub

Description

Retrieves error information from custom COM object. This information will be included into error report by ErrorIn.

Declaration

Public Sub ErrGetFromServer(ByVal Extractor, ByVal COMServer As Object, _
        Optional ByVal Param, Optional ByVal Comment As String)

Parameters

Extractor

Instance of custom class provided by application that "knows" how to extract information from COM object. This class must have one method Extract that returns error information.

COMServer

Object from which error information should be extracted.

Param

Free form parameter that application can pass to Extract method of extractor class

Comment

Free form string that will be included into error report in the header of the information block of this COMServer.

Comments

None.

Contents



HuntERR31.IsException Function

Description

Returns true if provided error number falls into range reserved for exceptions.

Declaration

Public Function IsException(ByVal AnErrNumber As Long) As Boolean

Parameters

ErrNumber

Error number to check against error map ranges.

Comments

None.

Contents



HuntERR31.InException Function

Description

Returns True if saved error number is exception.

Declaration

Public Function InException() As Boolean

Parameters

None.

Comments

ErrorIn, ErrPreserve, or ErrGetFromServer must be called at least once in current library instance prior to calling this function. It checks not Err.Number property but error number preserved by previous call to one of these functions.

Contents



HuntERR31.InPropagation Function

Description

Returns True if propagation (stack unwinding) process is active, i.e. ErrorIn was already called at least once.

Declaration

Public Function InPropagation() As Boolean

Parameters

None.

Comments

ErrorIn, ErrPreserve, or ErrGetFromServer must be called at least once in current library instance prior to calling this function. It checks not Err.Source property but error source preserved by previous call to one of these functions.

Contents



HuntERR31.ErrReport Property

Description

Read Only. Returns error report created by last call to ErrorIn, or value of Err.Description property if ErrorIn property was not called in this instance yet, and propagation is on the way.

Declaration

Public Property Get ErrReport() As String

Parameters

None.

Comments

None.

Contents



HuntERR31.ErrReportHTML Property

Description

Read Only. Returns HTML-formatted version of ErrReport property.

Declaration

Public Property Get ErrReportHTML() As String

Parameters

None.

Comments

None.

Contents



HuntERR31.ErrNumber Property

Description

Read Only. Returns error number preserved by last call to ErrPreserve, ErrorIn, or ErrGetFromServer.

Declaration

Public Property Get ErrNumber() As Long

Parameters

None.

Comments

None.

Contents



HuntERR31.ErrSource Property

Description

Read Only. Returns error source preserved by last call to ErrPreserve, ErrGetFromServer, or set by ErrorIn.

Declaration

Public Property Get ErrSource() As String

Parameters

None.

Comments

None.

Contents



HuntERR31.ErrDescription Property

Description

Read Only. Returns error description preserved by last call to ErrPreserve, ErrGetFromServer, or set by ErrorIn.

Declaration

Public Property Get ErrDescription() As String

Parameters

None.

Comments

Error description may contain either error report, or original error description if exception is being processed.

Contents



HuntERR31.ErrOrigSource Property

Description

Read Only. Extracts original error source from error report created by last execution of ErrorIn.

Declaration

Public Property Get ErrOrigSource() As String

Parameters

None.

Comments

None.

Contents



HuntERR31.ErrOrigDescription Property

Description

Read Only. Extracts original error Description from error report created by last execution of ErrorIn.

Declaration

Public Property Get ErrOrigDescription() As String

Parameters

None.

Comments

None.

Contents



HuntERR31.ErrAccumBuffer Property

Description

Read/Write. Sets/returns internal buffer with accumulated messages. Each message is added by Check sub called with ERR_ACCUMULATE error number if Cond parameter is False. Messages are separated by CRLF character.

Declaration

Public Property Get ErrAccumBuffer() As String
Public Property Let ErrAccumBuffer(ByVal AValue As String)

Parameters

None.

Comments

None.

Contents



HuntERR31.ErrExtractFromReport Function

Description

Extracts substring from error report located between FromStr and TillStr tags.

Declaration

Public Function ErrExtractFromReport(ByVal FromStr As String, ByVal TillStr As String)

Parameters

FromStr

Start tag. Not included into result string.

TillStr

End tag. Not included into result string.

Comments

None.

Contents



HuntERR31.ErrMessageSource Property

Description

Read/Write. Sets/returns message source object. The object must implement GetMessage function that returns message by its key.

Declaration

Public Property Get ErrMessageSource() As Object
Public Property Set ErrMessageSource(ByVal Obj As Object)

Parameters

None.

Comments

None.

Contents



HuntERR31.ErrRlsObjs Sub

Description

Clears up to 8 object references provided as parameters.

Declaration

Public Sub ErrRlsObjs(Optional ByRef Obj1 As Object, _
                            Optional ByRef Obj2 As Object, _
                            Optional ByRef Obj3 As Object, _
                            Optional ByRef Obj4 As Object, _
                            Optional ByRef Obj5 As Object, _
                            Optional ByRef Obj6 As Object, _
                            Optional ByRef Obj7 As Object, _
                            Optional ByRef Obj8 As Object)

Parameters

Up to 8 object references

Comments

Preserves error information. Note that actual object release happens at the moment of return from Sub. If one of the objects is ADO object then reference to Connection object is preserved internally.

Contents



HuntERR31.ErrCloseFiles Sub

Description

Closes file handles provided as parameters. Tries to release only non-zero handles.

Declaration

Public Sub ErrCloseFiles(ParamArray Files())

Parameters

ParamArray of File handles, values of type Long or other integer types.

Comments

Preserves error information. Fail-safe. If error occurs it is ignored.

Contents



HuntERR31.ErrMustStop Function

Description

Returns True if execution should stop in error handler in IDE. Used in Stop-on-Error operators in error handlers.

Declaration

Public Function ErrMustStop() As Boolean

Parameters

None

Comments

Return value depends on ErrStopFlag value, and previous selection made by user in Stop message box.

Contents



HuntERR31.ErrStopFlag Function

Description

Returns False if H_NOSTOP conditional compilation argument is defined and set to 1. Returns false otherwise.

Declaration

Public Property Get ErrStopFlag() As Boolean

Parameters

None

Comments

H_NOSTOP argument allows to easily disable stop-on-error operators without removing them from code in IDE. ErrStopFlag is its boolean equivalent.

Contents



HuntERR31.ErrSaveToEventLog Function

Description

Saves error report to event log. Returns true if successful, False if error occurred.

Declaration

Public Function ErrSaveToEventLog() As Boolean

Parameters

None.

Comments

Logging to Event Log commands are ignored when application is run from VB IDE.

Contents



HuntERR31.ErrSaveToFile Function

Description

Saves(appends) error report to text file. Returns true if successful, False if error occurred.

Declaration

Public Function ErrSaveToFile(Optional ByVal ErrFileName As String = "Errors.txt") As Boolean

Parameters

ErrFileName

Optional. Name of file to save error to.

Comments

Creates new file if it doesn't exist. If fails to open file, retries for 100 milliseconds before giving up to make provision for the fact that several components may be trying to access the file. If you specify filename only without path function will attach application path, so error file will be located in the same folder where your EXE or DLL binary file is located.

Contents



HuntERR31.ErrSaveToDB Function

Description

Saves error report to database. Returns true if successful, False if error occurred.

Declaration

Public Function ErrSaveToDB(ByVal ConnectString As String, _
                       Optional ByVal AppID As Long = 1, _
                       Optional ByVal ProcName As String = "spErrorLogInsert") As Boolean

Parameters

ConnectString

Required. Connection string to database where error log table and corresponding stored procedure are located.

AppID

Optional. Application ID. This parameter allows you to separate errors occurring in different applications, or different components in your application.

ProcName

Optional. Name of stored procedure that inserts error report record into database table. You can use your custom stored procedure as long as it has the same parameter list as HuntERR's spErrorLogInsert .

Comments

To use this method you should create table tblErrorLog and stored procedure spErrorLogInsert in database. However, you may use your custom stored procedure with custom error log table, as long as it has the same parameters as spErrorLogInsert. In this case you may specify its name when calling this function. If error occurs in procedure it tries to post message about failure to event log.

Contents



HuntERR31.ErrInIDE Function

Description

Returns True if code is running in VB IDE.

Declaration

Public Function ErrInIDE() As Boolean

Parameters

None

Comments

Doesn't clear Err object, doesn't preserve it. May be used in mainstream code, not only in error handlers.

Contents


Module HuntERR31SysH.Bas

This module contains procedures that are responsible for system exceptions handling. System exceptions are severe application errors that normally result in crash even if error handler is in place. If application is running in VB IDE then IDE crashes as well. HuntERR enables you to turn these deadly errors into normal VB error that can be handled in usual way.

If you use this part of HuntERR functionality in your application you should include this module into your project.

We recommend you to setup system exception handler at start of your application, and keep it set for the whole span of application session. If system exception occurs HuntERR will catch it and raise ERR_SYSEXCEPTION error which will be processed in usual way in error handler of your method. Note: beginning from version 3.1 ErrorIn DOES NOT release system exception handler automatically as in previous versions. You may release handler at application unload but this is not required - Windows does this automatically.


HuntERR31SysH.ErrSysHandlerWasSet Property

Description

Read Only. Returns True if ErrSysHandlerSet was called and system exception handler was set.

Declaration

Public Property Get ErrSysHandlerWasSet() As Boolean

Parameters

None.

Comments

None.

Contents



HuntERR31SysH.ErrSysHandlerSet Sub

Description

Sets system exception handler. This handler is just a VB procedure that will be called when system exception occurs. ErrSysHandlerSet registers this procedure with Windows kernel. This operation can be undone by calling ErrSysHandlerRelease.

Declaration

Public Sub ErrSysHandlerSet()

Parameters

None.

Comments

None.

Contents



HuntERR31SysH.ErrSysHandlerRelease Sub

Description

Releases custom exception handler by restoring Windows default handler.

Declaration

Public Sub ErrSysHandlerRelease()

Parameters

None.

Comments

None

Contents


ujTransaction.Cls Class

Transaction Control Class. Helps your application to control COM+ transactions. This class should be configured in COM+ application with transactional attribute "Requires Transaction" or "Requires New Transaction". Creating the instance of this class initiates the transaction. You include other COM objects into the scope of transaction by instantiating them through CreateInstance method of transaction control object. After completing the operation application should call SetComplete method of this class to commit the transaction. In case of error transaction is aborted by calling SetAbort method.

This class implementation is independent from other HuntERR functionality, so you can use it for transaction control even if you don't use HuntERR for error handling.


ujTransaction.CreateInstance Function

Description

Application calls this method to create COM object in the scope of transaction started by transaction control class instance.

Declaration

Public Function CreateInstance(ByVal ProgID As String) As Object

Parameters

ProgID

ProgID of object to be created.

Comments

None.

Contents



ujTransaction.SetComplete Sub

Description

Commits the transaction initiated by this class instance.

Declaration

Public Sub SetComplete()

Parameters

None.

Comments

Transaction commits immediately AFTER returning from this method. This procedure clears Err object as a side effect.

Contents



ujTransaction.SetAbort Sub

Description

Aborts the transaction initiated by this class instance.

Declaration

Public Sub SetAbort()

Parameters

None.

Comments

Transaction aborts immediately AFTER returning from this method. This procedure clears Err object as a side effect.

Contents


ujEEDomDoc.Cls Class

Error extractor class for MSXML DOMDocument COM Server. Use this class as a model for building your own custom extractor. Extractor classes are used as extensions of HuntERR to allow process errors in custom COM Servers.


Extract Function

Description

Extracts error information from custom COM object. Called by ErrGetFromServer method which in turn is called by application in error handler.

Declaration

Public Function Extract(ByVal COMServer As Object, ByVal Param) As String

Parameters

COMServer

Instance of COM object provided by application in a call to ErrGetFromServer .

Param

Free-form parameter that your application may use to send some additional information to Extract method. You specify the value in a call to ErrGetFromServer, and it passes this parameter to Extract function.

Comments

Please read the section about HuntERR extensions and writing custom extractors in HuntERR Programmer's Guide.

Contents


frmShowError.frm Form

A simple form to show error report to developer. We recommend to use this form to view error report immediately after the error happens during development. Include this form into your main EXE project or test EXE project that you use to debug your COM components.


ErrorReport Property

Description

Write Only. Use this property to show error report. Assign error report string to this property and report will appear in the form.

Declaration

Public Property Let ErrorReport(ByVal AReport As String)

Parameters

AReport

Error report to show

Comments

Shows the form if it was not shown yet. First tries to show it as non-modal. If your application has modal window hanging then this would fail, and form will appear as modal.

Contents


Copyright URFIN JUS (www.urfinjus.net) , 2001-2002. All rights reserved.