MDAC 2.5 SDK - OLE DB Programmer's Reference
OLE DB Interfaces

IRowsetUpdate::GetRowStatus

Returns the status of rows.

HRESULT GetRowStatus(
   HCHAPTER          hReserved,
   ULONG             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

IRowsetUpdate::GetPendingRows