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


 

Chapter 6: Getting and Setting Data

This chapter 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 chapter. 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 chapter's discussion of getting and setting data.

For more information on Go to
Consumers and providers "Consumers and Providers" in Chapter 1, "Overview of OLE DB"
OLE DB objects "OLE DB Objects" in Chapter 1, "Overview of OLE DB"
Length of a data value "Length" in this chapter
Status of a data value "Status" in this chapter
Accessors "Accessors" in this chapter
Optimized accessors "Optimized Accessors" in this chapter
Reference accessors "Reference Accessors" in this chapter
DBBINDING structures "Bindings" in this chapter
Responsibility for freeing memory "Responsibility for Freeing Memory" in this chapter
Data transfer procedures "Data Transfer Procedures" in this chapter

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 Chapter 10, "Index Rowsets.")

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.