Error Object

Description

An Error object contains details about data access errors, each of which pertains to a single operation involving DAO.

Remarks

Any operation involving DAO can generate one or more errors. For example, a call to an ODBC server might result in an error from the database server, an error from ODBC, and a DAO error. As each such error occurs, an Error object is placed in the Errors collection of the DBEngine object. A single event can therefore result in several Error objects appearing in the Errors collection.

When a subsequent DAO operation generates an error, the Errors collection is cleared, and one or more new Error objects are placed in the Errors collection. DAO operations that don't generate an error have no effect on the Errors collection.

The set of Error objects in the Errors collection describes one error. The first Error object is the lowest level error (the originating error), the second the next higher level error, and so forth. For example, if an ODBC error occurs while trying to open a Recordset object, the first Error object — Errors(0) — contains the lowest level ODBC error; subsequent errors contain the ODBC errors returned by the various layers of ODBC. In this case, the ODBC driver manager, and possibly the driver itself, return separate Error objects. The last Error object — Errors.Count-1 — contains the DAO error indicating that the object couldn't be opened.

Enumerating the specific errors in the Errors collection enables your error-handling routines to more precisely determine the cause and origin of an error, and take appropriate steps to recover. On both Microsoft Jet and ODBCDirect workspaces, you can read the Error object's properties to obtain specific details about each error, including:

The Description property, which contains the text of the error alert that will be displayed on the screen if the error is not trapped.
The Number property, which contains the Long integer value of the error constant.
The Source property, which identifies the object that raised the error. This is particularly useful when you have several Error objects in the Errors collection following a request to an ODBC data source.
The HelpFile and HelpContext properties, which indicate the appropriate Microsoft Windows Help file and Help topic, respectively, (if any exist) for the error.

Note When programming in Microsoft Visual Basic for Applications (VBA), if you use the New keyword to create an object that subsequently causes an error before that object has been appended to a collection, the DBEngine object's Errors collection won't contain an entry for that object's error, because the new object is not associated with the DBEngine object. However, the error information is available in the VBA Err object.

Your VBA error-handling code should examine the Errors collection whenever you anticipate a data access error. If you are writing a centralized error handler, test the VBA Err object to determine if the error information in the Errors collection is valid. If the Number property of the last element of the Errors collection (DBEngine.Errors.Count - 1) and the value of the Err object match, you can then use a series of Select Case statements to identify the particular DAO error or errors that occurred. If they do not match, use the Refresh method on the Errors collection.

Properties

Description property, HelpContext, HelpFile properties, Number property, Source property.

Specifics (Microsoft Access)

The Description property of an Error object contains the descriptive string associated with a particular Data Access Objects (DAO) error. You can read the Description property only if the DAO error has occurred.

To determine the descriptive string associated with a DAO error that hasn't occurred, use the Microsoft Access AccessError function. The AccessError function takes an error number as an argument and returns the descriptive string. For example, if you want to determine the descriptive string associated with DAO error 3021, you might use the AccessError function as follows:

Debug.Print AccessError(3021)

Microsoft Access prints the descriptive string associated with DAO error 3021, "No current record," to the Debug window.

Example

See the Description property example.

Example (Microsoft Access)

The following example generates an error by attempting to open a Recordset object on a nonexistent Students table. Information about the error is stored in both the DAO Error object and the Visual Basic Err object. The procedure prints the value of the Description, Source, and Number properties of the Error object. Then it prints the values of the corresponding properties of the Err object.

Note that the last Error object in the Errors collection should always refer to the same error as the Err object. That is, the value of Err.Number should be equivalent to Errors.Count – 1. If these two values aren't equivalent, information in the Errors collection may be outdated. Use the Refresh method to ensure that the Errors collection includes the most recent error information.

Sub CheckError()
    Dim dbs As Database, tdf As TableDef, rst As Recordset
    ' Declare Error object variable for enumeration 
    ' of Errors collection.
    Dim errX As Error
    
    ' Ignore errors.
    On Error Resume Next
    ' Clear error in Err object.
    Err.Clear
    ' Refresh Errors collection.
    Errors.Refresh
    ' Return reference to current database.
    Set dbs = CurrentDb
    ' Attempt to open Recordset object on nonexistent table.
    Set rst = dbs.OpenRecordset("Students")
    Debug.Print "DAO Error Object:"
    ' Print number of errors in Errors collection.
    Debug.Print ">>>Number of errors: "; Errors.Count
    ' Enumerate Errors collection and key properties.
    For Each errX In DBEngine.Errors
        Debug.Print errX.Description
        Debug.Print errX.Source
        Debug.Print errX.Number
    Next errX
    Debug.Print
    Debug.Print "VBA Err Object:"
    ' Display corresponding properties of Err object.
    Debug.Print Err.Description
    Debug.Print Err.Source
    Debug.Print Err.Number
    Set dbs = Nothing
End Sub