Using Index Rowsets

OLE DB Programmer's Reference

Index implementations vary in their support of certain capabilities. Before an index rowset is created, consumers can determine the capabilities of the underlying index by calling IDBSchemaRowset::GetRowset for the INDEXES schema rowset. They can determine the capabilities of an index rowset to which they already have an interface pointer by calling IRowsetIndex::GetIndexInfo.

To use an index rowset, a consumer must perform the following actions:

1. Create an instance of a rowset over a base table and create an index rowset over an index on the same base table.
2. Call IColumnsInfo::GetColumnInfo on the index rowset to determine which column contains the bookmarks that point to rows in the base table column.

   The ordinal of this column is greater than zero, and the DBCOLUMNFLAGS_ISBOOKMARK flag is set on it. IColumnsInfo::GetColumnInfo also returns the key columns in the order of most significant column to least significant column. The consumer can determine which columns are the key columns by inspecting the DBINDEXCOLUMNDESC structure returned by IRowsetIndex::GetIndexInfo.

3. (Optional) Call IRowsetIndex::SetRange on the index rowset to set the range in which to search for key values in the index. If the consumer does not call SetRange, the index rowset will search the entire index.
4. Call IRowsetIndex::Seek on the index rowset to set the next fetch position to a specified key value. This key value must be in the range set in step 3, which is optional. If the consumer did not perform step 3, Seek will search the entire index.
5. Call IRowset::GetNextRows on the index rowset to get the row or rows from the index starting with the key value specified in step 4. GetNextRows is limited to the range set in step 3, which is optional. If the consumer did not perform step 3, GetNextRows can traverse the entire index.
6. Call IRowset::GetData on the index rowset for each fetched row to get the bookmarks pointing to the base table rowset.
7. Call IRowsetLocate::GetRowsByBookmark on the base table rowset to retrieve the rows in that rowset that correspond to the index rows fetched in step 5.

Because an index is a rowset, the consumer can treat it like any other rowset. Therefore, the consumer can update the index by calling IRowsetChange methods. However, the provider is not required to validate the consumer's updates to the index.

1998-2001 Microsoft Corporation. All rights reserved.