IRowsetCurrentIndex::SetIndex

Sets the current index on the rowset.

Syntax

HRESULT SetIndex (
   DBID      *pIndexID);

Parameters

• pIndexID
  [in] The DBID of the current index on the rowset.

Return Code

• S_OK
  The method succeeded.

• DB_S_COLUMNSCHANGED
  The metadata for the rowset changed based on the index selected. The provider had to reexecute the command for the newly selected index, and the order of the columns changed.

• E_INVALIDARG
  pIndexID was a null pointer.

• DB_E_BADINDEXID
  *pIndexID was an invalid index ID.

• DB_E_ROWSNOTRELEASED
  The provider requires release of existing rows before changing the index because the rowset will be regenerated. This may be required even if the provider supports a value of VARIANT_TRUE for DBPROP_CANHOLDROWS. For more information, see DBPROP_CANHOLDROWS in Appendix C.

• DB_E_NOINDEX
  The index specified in pIndexID did not exist.

• E_FAIL
  A provider-specific error occurred.

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.