Records in OLE DB error objects are numbered starting from zero. The methods in IErrorRecords allow consumers to specify the record from which to retrieve error information. As error records are added, they are added to the top of the list (that is, the number of the existing error records is increased by 1 and a new record 0 is added), so consumers can start with the highest level of error information and then retrieve increasingly more detailed information.
Each error record is composed of five parts: an ERRORINFO structure, error parameters, a pointer to a custom error object, a dynamic error ID, and a lookup ID.
The ERRORINFO structure returns most of the basic information associated with an error:
typedef struct tagERRORINFO {
HRESULT hrError;
DWORD dwMinor;
CLSID clsid;
IID iid;
DISPID dispid;
} ERRORINFO;
The elements of this structure are used as follows.
The ERRORINFO structure
| Element | Description |
| hrError | The code returned by the method. This might be different in different records in the error object. For example, suppose a query processor service component opens rowsets provided by base table data providers. If ICommand::Execute in the query processor calls IOpenRowset::OpenRowset in a base table data provider and OpenRowset fails with DB_E_NOTABLE, Execute might return DB_E_ERRORSINCOMMAND. |
| dwMinor | A provider-specific error code. |
| clsid | The class ID of the object that returned the error. |
| iid | The interface ID of the interface that generated the error. iid can be different from the ID of the interface that defines the method the consumer called. For example, if a consumer calls Execute in a query processor, the query processor calls OpenRowset in a base table data provider, and OpenRowset fails, iid is IID_IOpenRowset, not IID_ICommand. If the method that generates an error belongs to more than one interface due to inheritance, this is the ID of the first interface in which the method is defined. For example, suppose IRowsetLocate::GetRowsAt is called through a pointer to IRowsetScroll, which inherits from IRowsetLocate. If GetRowsAt fails, iid is IID_IRowsetLocate, not IID_IRowsetScroll. |
| dispid | If defined, this might indicate the method that returned the error. |
Error parameters are provider-specific values that are incorporated into error messages. For example, the provider might associate the error message Cannot open table <param1> with a dwMinor value of 10.
In the example, the error parameters would be used to supply the name of the table that could not be opened. Error parameters are inserted into error messages by a provider-specific error lookup service. Thus, the format of error parameters and how they are substituted into error messages are completely provider specific. The code in IErrorInfo calls the error lookup service. For more information, see "Error Lookup Services" later in this chapter.
Associated with each error record is a custom error object. An interface pointer to the object is stored in the record. If no custom error object exists, this pointer is null. The custom error object is the mechanism by which OLE DB error objects are extensible.
When an error record is added, the error object calls AddRef to add a reference to the custom error object. The provider that created the custom error object calls Release to release its hold on the custom error object. Thus, ownership of the custom error object is effectively transferred from the provider to the error object. The error object releases all custom error objects when it is released.
For example, ODBC-related providers can expose ISQLErrorInfo on a custom error object to return the SQLSTATE value. For more information, see ISQLErrorInfo.
The dynamic error ID is the ID of an error message created at run time by the error lookup service, as opposed to an error message hard-coded in the lookup service. The error object uses the dynamic error ID to release the dynamic error message when the error object is released. In most cases, all error messages associated with a single error object have the same dynamic error ID. For more information, see "Error Lookup Services" later in this chapter.
The error lookup service uses the lookup ID in conjunction with the return code to identify the error description, Help file, and context ID for a specific error. The lookup ID also can be a special value, IDENTIFIER_SDK_ERROR, that tells the implementation of IErrorInfo that is shipped with the OLE DB SDK to ignore the provider's lookup service and use the description supplied in the error resource DLL shipped with the OLE DB SDK. For more information, see "Error Lookup Services" later in this chapter.