Err Object

Description

Contains information about run-time errors. Accepts the Raise and Clear methods for generating and clearing run-time errors.

Syntax

Err[.{property | method}]

Remarks

The properties of the Err object are set by the generator of an error — Visual Basic, an OLE object, or the Visual Basic programmer.

The default property of the Err object is Number. Its value corresponds the value returned by the Err function in previous versions of Visual Basic. Assigning an error code to the Number property corresponds to specifying a number in the Err statement in previous versions of Visual Basic. Since the default property can be represented by the object name Err, existing code that expects a valid error number to be returned or set by Err doesn’t have to be modified. While the value of Err.Number is compatible with previous versions of Basic, it now contains a Long integer and can be used by an OLE Automation object to return an OLE SCode.

When a run-time error occurs, the properties of the Err object are filled with information that uniquely identifies the error and information that can be used to handle it. To generate a run-time error in your code, use the Raise method.

The Err object’s properties are reset to zero or zero-length strings ("") after any form of the Resume or On Error statement and after an Exit Sub, Exit Function, or Exit Property statement within an error-handling routine. The Clear method can be used to explicitly reset Err.

Caution If you set up an error handler using On Error GoTo and that handler calls another procedure, the properties of the Err object may be reset to zero and zero-length strings. To retain values for later use, assign the values of Err properties to variables before calling another procedure, or before executing Resume, On Error, Exit Sub, Exit Function, or Exit Property statements.

When writing code for an OLE Automation object in Visual Basic, use the Raise method (rather than the Error statement) to generate run-time errors. Whether or not to use the Raise method in new non-OLE Automation code depends on the richness of the information you want to return. In code that uses Error statements instead of the Raise method to generate errors, the properties of the Err object are assigned the following default values when Error is executed:

There is no need to change existing code that used Err and the Error statement. However, mixing use of the Err object and the Error statement can result in unintended consequences. For instance, even if you fill in the Err object’s properties, they are reset to the default values indicated in the preceding table as soon as the Error statement is executed. Although you can still use the Error statement to generate Visual Basic run-time errors, it is retained principally for compatibility with existing code. Use the Err object and the Raise and Clear methods for system errors and in new code, especially for OLE Automation objects.

The Err object is an intrinsic object with global scope — there is no need to create an instance of it in your code.

Properties

Description Property, HelpContext Property (Visual Basic), HelpFile Property (Visual Basic), LastDLLError Property, Number Property, Source Property.

Methods

Clear Method, Raise Method.

See Also

Error Function, Error Statement, On Error Statement, Resume Statement.

Example

This example uses the properties of the Err object in constructing an error-message dialog box. Note that when you generate a Visual Basic error with the Raise method, if you use the Clear method first, Visual Basic’s default values become the properties of the Err object.

' If an error occurs, construct an error messageError Resume Next    ' Defer error handling..Clear.Raise 6        ' Generate an "Overflow" error.
' Check for error, then show message.Err.Number <> 0 Then
    Msg = "Error # " & Str(Err.Number) & " was generated by " _
        & Err.Source & Chr(13) & Err.Description
    MsgBox Msg, , "Error", Err.Helpfile, Err.HelpContextIf