AlterColumn alters the column ID and/or properties associated with a column in a table.
HRESULT AlterColumn(
DBID * pTableID,
DBID * pColumnID,
DBCOLUMNDESCFLAGS ColumnDescFlags,
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.
ColumnDescFlags
[in]
Values as described in the enumeration DBCOLUMNDESCFLAGS. 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.
| Flag | Associated Portion of DBCOLUMNDESC |
| DBCOLUMNDESCFLAG_TYPENAME | pwszTypeName |
| DBCOLUMNDESCFLAG_ITYPEINFO | ITypeInfo * |
| DBCOLUMNDESCFLAG_PROPERTIES | rgPropertySets AND cPropertySets |
| DBCOLUMNDESCFLAG_CLSID | pclsid |
| DBCOLUMNDESCFLAG_COLSIZE | ulColumnSize |
| DBCOLUMNDESCFLAG_DBCID | dbcid |
| DBCOLUMNDESCFLAG_WTYPE | wType |
| DBCOLUMNDESCFLAG_PRECISION | bPrecision |
| DBCOLUMNDESCFLAG_SCALE | bScale |
pColumnDesc
[in]
A pointer to a DBCOLUMNDESC structure defining new values for the columns. Only the values defined in ColumnDescFlags 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.
E_FAIL
A provider-specific error occurred.
E_INVALIDARG
pTableID or pColumnID was a null pointer.
pColumnDesc was a null pointer.
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 current data source.
DB_E_DUPLICATECOLUMNID
The ColumnDescFlags structure indicated that the dbcid portion of the pColumnDesc argument should be used, and the column ID specified in dbcid was the same as an existing column ID.
DB_SEC_E_PERMISSIONDENIED
The consumer did not have sufficient permission to alter the columns of this table.
DB_E_TABLEINUSE
The specified table was in use and the provider could not alter the column while the table was open.
DB_E_NOTSUPPORTED
ColumnDescFlags was an invalid value. Providers return valid values in the property DBPROP_ALTERCOLUMN.
Comments
AlterColumn applies the new properties and column ID to the existing column. The altered column preserves all properties associated with the existing column that are not explicitly changed by properties specified in *prgProperties. If pNewColumnID is null, or the same as pColumnID, then the column name is unchanged. If cPropertySets is zero, then no properties are changed. If pNewColumnID is null, or the same as pColumnID, and cPropertySets is zero, then the method makes no change to the state of the table and returns S_OK.
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 ColumnDescFlags parameter.
Calls to AlterColumn should be atomic. Failure should leave the column in the same state as before the call to the method.