Rows and Row Handles

OLE DB Programmer's Reference

Conceptually, a rowset is a set of rows. A row is a set of related data items, or columns, that are treated as a unit. In OLE DB, each row in a rowset object is stored in a separately allocated data buffer that the provider maintains on behalf of the consumer. Thus a rowset's row data, stored in these row buffers, is external to the rowset object, which contains a set of handles to the row buffers. These handles are called row handles.

Row handles are of type HROW, which is defined as follows:

typedef ULONG_PTR HROW;

The consumer can use row handles to manage the activity of individual rows or sets of rows in a rowset. A rowset may have a limit on the number of open row handles it can hold. This limit is imposed by the rowset's DBPROP_MAXOPENROWS property.

When a consumer fetches a row, the data for the row appears to be cached in the provider and left there until the row is released. The consumer accesses the data in the row through the functions IRowset::GetData and IRowsetChange::SetData, which use accessor objects to define how the data is to be transferred. For more information, see "Accessors" in Chapter 6: Getting and Setting Data.

By having a local copy of the row, multiple consumers can get data from the row without making additional trips to the data store, which might reside on a separate server. Consumers can also coordinate changes to the row without transmitting them to the data store until all consumers are ready.

However, caching rows in the provider means that it is costly to keep materialized row handles—those defined by creating an instance. Although a particular provider might not enforce a preset limit on the number of active row handles, keeping even a few hundred row handles deteriorates provider performance. Some providers might be expected to handle rowsets with millions of rows, but no provider is expected to materialize many rows simultaneously. Consumers are therefore encouraged to release row handles whenever possible and keep bookmarks to these rows if it is necessary to refetch them. Consumers can keep a small number of frequently accessed row handles in materialized form.

1998-2001 Microsoft Corporation. All rights reserved.