OLE DB Programmer's Reference |
Sets the current index on the rowset.
HRESULT SetIndex ( DBID *pIndexID);
Parameters
Return Code
Comments
IRowsetCurrentIndex::SetIndex sets the current index used by IRowsetIndex in navigating the indexed rowset.
Providers may require that all existing row handles be released prior to successfully processing a call to IRowsetCurrentIndex::SetIndex.
If IRowsetCurrentIndex::SetIndex returns DB_S_COLUMNSCHANGED and the consumer subsequently calls methods in IColumnsInfo or IColumnsRowset, these methods must reflect the new metadata. Existing rowset accessors are not updated to reflect the new metadata. That is, IAccessor::GetBindings returns exactly the same information it would have returned before IRowsetCurrentIndex::SetIndex was called. If such accessors are subsequently used, such as in a call to IRowset::GetData, the provider must revalidate them. If none of the columns bound by the accessor have changed, the accessor can be used successfully. If any of the columns have changed, the appropriate error or warning is returned.
It may not be possible for a provider to change to a new index in all cases. For example, if the provider is currently exposing a clustered index as an integrated index rowset, changing to a nonclustered index might not be possible because it does not contain the same set of columns. In this case, the consumer can close the existing rowset and open a new rowset, specifying the desired index.
If IRowsetCurrentIndex::SetIndex returns DB_S_COLUMNSCHANGED and the consumer subsequently calls methods in IColumnsInfo or IColumnsRowset, these methods must reflect the new metadata. Existing rowset accessors are not updated to reflect the new metadata. That is, IAccessor::GetBindings returns exactly the same information it would have returned before IRowsetCurrentIndex::SetIndex was called. If such accessors are subsequently used, such as in a call to IRowset::GetData, the provider must revalidate them. If none of the columns bound by the accessor have changed, the accessor can be used successfully. If any of the columns have changed, the appropriate error or warning is returned.
Changing the index of a rowset may affect the ordering of chapters generated from that rowset that do not have explicit sort orders defined. However, if the chapter has been specified with an explicit sort order, that sort order survives changing of the root rowset's index.
1998-2001 Microsoft Corporation. All rights reserved.