Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Return Codes (OLE DB)
Collapse the table of content
Expand the table of content

Return Codes (OLE DB)

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 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.

© 2015 Microsoft