Data has three parts: the data value, the length of the data value, and the status of the data value. The consumer can bind one, two, or all three of these parts. Except in very rare cases, the consumer always binds the data value and the status, and always binds the length for variable-length data types.
If the consumer is getting data and does not bind a part, the provider does not return that part. Although this is not an error, it is generally of little or no use. For example, if the consumer does not bind the status and the provider returns DB_S_ERRORSOCCURRED, the consumer must assume that the value was not returned correctly.
If the consumer is setting data and does not bind a part, the provider sends the data if it has sufficient information; otherwise it returns an error. For example, if the consumer binds the status but not the value, the provider sends the data if the status is DBSTATUS_S_ISNULL and returns an error if the status is DBSTATUS_S_OK.
The following table explains the behavior of the consumer and provider for each combination of bound parts.
Consumer/Provider behaviors for data binding
| Val | Len | Stat | Use when getting data | Use when setting data |
| α | α | α | Most commonly used combination when getting variable-length data. | Most commonly used combination when setting variable-length data. |
| α | α | – | Not generally used. If the method returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED, the consumer must assume that it didn’t successfully get or set the value for the column. If the column is nullable, the consumer cannot determine the validity of the returned value or length because it does not know if the column value is NULL. |
Not generally used. If the method returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED, the consumer must assume that it didn’t successfully get or set the value for the column. The provider assumes the status is DBSTATUS_S_OK. |
| α | – | α | Most commonly used combination when getting fixed-length data. | Most commonly used combination when setting fixed-length data. The provider assumes that string data is null terminated. See note 1. |
| α | – | – | Not generally used. If the method returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED, the consumer must assume that it didn’t successfully get or set the value for the column. If the column is nullable, the consumer cannot determine the validity of the returned value or length because it does not know if the column value is NULL. |
Not generally used. If the method returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED, the consumer must assume that it didn’t successfully get or set the value for the column. The provider assumes the status is DBSTATUS_S_OK. The provider assumes that string data is null terminated. If wType in the DBBINDING structure is a variable length DBTYPE, the provider returns a DB_E_ERRORSOCCURRED. |
| – | α | α | Not generally used. | If IColumnsInfo::GetColumnInfo does not return DBCOLUMNFLAGS_ISLONG for the column, the provider returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED. |
| – | α | – | Not generally used. If the method returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED, the consumer must assume that it didn’t successfully get or set the value for the column. If the column is nullable, the consumer cannot determine the validity of the returned value or length because it does not know if the column value is NULL.. |
Not generally used. If the method returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED, the consumer must assume that it didn’t successfully get or set the value for the column. The provider assumes the status is DBSTATUS_S_OK. |
| – | – | α | Not generally used. | Not generally used. Can be used to set the value of a column or parameter to NULL or to specify that the provider is to use the default value for an input or input/output parameter in a procedure. If the status is DBSTATUS_S_OK, the provider returns a status of DBSTATUS_E_UNAVAILABLE. |
| – | – | – | IAccessor::CreateAccessor returns DBBINDSTATUS_ BADBINDINFO for the binding. |
IAccessor::CreateAccessor returns DBBINDSTATUS_ BADBINDINFO for the binding. |
| 1If wType in the DBBINDING structure is DBTYPE_BYTES, and the status is DBSTATUS_S_OK, the provider uses the value of cbMaxLen in the DBBINDING structure as the number of bytes to read. Note that 1.x providers may return an error for this case; in order to work with 1.x providers, consumers should always include the length data part when specifying non-null values of type DBTYPE_BYTES. | ||||