MDAC 2.5 SDK - OLE DB Programmer's Reference
OLE DB Interfaces

IAlterTable::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
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 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.

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 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_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_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_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_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

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 ColumnDescFlags parameter.

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