IAlterTable::AlterColumn

OLE DB Programmer's Reference

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.

1998-2001 Microsoft Corporation. All rights reserved.