IAlterTable::AlterColumn
Alters the column ID and/or properties associated with a column in a table.
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 DBCOLUMNDESC structure 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.
