IAlterTable::AlterTable

AlterTable alters the ID and/or properties associated with a table.

HRESULT AlterTable(
   DBID *   pTableID,
   DBID *   pNewTableID,
   ULONG   cPropertySets,
   DBPROPSET   rgPropertySet[]);

Parameters

pTableID

[in]
The DBID of the base table to alter.

pNewTableID

[in]
The new DBID of the base table. If this is the same as pTableID, or a null pointer, then the ID of the table 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 table property set.

Return Code

S_OK

The method succeeded.

E_FAIL

A provider-specific error occurred.

E_INVALIDARG

pTableID was a null pointer.

DB_E_BADTABLEID

*pTableID was an invalid table ID.

DB_E_NOTABLE

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

DB_DUPLICATETABLEID

The table specified in *pNewTableID already exists in the current data source.

DB_SEC_E_PERMISSIONDENIED

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

DB_E_TABLEINUSE

The specified table was in use and the provider could not alter the table while it was open.

Comments

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