IRowsetChange::DeleteRows

Deletes rows.

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

Parameters

hChapter

[in]
The chapter handle. For nonchaptered rowsets, hChapter is ignored.

cRows

[in]
The number of rows to be deleted. If cRows is zero, DeleteRows does not do anything.

rghRows

[in]
An array of handles of the rows to be deleted.

If rghRows includes a duplicate row handle, 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 statuses are returned. For information about the DBROWSTATUS enumerated type, see "Arrays of Errors" in Chapter 13.

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 source. For more information, see the DBPROP_REPORTMULTIPLECHANGES property. 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 source. 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 source. The corresponding element of rgRowStatus contains DBROWSTATUS_E_NEWLYINSERTED.
The consumer did not have sufficient permission to delete a row. This error can be returned only if the value of the DBPROP_ROWRESTRICT property is VARIANT_TRUE. 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_BADCHAPTER
The rowset was chaptered and hChapter was invalid.

The rowset was single-chaptered and the specified chapter was not the currently open chapter. The consumer must use the currently open chapter or release the currently open chapter before specifying a new chapter.

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.

Comments

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

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

If 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 source. 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 ReleaseRows, which must be called to release it.

If an error occurs while deleting a row, 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.