Bookmarks and Random Access

To enable you to move through rowsets nonsequentially, the IOM provider supports bookmarks. A bookmark is defined by OLE DB as a reference to a particular row in a data set. Though the OLE DB specification defines several types of bookmarks, the IOM provider only supports numeric self bookmarks. A self bookmark is a value returned in column zero of a row that uniquely identifies the row. The value is numeric because the bookmark value is based on the position of the row in the table, and the rowset property DBPROP_BOOKMARKTYPE is set to DBPROPVAL_BMK_NUMERIC. Once a client retrieves a row and obtains the bookmark from column zero, it may use the bookmark to return to that row throughout the life of the rowset.

Self bookmarks cannot be persisted across multiple rowset opens over the same table. In other words, there is no guarantee that a bookmark value that is returned for row N from one rowset will be the same bookmark value that is returned for row N from another rowset, even if both rowsets are opened over the same table. Client programs should not make any assumptions about the lengths or values of bookmarks of the rowset, other than the bookmark characteristics that are described by the properties that are discussed here.

Self bookmarks that are returned by the IOM provider are literal bookmarks. Clients may verify this by checking the the value of DBPROP_LITERALBOOKMARKS for VARIANT_TRUE. Two literal bookmarks may be compared as a sequence of bytes to determine if they refer to the same row. However, self bookmarks returned by the IOM provider are not ordered bookmarks. Clients will find the value of DBPROP_ORDEREDBOOKMARKS to be VARIANT_FALSE, so two bookmarks may not be compared to determine which row precedes the other in a data set.

Besides returning bookmarks, the IOM provider supports random access operations by supporting IRowsetLocate. This interface, which the IOM provider surfaces by default on its rowsets, enables a client to use bookmarks to fetch rows and to compare bookmarks. If a client program does not have the need for random access services, it may set DBPROP_IRowsetLocate to VARIANT_FALSE when it opens a rowset.

Obtaining Bookmarks

When the IOM provider opens a rowset, the property DBPROP_BOOKMARKS is by default set to VARIANT_TRUE and self bookmarks are returned. After the rowset has been opened, the client may programmatically verify that column zero does indeed contain bookmarks by calling IColumnsInfo::GetColumnInfo() and checking dwFlags for DBCOLUMNFLAGS_ISBOOKMARK. The IOM provider exposes self bookmarks as byte arrays. This means IColumnsInfo::GetColumnsInfo() will return the size of a byte array in the ulColumnSize field for column 0, and DBTYPE_BYTES as the type of column 0. To obtain bookmarks, create an accessor, binding column zero to DBTYPE_BYTES. Use this accessor when you invoke IRowset::GetData() to return rows with bookmarks.

To obtain a rowset without bookmarks, set DBPROP_BOOKMARKS to VARIANT_FALSE on IOpenRowset::OpenRowset().

Using Bookmarks

The IOM provider supports the following methods that use bookmarks.

IRowsetLocate::Compare(): compares two bookmarks.

IRowsetLocate::GetRowsAt(): uses a bookmark as a place to start retrieving rows from.

IRowsetLocate::GetRowsByBookmark(): uses bookmarks to retrieve specific rows.