IIndexDefinition::CreateIndex

Adds a new index to a base table.

HRESULT CreateIndex(
   DBID *                                 pTableID,
   DBID *                                 pIndexID,
   ULONG                              cIndexColumnDescs,
   const DBINDEXCOLUMNDESC      rgIndexColumnDescs[],
   ULONG                              cPropertySets,
   DBPROPSET                        rgPropertySets[],
   DBID **                              ppIndexID);

Parameters

pTableID

[in]
A pointer to the DBID of the table for which to create an index.

pIndexID

[in]
A pointer to the ID of the new index to create. If this is a null pointer, the provider assigns an ID to the index. The ID must be unique.

cIndexColumnDescs

[in]
The count of DBINDEXCOLUMNSDESC structures in rgIndexColumnDescs.

rgIndexColumnDescs

[in]
An array of DBINDEXCOLUMNDESC structures that describe how to construct the index. The order of the DBINDEXCOLUMNDESC structures in rgIndexColumnDescs determines the order of the columns in the index key. That is, the column identified by the first element of this array is the most significant column in the index key and the column identified by the last element is the least significant column. When the index is opened as a rowset, the key columns occur in order of most significant column to least significant column.

typedef struct {
 DBID *    pColumnID;
 DBINDEX_COL_ORDER eIndexColOrder;
} DBINDEXCOLUMNDESC;

The elements of this structure are used as follows.

Element	Description
pColumnID	A pointer to the ID of the base table column.
eIndexColOrder	Whether the index is ascending or descending in this column. DBINDEX_COL_ORDER_ASC—Ascending DBINDEX_COL_ORDER_DESC—Descending

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 group. If the same property is specified more than once in rgPropertySets, then it is provider-specific which value is used. If cPropertySets is zero, this argument is ignored.

For information about the properties in the Index property group that are defined by OLE DB, see "Index Properties" in Appendix C. For information about the DBPROPSET and DBPROP structures, see "DBPROPSET Structure" and "DBPROP Structure" in Chapter 11.

ppIndexID

[out]
A pointer to memory in which to return a pointer to the DBID of a newly created index. If ppIndexID is a null pointer, no DBID is returned.

Return Code

S_OK
The method succeeded and the new index has been created. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK.

DB_S_ERRORSOCCURRED
The index was created 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 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.

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

E_FAIL
A provider-specific error occurred.

E_INVALIDARG
pTableID was a null pointer.

pIndexID and ppIndexID were both null pointers.

cIndexColumnDescs was zero.

rgIndexColumnDescs was a null pointer.

eIndexColOrder in an element of rgIndexColumnDescs was not a valid value.

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.

DB_E_BADCOLUMNID
A column specified in an element of rgIndexColumnDescs did not exist.

DB_E_BADINDEXID
*pIndexID was an invalid index ID.

DB_E_BADTABLEID
*pTableID was an invalid table ID.

DB_E_DUPLICATEINDEXID
The specified index already exists in the current data source object.

DB_E_ERRORSOCCURRED
No index was created 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.

DB_E_NOTABLE
The specified table does not exist in the current data source object.

DB_SEC_E_PERMISSIONDENIED
The consumer did not have sufficient permission to create the index.

Comments

If CreateIndex returns any errors, the index is not created, and ppIndexID is set to NULL on output.