Status

The status indicates whether the data value or some other value, such as a NULL, is to be used as the value of the column or parameter. If the data value is to be used, the consumer sets the status to DBSTATUS_S_OK on input. On output, the provider returns information about whether the consumer was able to set or get the value.

If the data value is not to be used, the status is set to DBSTATUS_S_ISNULL or DBSTATUS_S_DEFAULT. DBSTATUS_S_ISNULL indicates that a NULL value is to be used for the column or parameter; the data value and length are ignored. DBSTATUS_S_DEFAULT indicates that the default value of an input or input/output parameter in a procedure is to be used on input. The data value and length are ignored on input. However, they are used on output for an input/output parameter.

Status Values Used When Getting Data

To get rowset or output parameter data, use ICommand::Execute, IMultipleResults::GetResults, IRowset::GetData, IRowsetRefresh::GetLastVisibleData, and IRowsetUpdate::GetOriginalData. As the provider returns the data, it sets the status of each column or output parameter so the consumer can determine which data values it got successfully. It produces the return codes as follows:

Success return code (generally S_OK)—No errors occurred while getting data for any columns or parameters. Warning conditions may have occurred for any columns or parameters.
Note Truncation is a warning condition when getting data. The corresponding status is set to DBSTATUS_S_TRUNCATED.
DB_S_ERRORSOCCURRED—Errors occurred while getting data for one or more columns or parameters but data was successfully returned for at least one column or parameter. Warning conditions may have occurred for any nonerror columns or parameters.
DB_E_ERRORSOCCURRED—Errors occurred while getting data for all columns or parameters. Warning conditions did not occur for any columns or parameters.

If the provider returns a fatal error other than DB_E_ERRORSOCCURRED, such as E_FAIL, the returned status values are undefined. If the consumer did not bind the status for a column or output parameter and the method returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED, the consumer must assume that the value for that column or output parameter was not successfully returned.

The following table explains the meaning of each returned status value, whether it is a success, error, or warning condition, and whether data was successfully returned.

Status values for returned data

Status value	Success, warning, or error	Data returned	Description
DBSTATUS_S_OK	Success	Y	The provider returned a non-NULL value.
DBSTATUS_S_ISNULL	Success	Y	The provider returned a NULL value.
DBSTATUS_S_ TRUNCATED	Warning	Y	Variable-length data or nonsignificant digits of numeric data were truncated.
DBSTATUS_E_ BADACCESSOR	Error	N	Accessor validation was deferred and was performed while the method returned data. The binding was invalid for this column or parameter. For a description of the cases that may cause deferred accessor validation to fail, see the description of the DBBINDSTATS values listed under the rgStatus argument of CreateAccessor.
DBSTATUS_E_ CANTCONVERTVALUE	Error	N	The data value couldn't be converted for reasons other than sign mismatch or data overflow. For example, the data was corrupted in the data source but the row was still retrievable.
DBSTATUS_E_ CANTCREATE	Error	N	One of the following conditions: The provider could not allocate memory in which to return data. The type indicator for the column was DBTYPE_IUNKNOWN and a storage object was already open on the column. The type indicator for the column was DBTYPE_IUNKNOWN, the provider supports only one open storage object at a time (DBPROP_ MULTIPLESTORAGEOBJECTS was VARIANT_FALSE), and a storage object was already open on the rowset.
DBSTATUS_E_ DATAOVERFLOW	Error	N	Conversion failed because the data value overflowed the type specified for the value part in the consumer's buffer.
DBSTATUS_E_ SIGNMISMATCH	Error	N	Conversion failed because the data value was signed and the type specified for the value part in the consumer's buffer was unsigned.
DBSTATUS_E_ UNAVAILABLE	Error	N	The provider could not determine a value. For example, the row was just created, the default for the column was not available, and the consumer had not yet set a new value.

Status Values Used When Setting Data

To set rowset or input parameter data, use ICommand::Execute, IRowsetChange::SetData, IRowsetChange::InsertRow, IRowsetIndex::Seek, and IRowsetIndex::SetRange. When using these methods, the consumer must set the status to one of the following values.

Status value	Description
DBSTATUS_S_OK	The value sent to the provider is not NULL and is passed in the consumer's buffer at the offset specified by obValue in the binding.
DBSTATUS_S_ISNULL	The value sent to the provider is NULL. The provider ignores the contents of the value and length parts of the consumer's buffer.
DBSTATUS_S_ DEFAULT	The provider is to use the default value in SetData or InsertRow, or use it as the input value for an input or input/output parameter in a procedure. The provider ignores the contents of the value and the length parts of the consumer's buffer on input, although it uses them on output for input/output parameters. This value is never returned when getting data. If the provider can determine the default value, that value is returned along with a status of DBSTATUS_S_OK if the default is non-null, or DBSTATUS_S_ISNULL if the default is null. If the provider cannot determine the default value, it returns DBSTATUS_E_UNAVAILABLE when calling GetData for columns set as DBSTAUS_S_DEFAULT. Note that consumers should be prepared for 1.0 or 1.1 providers to return DBSTATUS_E_BADSTATUS when attempting to specify DBSTATUS_S_DEFAULT in SetData or InsertRow.
DBSTATUS_S_IGNORE	The provider is to skip this column when setting data. The provider ignores the contents of the value and the length parts of the consumer's buffer for this column and does not change the underlying column value. DBSTATUS_S_IGNORE is not valid for parameters, and returns DBSTATUS_E_BADSTATUS. Consumers should use DBSTATUS_S_DEFAULT to pass default values as parameters. Consumers should be prepared for 1.x providers to return DBSTATUS_E_BADSTATUS when attempting to specify DBSTATUS_S_IGNORE in SetData or InsertRow.

As the provider transfers data from the consumer to the provider, it sets the status of each column or input parameter so that the consumer can determine which data values were successfully set. It produces return codes as follows:

Success return code (usually S_OK)—No errors occurred while setting data for any columns or parameters.
DB_S_ERRORSOCCURRED—Errors occurred while setting data for one or more columns or parameters but data was successfully set for at least one column or parameter.
Note Truncation is an error condition when setting data. The corresponding status is set to DBSTATUS_E_CANTCONVERTVALUE.
DB_E_ERRORSOCCURRED—Errors occurred while setting data for all columns or parameters.

If the provider returns a fatal error other than DB_E_ERRORSOCCURRED, such as E_FAIL, the returned status values are undefined. If the consumer did not bind the status for a column or input parameter and the method returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED, the consumer must assume that the value for that column or input parameter was not successfully set.

The following table explains the meaning of each returned status value, whether it is a success or error condition, and whether data was successfully sent.

Returned status values for sent data

Status value	Success, warning, or error	Data sent	Description
DBSTATUS_S_OK	Success	Y	A non-NULL value was sent to the provider.
DBSTATUS_S_ISNULL	Success	Y	A NULL value was sent to the provider.
DBSTATUS_S_ DEFAULT	Success	Y	The provider used the default value for an input parameter in a procedure. If the provider used the default value on input for an input/output parameter, the status is set to the status of the output value on output.
DBSTATUS_E_ BADACCESSOR	Error	N	Accessor validation was deferred and was performed while the method sent data. The binding was invalid for this column or parameter. For a description of the cases that may cause deferred accessor validation to fail, see the description of the DBBINDSTATS values listed under the *rgStatus* argument of CreateAccessor.
DBSTATUS_E_ BADSTATUS	Error	N	One of the following conditions: The status value sent to the provider was not DBSTATUS_S_OK, DBSTATUS_S_ISNULL, DBSTATUS_S_IGNORE, or DBSTATUS_S_DEFAULT. The status value was DBSTATUS_S_DEFAULT and the binding was not used in SetData, InsertData, or for an input or input/output parameter in a procedure. The status value was DBSTATUS_S_DEFAULT, the binding was not for an input or input/output parameter in a procedure, and the provider was a 1.0 or a 1.1 provider. The binding used in SetData only contained the status part and the status value was not DBSTATUS_S_ISNULL. The status value sent to the provider was DBSTATUS_S_IGNORE and the binding was for a parameter in a procedure. The status value sent to a provider was DBSTATUS_IGNORE and the provider was a 1.x provider.
DBSTATUS_E_ CANTCONVERTVALUE	Error	N	The data value couldn't be converted for reasons other than sign mismatch or data overflow. For example, converting the data would have truncated it, including truncating nonsignificant digits in numeric data.
DBSTATUS_E_ CANTCREATE	Error	N	One of the following conditions: The type indicator for the column was DBTYPE_IUNKNOWN and a storage object was already open on the column. The type indicator for the column was DBTYPE_IUNKNOWN, the provider supports only one open storage object at a time (DBPROP_ MULTIPLESTORAGEOBJECTS was VARIANT_FALSE), and a storage object was already open on the rowset.
DBSTATUS_E_ DATAOVERFLOW	Error	N	Conversion failed because the data value overflowed the type used by the provider.
DBSTATUS_E_ INTEGRITYVIOLATION	Error	N	The data value violated the integrity constraints for the column.
DBSTATUS_E_ PERMISSIONDENIED	Error	N	The DBPROP_COLUMNRESTRICT property was VARIANT_TRUE and the user did not have permission to write to the column.
DBSTATUS_E_ SCHEMAVIOLATION	Error	N	The data value violated the schema for the column.
DBSTATUS_E_ SIGNMISMATCH	Error	N	Conversion failed because the data value was signed and the type used by the provider was unsigned.
DBSTATUS_E_ UNAVAILABLE	Error	N	The value was not sent for an undetermined reason. For example, the provider encountered an error while sending a column or parameter value and stopped processing. If the provider backs out changes it made before the error, it also sets the status of the columns from which it backs data out to DBSTATUS_E_UNAVAILABLE.
DBSTATUS_E_ UNAVAILABLE	Error	N	One of the following conditions: The consumer did not bind the value part of the data, the status was DBSTATUS_S_OK, and IColumnsInfo::GetColumnInfo did not return the DBCOLUMNFLAGS_ISLONG flag for the column. The consumer did not bind the length part of the data, the status was DBSTATUS_S_OK, and wType in the DBBINDING structure was DBTYPE_BYTES.