IRowsetChange::DeleteRows

OLE DB Programmer's Reference

Deletes rows.

HRESULT DeleteRows (    HCHAPTER      hChapter,    DBCOUNTITEM   cRows,    const HROW    rghRows[],    DBROWSTATUS   rgRowStatus[]);

Parameters

hChapter: [in]
The chapter handle. Providers are allowed to ignore this argument. For maximum interoperability, consumers should set hChapter to DB_NULL_HCHAPTER.
cRows: [in]
The number of rows to be deleted. If cRows is zero, IRowsetChange::DeleteRows does not do anything.
rghRows: [in]
An array of handles of the rows to be deleted.
If rghRows includes a duplicate row handle, IRowsetChange::DeleteRows behaves as follows. If the row handle is valid, it is provider-specific whether the returned row status information for each row or a single instance of the row is set to DBROWSTATUS_S_OK. If the row handle is invalid, the row status information for each occurrence of the row contains the appropriate error.
rgRowStatus: [out]
An array with cRows elements in which to return values indicating the status of each row specified in rghRows. If no errors or warnings occur while deleting a row, the corresponding element of rgRowStatus is set to DBROWSTATUS_S_OK. If a warning occurs while deleting a row, the corresponding element is set as specified in S_OK. If an error occurs while deleting a row, the corresponding element is set as specified in DB_S_ERRORSOCCURRED. The consumer allocates memory for this array. If rgRowStatus is a null pointer, no row status information is returned.

Return Code

S_OK

The method succeeded. All rows were successfully deleted. The following values can be returned in rgRowStatus:

The row was successfully deleted, and no warning conditions occurred. The corresponding element of rgRowStatus contains DBROWSTATUS_S_OK.
The rowset was in immediate update mode, and deleting a single row caused more than one row to be deleted in the data store. For more information, see the DBPROP_REPORTMULTIPLECHANGES property in Appendix C. The corresponding element of rgRowStatus contains DBROWSTATUS_S_MULTIPLECHANGES.

DB_S_ERRORSOCCURRED

An error occurred while deleting a row, but at least one row was successfully deleted. Successes and warnings can occur for the reasons listed under S_OK. The following errors can occur:

An element of rghRows was invalid or was a row handle to which the current thread does not have access rights. The corresponding element of rgRowStatus contains DBROWSTATUS_E_INVALID.
Deletion of a row was canceled during notification. The row was not deleted and the corresponding element of rgRowStatus contains DBROWSTATUS_E_CANCELED.
An element of rghRows referred to a row with a pending delete or for which a deletion had been transmitted to the data store. The corresponding element of rgRowStatus contains DBROWSTATUS_E_DELETED.
Deleting a row referred to by an element of rghRows violated the integrity constraints for the column or table. The corresponding element of rgRowStatus contains DBROWSTATUS_E_INTEGRITYVIOLATION.
The rowset was in immediate update mode, and the row was not deleted due to reaching a limit on the server, such as a query execution timing out. The error in the corresponding element of rgRowStatus contains DBROWSTATUS_E_LIMITREACHED.
Deleting a row would exceed the limit for pending changes specified by the rowset property DBPROP_MAXPENDINGROWS. The corresponding element of rgRowStatus contains DBROWSTATUS_E_MAXPENDCHANGESEXCEEDED.
DBPROP_CHANGEINSERTEDROWS was VARIANT_FALSE, and an element of rghRows referred to a row for which the insertion has been transmitted to the data store. The corresponding element of rgRowStatus contains DBROWSTATUS_E_NEWLYINSERTED.
The consumer did not have sufficient permission to delete a row. The corresponding element of rgRowStatus contains DBROWSTATUS_E_PERMISSIONDENIED. If the rowset is in delayed update mode, this error might not be returned until IRowsetUpdate::Update is called.
The consumer encountered a recoverable, provider-specific error, such as an RPC failure when transmitting the change to a remote server. The corresponding element of rgRowStatus contains DBROWSTATUS_E_FAIL.

E_FAIL

A provider-specific error occurred.

E_INVALIDARG

rghRows was a null pointer, and cRows was greater than or equal to one.

E_UNEXPECTED

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

DB_E_ABORTLIMITREACHED

The rowset was in immediate update mode, and the row was not deleted due to reaching a limit on the server, such as a query execution timing out.

DB_E_ERRORSOCCURRED

Errors occurred while deleting all of the rows. Errors can occur for the reasons listed under DB_S_ERRORSOCCURRED.

DB_E_NOTREENTRANT

The consumer called this method while it was processing a notification, and it is an error to call this method while processing the specified DBREASON value.

DB_E_NOTSUPPORTED

The provider does not support this method, or the corresponding bit of DBPROP_UPDATABILITY is not set.

Note The spec, as of 2.1, does not require this return code if the corresponding bit is not set.

Comments

In delayed update mode, IRowsetChange::DeleteRows marks rows for deletion rather than actually deleting them. Rows with pending deletes cannot be used in any methods except IRowsetRefresh::GetLastVisibleData, IRowsetRefresh::RefreshVisibleData, IRowsetUpdate::Undo, IRowsetUpdate::Update, IRowsetUpdate::GetOriginalData, IRowsetUpdate::GetRowStatus, IRowsetUpdate::GetPendingRows, IRowset::ReleaseRows, and IRowsetIdentity::IsSameRow. The deletion is not transmitted to the data store until IRowsetUpdate::Update is called. In immediate update mode, IRowsetChange::DeleteRows transmits deletions to the data store immediately. For more information, see "Changing Data" in Chapter 5: Updating Data in Rowsets.

After a deletion has been transmitted to the data store, it cannot be undone. The row cannot be used with any method except IRowset::ReleaseRows. Neither IRowsetChange::DeleteRows nor IRowsetUpdate::Update releases rows after transmitting deletions to the data store. The consumer must release the row with IRowset::ReleaseRows.

If IRowsetChange::DeleteRows is called for a row with a pending insert, the row is placed in the same state as a row for which a deletion has been transmitted to the data store. That is, if a row is inserted and then deleted in delayed update mode, the deletion cannot be undone. The row cannot be used with any method except IRowset::ReleaseRows, which must be called to release it.

If an error occurs while deleting a row, IRowsetChange::DeleteRows continues deleting the other rows in rghRows and returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED. It returns status information about each row in rgRowStatus.

If the DBPROP_ROWRESTRICT property is VARIANT_TRUE, the consumer may have permission to delete some rows but not other rows.

See Also