MDAC 2.5 SDK - OLE DB Providers
OLE DB Provider for SQL Server
At the most basic level, a member function either succeeds or fails. At a somewhat more precise level, a function can succeed but its success might not be identical to that intended by the application developer.
When a SQLOLEDB member function returns S_OK, the function succeeded.
When a SQLOLEDB member function does not return S_OK, the COM HRESULT-unpacking FAILED and IS_ERROR macros can determine the overall success or failure of a function.
If FAILED or IS_ERROR returns TRUE, the SQLOLEDB consumer is assured that member function execution failed. When FAILED or IS_ERROR return FALSE and the HRESULT does not equal S_OK, the SQLOLEDB consumer is assured that the function succeeded in some sense. The consumer can retrieve detailed information on this success-with-information return from SQLOLEDB error interfaces. Also, in the case where a function clearly fails (the FAILED macro returns TRUE), extended error information is available from the SQLOLEDB error interfaces.
SQLOLEDB consumers commonly encounter the DB_S_ERRORSOCCURRED success-with-information HRESULT return. Typically, member functions that return DB_S_ERRORSOCCURRED define one or more parameters that deliver status values to the consumer. No error information may be available to the consumer other than that returned in status-value parameters, so consumers should implement application logic that retrieves status values when they are available.
SQLOLEDB member functions do not return the success code S_FALSE. Any SQLOLEDB member function always returns S_OK to indicate success.