Each method returns a code, known as the return code, that indicates the overall success or failure of the method. These return codes are of type HRESULT. Program logic is usually based on return codes. There are two classes of return codes: success and warning codes, and error codes.
Success and warning codes begin with S_ or DB_S_ 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 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_ and indicate that the method failed completely and was unable to do any useful work. For example, 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. For information about which methods allocate memory in this case, see the methods that return DB_E_ERRORSOCCURRED. 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 which allocate memory that is returned to the consumer. The reason for listing E_OUTOFMEMORY in these sections is to remind consumer programmers that they can call the method successfully by requesting fewer returned values, such as fewer rows from GetNextRows.
Note Methods that return DB_S_ERRORSOCCURRED return this error only when one or more errors occur. Consumers should be aware that some providers incorrectly return DB_S_ERRORSOCCURRED when no errors but one or more warnings occur.