OLE DB Error Objects

OLE DB Programmer's Reference

Automation error objects do not support two capabilities required by OLE DB:

• The ability to return multiple error records from a single call
• The ability to return provider-specific error information

For example, each service component in the stack of service components might want to add its own error information to the existing error information, and a provider might want to expose error information that is unique to it.

To solve this problem, OLE DB extends Automation error objects. In particular, it adds the ability for an error object to contain multiple error records. That is, an Automation error object effectively contains a single error record, while an OLE DB error object contains multiple error records.

Support for OLE DB error objects is provider-specific. Providers can choose to generate them from all, none, or a subset of their interfaces. Consumers can call ISupportErrorInfo::InterfaceSupportsErrorInfo for each interface to determine whether the interface supports error objects.

OLE DB error objects can be created by any method call. Although they are most commonly created when the method returns an error or warning, such as the DB_E_ERRORSINCOMMAND code returned by ICommand::Execute or the DB_S_ERRORSOCCURRED code returned by IRowsetUpdate::Update, they can also be returned when the method succeeds and returns S_OK.

OLE DB providers are not required to generate error objects, even if a method on an interface that supports error objects returns an error. In this case, even though ISupportErrorInfo returns S_OK, calling GetErrorInfo returns a null value. However, the provider is required to clear any existing error objects when any method on an interface that supports error objects is called, whether or not that method returns an error. Therefore, the consumer can be assured that if an error object does exist after calling a method on an interface that supports error objects, the error object describes the outcome of that method.

1998-2001 Microsoft Corporation. All rights reserved.