Binding Data Values
In OLE DB, a data value has three parts: value, length (for variable-length data types), and status. The consumer can bind one, two, or all three of these parts. Usually the consumer binds all three. However, there are positive and negative consequences if certain parts are bound.
If the consumer is getting data and does not bind a particular part, the provider does not return that part. Although this is not an error, the result often has a specific use, as illustrated in the table below. For example, if the consumer binds the status and length but not the value, and calls IRowset::GetData, the provider returns the length and status of the data. The consumer could use the length to allocate memory for variable-length data.
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, and calls IRowsetChange::SetData with the status set to DBSTATUS_S_ISNULL, the provider sets the data value to NULL and returns a status of DBSTATUS_S_ISNULL. But, using the same binding, if the consumer calls IRowsetChange::SetData with the status set to DBSTATUS_S_OK, the provider returns an error and sets the status to DBSTATUS_E_UNAVAILABLE, since no data value was bound.
The following table explains the behavior of the consumer and provider for each combination of bound parts.
Value |
Length |
Status |
Use when getting data |
Use when setting data |
|---|---|---|---|---|
Y |
Y |
Y |
Most commonly used combination when getting variable-length data. If the column contains a string value, the consumer should bind DBPART_LENGTH only if it intends to retrieve the string value. If the consumer does bind DBPART_LENGTH to retrieve string data, it should allocate a buffer of at least the size of a null-termination character. Providers generally return DB_E_DATAOVERFLOW when binding DBPART_VALUE for string data with a cbMaxLen value smaller than the size of a null-termination character. |
Most commonly used combination when setting variable-length data. |
Y |
Y |
N |
Not generally used. If the method returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED, the consumer must assume that the method did not 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 whether the column value is NULL. |
Not generally used. If the method returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED, the consumer must assume that the method did not successfully get or set the value for the column. The provider assumes the status is DBSTATUS_S_OK. |
Y |
N |
Y |
Most commonly used combination when getting fixed-length data.[1] |
Most commonly used combination when setting fixed-length data. The provider assumes that string data is null-terminated.[2] |
Y |
N |
N |
Not generally used. If the method returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED, the consumer must assume that it did not 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 whether 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 did not 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. |
N |
Y |
Y |
Used to get the length and status of the value (for example, to allocate memory for variable-length data) without actually retrieving the value. |
Used to specify the length of a long variable-length column prior to passing any data. This is required by providers that must know the number of bytes of BLOB data that will be sent before any data is sent. If IColumnsInfo::GetColumnInfo does not return DBCOLUMNFLAGS_ISLONG for the column, the provider returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED. |
N |
Y |
N |
Not generally used. If the method returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED, the consumer must assume that the method did not successfully get or set the length 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 whether the column value is NULL. |
Not generally used. If the method returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED, the consumer must assume that the method did not successfully get or set the value for the column. The provider assumes the status is DBSTATUS_S_OK. |
N |
N |
Y |
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. |
N |
N |
N |
IAccessor::CreateAccessor returns DBBINDSTATUS_BADBINDINFO for the binding. |
IAccessor::CreateAccessor returns DBBINDSTATUS_BADBINDINFO for the binding. |
[1] Consumers should always include the length data part when retrieving variable-length, non-null-terminated data. If the length is not bound, the provider populates the value and status with the correct values but the consumer must rely on some intimate knowledge of the data to derive its length.
[2] Consumers should always include the length data part when specifying non-null values of type DBTYPE_BYTES or DBTYPE_VARNUMERIC. If wType in the DBBINDING structure is DBTYPE_BYTES or DBTYPE_VARNUMERIC, and the status, if bound, is DBSTATUS_S_OK, providers should use the value of cbMaxLen in the DBBINDING structure as the number of bytes to read. However, consumers should not rely on this behavior, because many providers return an error for this case.
This section contains the following topics:
This topic is a part of: