Return Codes

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 may 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 OLE/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, then 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.