Error Lookup Services

OLE DB Programmer's Reference

The ERRORINFO structure does not contain the error messages and help file information that IErrorInfo can return. Instead, this information is stored in a provider-specific lookup service. There are three important reasons for this: First, it allows the information to be easily localized. Second, it means that memory need not be allocated to store the information until the information is requested. Third, it provides an easy mechanism by which the provider can parameterize error messages.

The information in this lookup service can be created when the lookup service is written or it can be created at run time. The former case, which creates what are called static errors, is common when the lookup service is tied to a single database and the programmer knows ahead of time what the error messages are. For example, a provider built directly over an Oracle database might use static errors. The run-time case, which creates dynamic errors, is common when the lookup service is not tied to any particular database and the programmer cannot predict the error messages. For example, a provider built on top of any ODBC driver might use dynamic errors. The lookup service creates dynamic errors at run time and releases them when the error object with which they are associated calls IErrorLookup::ReleaseErrors as part of its release code. Dynamic errors are identified by a dynamic error ID. In most cases, all dynamic errors associated with a single error object have the same ID. This is not required, but it is more efficient when releasing error objects.

An error lookup service must be created by each provider that supports OLE DB error objects. The lookup service exposes the IErrorLookup interface. For information about the registry entries used by error lookup services, see "Error Lookup Service Registry Entries" in Chapter 18: Programming Considerations.

When a consumer calls IErrorInfo::GetDescription or IErrorInfo::GetSource for a particular record in an OLE DB error object, the error object creates an instance of the error lookup service. The error object then calls IErrorLookup::GetErrorDescription and passes the hrError element of the record's ERRORINFO structure, along with the lookup ID, the locale ID, and the parameters. GetErrorDescription uses the information provided to retrieve the error description and inserts the parameters into this description. However, if the lookup ID is set to IDENTIFIER_SDK_ERROR, the error object bypasses the error lookup service and retrieves the error description from the error resource DLL shipped with the MDAC SDK. Finally, the error object returns the completed, localized error message and source to the error object, which returns error messages to the consumer.

A similar process occurs when the consumer calls IErrorInfo::GetHelpFile or IErrorInfo::GetHelpContext, although no parameters are passed. If the lookup ID is set to IDENTIFIER_SDK_ERROR, the error object uses the error lookup service to get the Help file and Help context ID.

1998-2001 Microsoft Corporation. All rights reserved.