The latest version of this document and full HuntERR download package is located
here.
Your feedback is welcome: feedback@urfinjus.net
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. |
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
Main library module. Provides most of library's functionality.
Enumeration defining ranges of error numbers.
|
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
Enumeration defining flags specifying actions performed by ErrorIn function.
|
ErrorAction parameter of ErrorIn function expects set of flags specifying actions that it should perform. This enumeration defines these flags.
Processes the error/exception in error handler.
|
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. |
Main super-function of HuntERR library. Should be called in error handlers to process errors. Read HuntERR Guide for more information.
Checks if logical condition is true, and if not raises exception with specified number and description.
|
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. |
Check provides a convenient way to implement a checkpoint in application code. You can raise errors or exceptions using Check.
Preserves Number, Source and Description properties of Err object in internal variables.
|
None.
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.
Restores Err object properties from values saved by ErrPreserve.
|
None.
None.
Continues interrupted stack-unwinding process.
|
AnErrNum | Error number for continuation. |
AnErrReport | Error Report for continuation. |
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.
Retrieves error information from custom COM object. This information will be included into error report by ErrorIn.
|
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. |
None.
Returns true if provided error number falls into range reserved for exceptions.
|
ErrNumber | Error number to check against error map ranges. |
None.
Returns True if saved error number is exception.
|
None.
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.
Returns True if propagation (stack unwinding) process is active, i.e. ErrorIn was already called at least once.
|
None.
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.
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.
|
None.
None.
Read Only. Returns HTML-formatted version of ErrReport property.
|
None.
None.
Read Only. Returns error number preserved by last call to ErrPreserve, ErrorIn, or ErrGetFromServer.
|
None.
None.
Read Only. Returns error source preserved by last call to ErrPreserve, ErrGetFromServer, or set by ErrorIn.
|
None.
None.
Read Only. Returns error description preserved by last call to ErrPreserve, ErrGetFromServer, or set by ErrorIn.
|
None.
Error description may contain either error report, or original error description if exception is being processed.
Read Only. Extracts original error source from error report created by last execution of ErrorIn.
|
None.
None.
Read Only. Extracts original error Description from error report created by last execution of ErrorIn.
|
None.
None.
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.
|
None.
None.
Extracts substring from error report located between FromStr and TillStr tags.
|
FromStr | Start tag. Not included into result string. |
TillStr | End tag. Not included into result string. |
None.
Read/Write. Sets/returns message source object. The object must implement GetMessage function that returns message by its key.
|
None.
None.
Clears up to 8 object references provided as parameters.
|
Up to 8 object references
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.
Closes file handles provided as parameters. Tries to release only non-zero handles.
|
ParamArray of File handles, values of type Long or other integer types.
Preserves error information. Fail-safe. If error occurs it is ignored.
Returns True if execution should stop in error handler in IDE. Used in Stop-on-Error operators in error handlers.
|
None
Return value depends on ErrStopFlag value, and previous selection made by user in Stop message box.
Returns False if H_NOSTOP conditional compilation argument is defined and set to 1. Returns false otherwise.
|
None
H_NOSTOP argument allows to easily disable stop-on-error operators without removing them from code in IDE. ErrStopFlag is its boolean equivalent.
Saves error report to event log. Returns true if successful, False if error occurred.
|
None.
Logging to Event Log commands are ignored when application is run from VB IDE.
Saves(appends) error report to text file. Returns true if successful, False if error occurred.
|
ErrFileName | Optional. Name of file to save error to. |
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.
Saves error report to database. Returns true if successful, False if error occurred.
|
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 . |
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.
Returns True if code is running in VB IDE.
|
None
Doesn't clear Err object, doesn't preserve it. May be used in mainstream code, not only in error handlers.
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.
Read Only. Returns True if ErrSysHandlerSet was called and system exception handler was set.
|
None.
None.
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.
|
None.
None.
Releases custom exception handler by restoring Windows default handler.
|
None.
None
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.
Application calls this method to create COM object in the scope of transaction started by transaction control class instance.
|
ProgID | ProgID of object to be created. |
None.
Commits the transaction initiated by this class instance.
|
None.
Transaction commits immediately AFTER returning from this method. This procedure clears Err object as a side effect.
Aborts the transaction initiated by this class instance.
|
None.
Transaction aborts immediately AFTER returning from this method. This procedure clears Err object as a side effect.
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.
Extracts error information from custom COM object. Called by ErrGetFromServer method which in turn is called by application in error handler.
|
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. |
Please read the section about HuntERR extensions and writing custom extractors in HuntERR Programmer's Guide.
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.
Write Only. Use this property to show error report. Assign error report string to this property and report will appear in the form.
|
AReport | Error report to show |
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.
Copyright URFIN JUS (www.urfinjus.net) , 2001-2002. All rights reserved.