Bindings
An accessor is a collection of bindings. Each binding contains information about the consumer's buffer. The most notable information is the ordinal of the column or parameter to which the binding applies, what is bound (the data value, its length, and its status), the offsets in the buffer to each of these parts, and the length and type of the data value as it exists in the consumer's buffer. For more information, see Binding Data Values and DBBINDING Structures.
Each binding associates, or binds, a single column or parameter to the consumer's buffer. The consumer can bind columns and output parameters more than once in a single accessor but can bind input parameters only once in a single accessor. It is usually a consumer programming error to bind a column more than once in a single accessor and then use that accessor to set the value of the column, such as with IRowsetChange::SetData, because the result of doing so is unpredictable.
For example, the following illustration shows a consumer's buffer containing 10 bytes for a string, 2 unused bytes to properly align the string's status and length values, 4 bytes for the string's status, 4 bytes for the string's length, 2 unused bytes to properly align the integer's status value, 2 bytes for a 2-byte integer, and 4 bytes for the integer's status. It also shows the main binding information used to bind the string to column 1 and the integer to column 2. The table following the illustration summarizes the bindings in this example.
Main Binding Information in a Consumer's Buffer
.gif "binding information in consumer buffer")
Element |
String binding |
Integer binding |
|---|---|---|
Ordinal |
1 |
2 |
Bound parts |
DBPART_VALUE | DBPART_LENGTH | DBPART_STATUS |
DBPART_VALUE | DBPART_STATUS |
Offset to data value |
0 |
22 |
Offset to status |
12 |
24 |
Offset to length |
16 |
N/A |
Data type |
DBTYPE_STR |
DBTYPE_I2 |
Buffer length |
10 |
2 |
When the consumer gets data, the provider uses the information in each binding to determine where and how to return data in the consumer's buffer. When the consumer sets data, the provider uses the information in each binding to determine where and how to retrieve data from the consumer's buffer.
Note
The memory of a dbBindings structure should be initialized prior to setting any values. Use the syntax memset(rgBindings, 0, cColumns * sizeof(DBBINDING));, to perform this action. The syntax usage is shown in the example Binding and Accessor Example.
This topic is a part of: