IRowsetUpdate::GetPendingRows

OLE DB Programmer's Reference

Returns a list of rows with pending changes.

HRESULT GetPendingRows (    HCHAPTER             hReserved,    DBPENDINGSTATUS      dwRowStatus,    DBCOUNTITEM         *pcPendingRows,    HROW               **prgPendingRows,    DBPENDINGSTATUS    **prgPendingStatus);

Parameters

hReserved

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

dwRowStatus

[in]
Indicates whether consumers want rows with pending updates, deletes, or inserts. The following DBPENDINGSTATUS values are valid and can be combined:

DBPENDINGSTATUS_NEW
DBPENDINGSTATUS_CHANGED
DBPENDINGSTATUS_DELETED

For information about the DBPENDINGSTATUS type, see "Row States in Deferred Update Mode" in Chapter 5: Updating Data in Rowsets.

pcPendingRows

[out]
A pointer to memory in which to return the number of rows with pending changes. If this is a null pointer, prgPendingRows and prgPendingStatus are ignored. This is useful when the consumer wants to check the returned return code to determine whether there are any pending changes. If an error occurs, *pcPendingRows is set to zero.

prgPendingRows

[out]
A pointer to memory in which to return an array of handles of rows with pending changes. If this is a null pointer, no row handles are returned. The rowset allocates memory for the row handles and returns the address to this memory; the consumer releases this memory with IMalloc::Free when it no longer needs the row handles. This argument is ignored if pcPendingRows is a null pointer. If *pcPendingRows is zero on output or an error occurs, the provider does not allocate any memory and ensures that *prgPendingRows is a null pointer on output.

prgPendingStatus

[out]
A pointer to memory in which to return an array of DBPENDINGSTATUS values. These values are in one-to-one correspondence with the row handles returned in *prgPendingRows and indicate the type of pending change. For information about the DBPENDINGSTATUS type, see "Row States in Deferred Update Mode" in Chapter 5: Updating Data in Rowsets. If this is a null pointer, no status information is returned.

The rowset allocates memory for the row statuses and returns the address to this memory; the consumer releases this memory with IMalloc::Free when it no longer needs the row statuses. This argument is ignored if pcPendingRows is a null pointer. If *pcPendingRows is zero on output or an error occurs, the provider does not allocate any memory and ensures that *prgPendingStatus is a null pointer on output.

Return Code

S_OK: The method succeeded, and changes were pending.
S_FALSE: The method succeeded, and no changes were pending.
E_FAIL: A provider-specific error occurred.
E_INVALIDARG: dwRowStatus was DBPENDINGSTATUS_INVALIDROW, DBPENDINGSTATUS_UNCHANGED, or any other invalid value.
E_OUTOFMEMORY: The provider was unable to allocate sufficient memory in which to return the handles of rows with pending changes or the array of DBPENDINGSTATUS values.
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.

Comments

IRowsetUpdate::GetPendingRows increments the reference of each row handle it returns in *prgPendingRows. The consumer must call IRowset::ReleaseRows for these rows. If multiple changes are made to a single row, IRowsetUpdate::GetPendingRows returns the status as follows.

If IRowsetChange::SetData is called for a pending insert row, the row is still considered a pending insert row.
If IRowsetChange::DeleteRows is called for a pending update row, the row is considered a pending delete row.
If IRowsetChange::DeleteRows is called for a pending insert row, the row is considered a transmitted delete row; such rows are not returned by IRowsetUpdate::GetPendingRows.
If IRowsetRefresh::RefreshVisibleData is called for a pending insert row, the row is still considered a pending insert row.

For a complete description of pending change states, see "Row States in Deferred Update Mode" in Chapter 5: Updating Data in Rowsets.

See Also