共用方式為

IAlterTable::AlterTable

  • 發行項

Alters the ID and/or properties associated with a table.

Syntax

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

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 is a null pointer, 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.

  • DB_S_ERRORSOCCURRED
    The table 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 Table property group.

    • The property set was not supported by the provider.

    • It was not possible to set the property.

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

  • E_FAIL
    A provider-specific error occurred.

  • E_INVALIDARG
    pTableID 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.

  • DB_E_ALTERRESTRICTED
    The provider could not alter the table because it was referenced by a constraint.

  • DB_E_BADTABLEID
    *pNewTableID was an invalid table ID.

  • DB_DUPLICATETABLEID
    The table specified in *pNewTableID already exists in the data store.

  • DB_E_ERRORSOCCURRED
    The table was not altered because one or more properties ? for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_REQUIRED or an invalid value ? could not be set. The consumer checks dwStatus in the DBPROP structures to determine which properties were not set. The method can fail to set properties for any of the reasons specified in DB_S_ERRORSOCCURRED.

  • DB_E_NOTABLE
    The table specified in *pTableID does not exist in the data store.

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

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

  • XACT_E_XTIONEXISTS
    The provider supports transactional DDL, the session is participating in a transaction, and the value of DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML.

Comments

IAlterTable::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 rgPropertySets. If pNewTableID is null or the same as pTableID, the table ID is unchanged. If cPropertySets is zero, no properties are changed. If pNewTableID is null or the same as pTableID and if cPropertySets is zero, the method makes no change to the state of the table and returns S_OK.

Calls to IAlterTable::AlterTable should be atomic. Failure should leave the table in the same state as before the call to the method.

If the table is referenced by a constraint, it is provider-specific which modifications can be made. If the provider can detect that the operation failed because of a constraint, it returns DB_E_ALTERRESTRICTED.