IRowsetUpdate::GetRowStatus

  • Article

Returns the status of rows.

Syntax

HRESULT GetRowStatus(
   HCHAPTER          hReserved,
   DBCOUNTITEM       cRows,
   const HROW        rghRows[],
   DBPENDINGSTATUS   rgPendingStatus[]);

Parameters

  • hReserved
    [in] Reserved for future use. Must be DB_NULL_HCHAPTER.

  • cRows
    [in] The count of elements in rghRows and rgPendingStatus. If this value is zero, IRowsetUpdate::GetRowStatus ignores rghRows and rgPendingStatus and does not return any status.

  • rghRows
    [in] An array of handles of rows for which to return the status. This array is allocated by the consumer and must not be freed by the provider.

  • rgPendingStatus
    [out] An array of DBPENDINGSTATUS values. IRowsetUpdate::GetRowStatus returns the DBPENDINGSTATUS values for all rows specified in the rghRows array. The DBPENDINGSTATUS_INVALIDROW value is used to indicate an invalid row handle. For information about the DBPENDINGSTATUS type, see Row States in Deferred Update Mode.

    The rgPendingStatus array is allocated, but not necessarily initialized, by the caller and must not be freed by the provider.

Return Code

  • S_OK
    The method succeeded. Status values were successfully retrieved for all rows, and each element of rgPendingStatus is set to DBPENDINGSTATUS_NEW, DBPENDINGSTATUS_CHANGED, DBPENDINGSTATUS_DELETED, or DBPENDINGSTATUS_UNCHANGED.

  • DB_S_ERRORSOCCURRED
    An error occurred while getting the status of a row, but the status of at least one row was successfully retrieved. Successes can occur for the reasons listed under S_OK. The following error can occur:

    A row handle in rghRows was invalid. The corresponding element of rgRowStatus contains DBPENDINGSTATUS_INVALIDROW.

  • E_FAIL
    A provider-specific error occurred.

  • E_INVALIDARG
    cRows was greater than zero, and either rghRows was a null pointer or rgPendingStatus was a null pointer.

  • 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 hReserved 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 getting the status of all of the rows. Errors can occur for the reason listed under DB_S_ERRORSOCCURRED.

Comments

If multiple changes are made to a single row, IRowsetUpdate::GetRowStatus returns the status as described in IRowsetUpdate::GetPendingRows. If IRowsetChange::DeleteRows is called for a pending insert row, a status of DBPENDINGSTATUS_INVALIDROW is returned for the row.

For a complete description of row states, see Row States in Deferred Update Mode.

See Also

Reference

IRowsetUpdate::GetPendingRows