IIndexDefinition::CreateIndex

OLE DB Programmer's Reference

Adds a new index to a base table.

HRESULT CreateIndex(    DBID                     *pTableID,    DBID                     *pIndexID,    DBORDINAL                 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, 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 Property Group" in Appendix C. For information about the DBPROPSET and DBPROP structures, see "DBPROPSET Structure" and "DBPROP Structure" in Chapter 14: Properties.

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.

Note The contents of *ppIndexID might not exactly match the passed *pIndexID. The consumer should use *ppIndexID to identify the newly created index. If ppIndexID is NULL on input and the provider cannot create an index that exactly matches *pIndexID, IIndexDefinition::CreateIndex should fail with DB_E_BADINDEXID.

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 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.

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_BADINDEXID

*pIndexID was an invalid index ID.

DB_E_DUPLICATEINDEXID

The specified index already exists in the data store.

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.

DB_E_NOCOLUMN

A column specified by *pColumnID in an element of rgIndexColumnDescs does not exist in the specified table.

DB_E_NOTABLE

The specified table does not exist in the data store.

DB_SEC_E_PERMISSIONDENIED

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

Comments

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

See Also