IRowSchemaChange::DeleteColumns

OLE DB Programmer's Reference

Deletes one or more named columns from a row. For row-specific columns of a row that is in immediate update mode, this is an immediate schema operation.

HRESULT DeleteColumns(    DBORDINAL    cColumns,    const DBID   rgColumnIDs[ ],    DBSTATUS     rgdwStatus[ ] );

Parameters

cColumns

[in]
Count of column names specified in the rgColumnIDs array. If cColumns is zero, no column values are deleted.

rgColumnIDs[ ]

[in]
Consumer-allocated array of cColumns names of the columns to be deleted. It is not necessary to specify columns in any particular order in the array. If cColumns is zero, rgColumnIDs is ignored. If cColumns is not zero and rgColumnIDs is a null pointer, the provider returns E_INVALIDARG. It is not an error if a column name is specified more than once.

rgdwStatus[ ]

[in/out]
Optional consumer-allocated array of cColumns status fields indicating whether the value of the corresponding element of rgColumnIDs was deleted. Consumers not interested in receiving status may set rgdwStatus to null. The status fields described in the following table apply to the deletion of column values.

Status field	Description
DBSTATUS_S_OK	Indicates that the column value was deleted.
DBROWSTATUS_S_ROWSETCOLUMN	Providers may return this status flag when asked to delete a rowset column from a row. The value is actually nulled, but the column remains in the row and rowset.
DBSTATUS_E_DOESNOTEXIST	Indicates that the column does not exist on this row.
DBSTATUS_E_PERMISSIONDENIED	The consumer did not have sufficient permission to delete the column.

The order of status elements must match the order of the column names in rgColumnIDs.

For more information, see "Status" in Chapter 6: Getting and Setting Data.

Return Code

S_OK

The provider successfully deleted values for all of the requested column names.

E_INVALIDARG

cColumns was not zero, and rgColumnIDs was a null pointer.

DB_SEC_E_PERMISSIONDENIED

The provider was unable to delete any column values because of a permission failure.

DB_S_ERRORSOCCURRED

The provider was able to delete at least one column value but was unable to delete at least one column value. The caller should examine each element of rgdwStatus to determine whether, and why, an individual column was not set.

DB_E_DELETEDROW

The row has been deleted or moved. (A delete either is pending or has been transmitted to the data store.)

DB_E_ERRORSOCCURRED

The provider was unable to delete values of any of the named columns. The caller should examine each element of rgdwStatus to determine why each individual column was not set.

DB_E_NEWLYINSERTED

DBPROP_CHANGEINSERTEDROWS on the source rowset was VARIANT_FALSE, and the method was called on a row for which the insertion has been transmitted to the data store.

E_FAIL

A provider-specific error occurred. No columns were deleted.

E_UNEXPECTED

ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state.

Comments

IRowSchemaChange::DeleteColumns deletes the columns named in the rgColumnIDs array from the row. The behavior when deleted columns also belong to a source rowset or when the row is in deferred update mode is described below. If one or more of the named columns do not exist, the provider should set the corresponding element(s) of rgdwStatus to a DBSTATUS of DBSTATUS_E_DOESNOTEXIST and return DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED as appropriate.

If a row column also belongs to the row's source rowset or if the row is in deferred update mode, IRowSchemaChange::DeleteColumns is semantically equivalent to setting the column value to null. Subsequent attempts to retrieve the column, either using an accessor on the source rowset or using IRow::GetColumns, will return the null value. Furthermore, subsequent calls to IColumnsInfo on the containing rowset (if any) or to IColumnsInfo2::GetRestrictedColumnInfo will return metadata information for this column. The provider may elect to delete a row-specific column from the row once the source rowset and row have been released and re-instantiated. If a rowset column is non-nullable, IRowSchemaChange::DeleteColumns cannot set it to null. Instead, the provider should return DBSTATUS_E_INTEGRITYVIOLATION. If the column is typed as DBTYPE_VARIANT, the provider sets the column value to VT_EMPTY.

If a row column does not belong to the row's source rowset and the row is in immediate mode, or if there is no source rowset for the row, IRowSchemaChange::DeleteColumns removes the column from the row. Subsequent attempts to retrieve the column using IRow::GetColumns or to set the column using IRowChange::SetColumns or IRowSchemaChange::AddColumns will return an error and set the corresponding status value to DBSTATUS_E_DOESNOTEXIST. Furthermore, subsequent calls to IColumnsInfo2::GetRestrictedColumnInfo will not return metadata information for this column.

IRowSchemaChange::AddColumns or IRowChange::SetColumns can also be used to set column values to null.

1998-2001 Microsoft Corporation. All rights reserved.