Alters the ID and/or properties associated with an index.
HRESULT AlterIndex( DBID *pTableID, DBID *pIndexID, DBID *pNewIndexID, ULONG cPropertySets, DBPROPSET rgPropertySets);
[in] The DBID of the indexed base table.
[in] The DBID of the existing index to alter.
[in] The new DBID of the index. If this is the same as pIndexID or is a null pointer, the ID of the index is unchanged.
[in] The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores 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.
The method succeeded.
The index was altered but one or more properties ? for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties were not set. The method can fail to set properties for a number of reasons, including the following:
The property was not supported by the provider.
The property was not in the Index property group.
The property set was not supported by the provider.
It was not possible to set the property.
The colid in the DBPROP structure was not DB_NULLID.
The data type in vValue in the DBPROP structure was not the data type of the property or was not VT_EMPTY.
The value in vValue in the DBPROP structure was invalid.
The property's value conflicted with an existing property.
A provider-specific error occurred.
pTableID was a null pointer.
pIndexID was a null pointer.
cPropertySets was not zero, and rgPropertySets was a null pointer.
In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer.
*pIndexID or *pNewIndexID was an invalid index ID.
*pTableID was an invalid table ID.
The index specified in *pNewIndexID already exists in the data store and is not the same as pIndexID.
The index was not altered because one or more properties ? for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_REQUIRED or an invalid value ? were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties were not set. None of the satisfiable properties are remembered. The method can fail to set properties for any of the reasons specified in DB_S_ERRORSOCCURRED, except the reason that states that it was not possible to set the property.
The specified index was in use.
The index specified in *pIndexID does not exist in the data store or does not apply to the specified table.
The table specified in *pTableID does not exist in the data store.
The specified table was in use, and the provider could not modify the index with the table open.
The consumer did not have sufficient permission to alter the index.
The provider supports transactional DDL, the session is participating in a transaction, and the value of DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML.
IAlterIndex::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, the index ID is unchanged. If cPropertySets is zero, no properties are changed. If pNewIndexID is null or the same as pIndexID, and cPropertySets is zero, the method makes no change to the state of the index and returns S_OK.