Share via

ITableDefinition::AddColumn

  • Article

Adds a new column to a base table.

Syntax

HRESULT AddColumn(
   DBID            *pTableID,
   DBCOLUMNDESC    *pColumnDesc,
   DBID           **ppColumnID);

Parameters

  • pTableID
    [in] A pointer to the DBID of the table to which the column is to be added.

  • pColumnDesc
    [in/out] A pointer to the DBCOLUMNDESC structure that describes the new column. For more information about the DBCOLUMNDESC structure, see ITableDefinition::CreateTable.

  • ppColumnID
    [out] A pointer to memory in which to return the returned DBID of a newly created column. If this is a null pointer, no DBID is returned. If ppColumnID is non-null, the provider allocates memory for the DBID and overwrites *ppColumnID with a pointer to this new DBID without regard for its current value.

    Note

    The contents of *ppColumnID might not exactly match the passed dbcid in *pColumnDesc. The consumer should use *ppColumnID to identify the newly created column. If ppColumnID is NULL on input and the provider cannot create a column that exactly matches dbcid in *pColumnDesc, AddColumn should fail with DB_E_BADCOLUMNID.

Return Code

  • S_OK
    The method succeeded.

  • DB_S_ERRORSOCCURRED
    The column was added, 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 colid element of the DBPROP structure for the property 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.

    • The property was not supported by the provider.

    • It was not possible to set the property.

    • The property set was not supported by the provider.

    • The property was not in the Column, Rowset, or Table property group.

  • E_FAIL
    A provider-specific error occurred.

  • E_INVALIDARG
    pTableID or pColumnDesc was a null pointer.

    cPropertySets was not zero, and rgPropertySets was a null pointer in the DBCOLUMNDESC structure.

    In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer.

  • DB_E_BADCOLUMNID
    dbcid in *pColumnDesc was an invalid column ID.

  • DB_E_BADPRECISION
    The precision in *pColumnDesc was invalid.

  • DB_E_BADSCALE
    The scale in *pColumnDesc was invalid.

  • DB_E_BADTYPE
    The wType, pwszTypeName, or pTypeInfo element, in an element of rgColumnDescs was invalid.

    In an element of rgColumnDescs, pwszTypeName was non-null and implied a DBTYPE other than the type specified by wType.

  • DB_E_DUPLICATECOLUMNID
    dbcid in *pColumnDesc was the same as an existing column ID.

  • DB_E_ERRORSOCCURRED
    The column was not added 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 specified table does not exist in the current data store.

  • DB_E_TABLEINUSE
    The specified table was in use.

  • DB_SEC_E_PERMISSIONDENIED
    The consumer did not have sufficient permission to add a column.

  • 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

If ITableDefinition::AddColumn returns any errors, the column is not created.

The placement of the new column, whether inserted or added after the last column, is provider-specific.

If the session is participating in a transaction, if DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DDL_IGNORE, and if the method succeeds, the operation is complete and is unaffected by subsequent calls to abort or commit the transaction.

If the session is participating in a transaction, if DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DDL_COMMIT, and if the method succeeds, the transaction is committed without retention. No new transaction is created. Any new work done on the session is outside the scope of a transaction. Attempting to explicitly commit or abort when there is no outstanding transaction returns an error.

See Also

Reference

IDBProperties::GetPropertyInfo

ITableDefinition::CreateTable

ITableDefinition::DropColumn