Provider Errors

When a provider error occurs, a run-time error of -2147467259 is returned. When you receive this error, check the active Connection object's Errors collection, which will contain one or more errors describing what happened.

The ADO Errors Collection

Because a particular ADO operation can produce multiple provider errors, ADO exposes a collection of error objects through the Connection object. This collection contains no objects if an operation concludes successfully and contains one or more Error objects if something went wrong and the provider raised one or more errors. Examine each individual error object in order to determine the exact cause of the error.

Once you have finished handling any errors that have occurred, you can clear the collection by calling the Clear method. It is particularly important to explicitly clear the Errors collection before you call the Resync, UpdateBatch, or CancelBatch method on a Recordset object, the Open method on a Connection object, or set the Filter property on a Recordset object. By clearing the collection explicitly, you can be certain that any Error objects in the collection are not left over from a previous operation.

Some operations can generate warnings as well as errors. Warnings are also represented by Error objects in the Errors collection. When a provider adds a warning to the collection, it does not generate a run-time error. Check the Count property of the Errors collection to determine if a warning was produced by a particular operation. If the count is one or greater, an Error object has been added to the collection. Once you have determined that the Errors collection contains errors or warnings, you can iterate through the collection and retrieve information about each of the Error objects it contains. The following short Visual Basic example demonstrates this:

' BeginErrorHandlingVB02
Private Function DeleteCustomer(ByVal CompanyName As String) As Long
    On Error GoTo DeleteCustomerError
    
    rst.Find "CompanyName='" & CompanyName & "'"
    
DeleteCustomerError:

    Dim objError As ADODB.Error
    Dim strError As String

    If cnn.Errors.Count > 0 Then
        For Each objError In cnn.Errors
            strError = strError & "Error #" & objError.Number & _
                " " & objError.Description & vbCrLf & _
                "NativeError: " & objError.NativeError & vbCrLf & _
                "SQLState: " & objError.SQLState & vbCrLf & _
                "Reported by: " & objError.Source & vbCrLf & _
                "Help file: " & objError.HelpFile & vbCrLf & _
                "Help Context ID: " & objError.HelpContext
        Next
        MsgBox strError
    End If
End Function
' EndErrorHandlingVB02

The error-handling routine includes a For Each loop that examines each object in the Errors collection. In this example, it simply accumulates a message for display. In a working program, you would write code to perform an appropriate task for each error, such as closing all open files and shutting down the program in an orderly fashion.

The Error Object

By examining an Error object you can determine what error occurred, and more importantly, what application or what object caused the error. The Error object has the following properties:

The ADO Error object is quite similar to the standard Visual Basic Err object. Its properties describe the error that occurred. In addition to the number of the error, you also receive two related pieces of information. The NativeError property contains an error number specific to the provider you are using. In the previous example, the provider is the Microsoft OLE DB Provider for SQL Server, so NativeError will contain errors specific to SQL Server. The SQLState property has a five-letter code that describes an error in a SQL statement.

Event-Related Errors

The Error object is also used when event-related errors occur. You can determine if an error occurred in the process that raised an ADO event by checking the Error object passed as an event parameter.

If the operation that causes an event is concluded successfully, the adStatus parameter of the event handler will be set to adStatusOK. On the other hand, if the operation that raised the event was unsuccessful, the adStatus parameter is set to adStatusErrorsOccurred. In that case, the pError parameter will contain an Error object that describes the error.