ITableDefinition::AddColumn

Adds a new column to a base table.HRESULT AddColumn(
   DBID *                     pTableID,
   DBCOLUMNDESC *      pColumnDesc,
   DBID **                  ppColumnID);

Parameters

pTableID

[in]
A pointer to the DBID of the table to which the column is to be added.

pColumnDesc

[in/out]
A pointer to the DBCOLUMNDESC structure that describes the new column.

ppColumnID

[out]
A pointer to memory in which to return the returned DBID of newly created column. If this is a null pointer, no DBID is returned. If ppColumnID is non-null, the provider allocates memory for the DBID and overwrites *ppColumnID with a pointer to this new DBID without regard for its current value.

Return Code

S_OK
The method succeeded.

DB_S_ERRORSOCCURRED
The column was added, 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, Rowset, or Table 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 pColumnDesc was a null pointer.

DB_E_BADCOLUMNID
dbcid in *pColumnDesc was an invalid column ID.

DB_E_BADPRECISION
The precision in *pColumnDesc was invalid.

DB_E_BADSCALE
The scale in *pColumnDesc was invalid.

DB_E_BADTABLEID
*pTableID was an invalid table ID.

DB_E_BADTYPE
One or more of the wType, pwszTypeName, and pTypeInfo elements in an element of rgColumnDescs was invalid.

DB_E_DUPLICATECOLUMNID
dbcid in *pColumnDesc was the same as an existing column ID.

DB_E_ERRORSOCCURRED
The column was not added 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_NOTABLE
The specified table does not exist in the current data source.

DB_E_TABLEINUSE
The specified table was in use.

DB_SEC_E_PERMISSIONDENIED
The consumer did not have sufficient permission to add a column.

Comments

If AddColumn returns any errors, the column is not created.

The placement of the new column, whether inserted or added after the last column, is provider-specific.