IAlterTable::AlterColumn

  • Article

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

Syntax

HRESULT AlterColumn(
   DBID               *pTableID,
   DBID               *pColumnID,
   DBCOLUMNDESCFLAGS   dwColumnDescFlags,
   DBCOLUMNDESC       *pColumnDesc);

Parameters

  • pTableID
    [in] The DBID of the base table containing the column to alter.

  • pColumnID
    [in] The current DBID of the column to alter.

  • dwColumnDescFlags
    [in] Values as described in the enumeration DBCOLUMNDESCFLAGS. As illustrated in the following table, these bits define which portions of the DBCOLUMNDESC structure defined in pColumnDesc should be used when altering the column. A provider returns values it supports in the DBPROP_ALTERCOLUMN property. For more information about this field, please see the Comments section.

    DBCOLUMNDESCFLAGS values

    Associated portion of DBCOLUMNDESC

    DBCOLUMNDESCFLAGS_TYPENAME

    pwszTypeName

    DBCOLUMNDESCFLAGS_ITYPEINFO

    ITypeInfo *

    DBCOLUMNDESCFLAGS_PROPERTIES

    rgPropertySets AND cPropertySets

    DBCOLUMNDESCFLAGS_CLSID

    pclsid

    DBCOLUMNDESCFLAGS_COLSIZE

    ulColumnSize

    DBCOLUMNDESCFLAGS_DBCID

    dbcid

    DBCOLUMNDESCFLAGS_WTYPE

    wType

    DBCOLUMNDESCFLAGS_PRECISION

    bPrecision

    DBCOLUMNDESCFLAGS_SCALE

    bScale

  • pColumnDesc
    [in] A pointer to a DBCOLUMNDESCstructure defining new values for the columns. Only the values defined in dwColumnDescFlags are used ? the provider ignores other fields in the structure. For a description of the DBCOLUMNDESC structure, please refer to ITableDefinition::CreateTable.

Return Code

  • S_OK
    The method succeeded.

  • DB_S_ERRORSOCCURRED
    The column 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 Column 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 or pColumnID was a null pointer.

    pColumnDesc was a null pointer.

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

  • DB_E_BADCOLUMNID
    The dbcid member of *pColumnDesc was invalid.

  • DB_E_BADPRECISION
    The bPrecision member of *pColumnDesc was invalid.

  • DB_E_BADSCALE
    The bScale member of *pColumnDesc was invalid.

  • DB_E_BADTYPE
    One or more of the wType, pwszTypeName, or *pTypeInfo members of *pColumnDesc was invalid, or the provider was unable to change the existing column type to the new column type.

  • DB_E_DUPLICATECOLUMNID
    The column ID specified in the dbcid member of *pColumnDesc was the same as an existing column ID.

  • DB_E_ERRORSOCCURRED
    The column 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_NOCOLUMN
    The column specified in *pColumnID does not exist in the specified table.

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

  • DB_E_NOTSUPPORTED
    dwColumnDescFlags was an invalid value. Providers return valid values in the property DBPROP_ALTERCOLUMN.

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

  • DB_SEC_E_PERMISSIONDENIED
    The consumer did not have sufficient permission to alter the columns of this table.

Comments

IAlterTable::AlterColumn changes the column ID, selected column metadata (such as type, column size, precision, and scale) or OLE DB column properties. The altered column preserves all properties associated with the existing column that are not explicitly changed by properties specified in the *rgPropertySets member of the DBCOLUMNDESC structure pointed to by *pColumnDesc. If DBCOLUMNDESCFLAGS_DBCID is not set, or if it is the same as *pColumnID, the column ID is not changed. If cPropertySets is zero, no properties are changed. The method will be non-operational but will return S_OK if any one of the following conditions is satisfied:

  • if none of the DBCOLUMNDESCFLAGS bits are set

  • if only DBCOLUMNDESCFLAGS_PROPERTIES is set but cPropertySets is zero

  • if only DBCOLUMNDESCFLAGS_DBCID is set but the new column ID (dbcid) is the same as the old one

Providers may also return any of the return codes listed in ITableDefinition::CreateTable or ITableDefinition::AddColumn associated with errors in the DBCOLUMNDESC structure (for example, DB_E_BADCOLUMNID). However, the provider should not evaluate portions of the structure that are not explicitly listed in the dwColumnDescFlags parameter.

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

If the column 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.