Getting and Setting Data (OLE DB)

This section discusses how data is transferred between OLE DB consumers and providers and introduces the three parts of data ? value, length of the value, and status of the value. An accessor is a collection of information that describes how data is stored in the consumer's buffer. A special type, the reference accessor, is also discussed in this section. Defined another way, an accessor is a collection of bindings, and each binding associates a single column or parameter to the consumer's buffer. DBBINDING structures, memory management, and data transfer complete this section's discussion of getting and setting data.

Data refers collectively to parameter data and rowset data. Parameter data is the data used for parameters in commands. For example, in the text command SELECT * FROM MyTable WHERE Name = ?, the question mark represents a parameter and the consumer sends data for this parameter to the provider when the consumer executes the command. Rowset data is the data returned in a rowset ? for example, the rowset generated by executing the command (such as the SELECT * statement in this paragraph) and the key column values passed to an index rowset when setting the index range or searching for a key value. For more information on index rowsets, see Index Rowsets (OLE DB).

Data is stored in both the consumer and the provider. The consumer stores data in a buffer. A binding associates, or binds, a single column or parameter in the data store to a column in the consumer's buffer. A group of bindings is gathered together in an accessor. When transferring data, the consumer passes the provider a handle to the accessor and a pointer to the consumer's data buffer. In the provider, how a rowset's row data is handled is provider-specific. For example, row data can be cached in a set of row buffers belonging to the rowset, or it may be passed directly to and from the data store.

The provider transfers the data from consumer to provider and provider to consumer. Getting data is defined as transferring data from the provider to the consumer, as when getting rowset data with IRowset::GetData or getting output parameter data with ICommand::Execute. Setting data is defined as transferring data from the consumer to the provider, as when setting rowset data with IRowsetChange::SetData, key values with IRowsetIndex::SetRange, or input parameter data with ICommand::Execute.

This section contains the following topics:

• Binding Data Values

• Accessors

• Bindings

• DBBINDING Structures

• Binding and Accessor Example

• Responsibility for Freeing Memory

• Data Transfer Procedures