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.