IRowsetChange::DeleteRows

  • Article

Deletes rows.

Syntax

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.

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

Reference

IRowsetUpdate::Undo

IRowsetUpdate::Update