Return Codes

OLE DB Programmer's Reference

Each method returns a return code, which indicates the overall success or failure of the method. These return codes are of type HRESULT. There are two classes of return codes: success and warning codes, and error codes.

Success and warning codes begin with S_ or DB_S_ (for example, S_OK) and indicate that the method successfully completed. If the return code is other than S_OK or S_FALSE, it is likely that an error occurred from which the method was able to recover. For example, IRowset::GetNextRows returns DB_S_ENDOFROWSET when it is unable to return the requested number of rows due to reaching the end of the rowset or chapter. If a single warning condition occurs, the method returns the code for that condition; if multiple warning conditions occur, the documentation for the method describes the hierarchy of warning return codes—that is, which warning code should be returned when given a choice between multiple warning return codes.

Error codes begin with E_ or DB_E_ (for example, DB_E_BADACCESSORHANDLE) and indicate that the method failed and was unable to do any useful work. For example, IRowset::GetNextRows returns E_INVALIDARG when the pointer in which it is to return a pointer to an array of row handles (prghRows) is null. One exception is that some of the methods that return DB_E_ERRORSOCCURRED allocate memory in which to return additional information about these errors. Consumers must free this memory. Although error codes can indicate run-time errors such as running out of memory, they usually indicate programming errors. If multiple errors occur, which code is returned is provider-specific. If both errors and warnings occur, the method fails and returns an error code.

All methods can return S_OK, E_FAIL, and E_OUTOFMEMORY. The reference sections list S_OK and E_FAIL for all methods. In most cases, E_OUTOFMEMORY is listed only for those methods that allocate memory that is returned to the consumer. The reason for listing E_OUTOFMEMORY in these sections is to remind consumers that they might be able to call the method successfully by requesting fewer returned values, such as fewer rows from IRowset::GetNextRows.

In addition to the return codes for errors listed in the OLE DB Programmer's Reference, providers can return provider-specific error codes. However, providers must not return success codes other than those listed in the Programmer's Reference.

Note   Methods that can return DB_S_ERRORSOCCURRED do so only when one or more errors occur. Methods that fail entirely (that is, encounter nothing but errors) can return DB_E_ERRORSOCCURRED. Some providers incorrectly return DB_S_ERRORSOCCURRED (instead of S_OK) when no errors but one or more warnings occur.

1998-2001 Microsoft Corporation. All rights reserved.