MDAC 2.5 SDK - OLE DB Programmer's Reference
Chapter 6: Getting and Setting Data

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. The status is described in the DBSTATUS enumerated type defined in Appendix D, "Cotypes, Structures, and Enumerated Types."

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 that the consumer can determine which data values it got successfully. It produces the return codes as follows:

Success return code (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 of variable length data 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. If status is bound, the consumer can check the status value to learn why the column failed.
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.

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 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 was 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 might cause deferred accessor validation to fail, see the description of the DBBINDSTATUS values listed under the rgStatus argument in the reference entry for "IAccessor::CreateAccessor."
DBSTATUS_E_CANTCONVERTVALUE	Error	N	The data value could not be converted for reasons other than sign mismatch or data overflow. For example, the data was corrupted in the data store 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, 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 the 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 data or to set input parameter data, use ICommand::Execute, IRowsetChange::SetData, IRowsetChange::InsertRow, IRowsetIndex::Seek, and IRowsetIndex::SetRange. When calling these methods, the consumer must set the status to one of the values in the following table.

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 IRowsetChange::SetData or IRowsetChange::InsertRow or 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 sets them on output for input/output parameters. This status value is never returned when getting data. If the provider can determine the default value on output, that value is returned along with a status of DBSTATUS_S_OK if the default is not NULL, or DBSTATUS_S_ISNULL if the default is NULL. If the provider cannot determine the default value on output, it returns DBSTATUS_E_UNAVAILABLE when calling IRowset::GetData for columns set as DBSTATUS_S_DEFAULT. Consumers should be prepared for OLE DB 1.0 or 1.1 providers to return DBSTATUS_E_BADSTATUS when attempting to specify DBSTATUS_S_DEFAULT in IRowsetChange::SetData or in IRowsetChange::InsertRow or for providers that cannot set a column to its default value.
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 parameter values. Consumers should be prepared for OLE DB 1.x providers to return DBSTATUS_E_BADSTATUS when attempting to specify DBSTATUS_S_IGNORE in IRowsetChange::SetData or in IRowsetChange::InsertRow. Note In IRowsetChange::InsertRow, specifying DBSTATUS_S_IGNORE for a column is equivalent to not including that column in the accessor. For most providers, this is equivalent to specifying DBSTATUS_S_DEFAULT.

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. The provider produces return codes as follows:

Success return code (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 of variable-length data is an error condition when setting data. The corresponding status is set to DBSTATUS_E_CANTCONVERTVALUE or DBSTATUS_E_OVERFLOW as appropriate.
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.

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_S_IGNORE	Success	N	The consumer specified DBSTATUS_S_IGNORE when setting data, and the provider ignored the column.
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 DBBINDSTATUS values listed under the rgStatus argument of in the reference entry for "IAccessor::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, the binding was not passed as an input or input/output parameter in a procedure, and the provider was not able to determine the default value for the column. The status value was DBSTATUS_S_DEFAULT, the binding was used in a method other than IRowsetChange::SetData or IRowsetChange::InsertData, and the binding was not passed as 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 1.1 provider. The binding used in IRowsetChange::SetData did not contain the value part, and status on input is not DBSTATUS_S_ISNULL, DBSTATUS_S_IGNORE, DBSTATUS_S_DEFAULT nor DBSTATUS_S_OK. 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_S_IGNORE, and the provider was a 1.x provider.
DBSTATUS_E_CANTCONVERTVALUE	Error	N	The data value could not 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	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's constraint 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	One of the following conditions: The consumer did not bind the value part, IColumnsInfo::GetColumnInfo does not return DBCOLUMNFLAGS_ISLONG for the column, and the status was DBSTATUS_S_OK. 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. 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.