IAlterIndex::AlterIndex

AlterIndex alters the ID and/or properties associated with an index.

HRESULT AlterIndex(
   DBID *   pTableID,
   DBID *   pIndexID,
   DBID *   pNewIndexID,
   ULONG   cPropertySets,
   DBPROPSET   rgPropertySet[]);

Parameters

pTableID

[in]
The DBID of the indexed base table.

pIndexID

[in]
The DBID of the existing index to alter.

pNewIndexID

[in]
The new DBID of the index. If this is the same as pIndexID, or a null pointer, then the ID of the index is unchanged.

cPropertySets

[in]
The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets.

rgPropertySets

[in/out]
An array of DBPROPSET structures containing properties and values to be set. The properties specified in these structures must belong to the index property set.

Return Code

S_OK

The method succeeded.

E_FAIL

A provider-specific error occurred.

E_INVALIDARG

pTableID was a null pointer.

pIndexID was a null pointer.

DB_E_NOTABLE

The table specified in *pTableID does not exist in the current data source.

DB_E_NOINDEX

The index specified in *pIndexID does not exist in the current data source or did not apply to the specified table.

DB_DUPLICATEINDEXID

The index specified in *pNewIndexID already exists in the current data source.

DB_SEC_E_PERMISSIONDENIED

The consumer did not have sufficient permission to alter the index.

DB_E_BADINDEXID

*pNewIndexID was an invalid index ID.

DB_E_INDEXINUSE

The specified index was in use.

DB_E_TABLEINUSE

The specified table was in use and the provider could not modify the index with the table open.

Comments

AlterIndex applies the new properties and index ID to the existing index. The altered index preserves all properties associated with the existing index that are not explicitly changed by properties specified in *prgProperties. If pNewIndexID is null, or the same as pIndexID, then the index ID is unchanged. If cPropertySets is zero, then no properties are changed. If pNewIndexID is null, or the same as pIndexID, and cPropertySets is zero, then the method makes no change to the state of the index and returns S_OK.