IRowsetUpdate::GetRowStatus

OLE DB Programmer's Reference

Returns the status of rows.

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" in Chapter 5: Updating Data in Rowsets.
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" in Chapter 5: Updating Data in Rowsets.

See Also