IRowsetUpdate::GetPendingRows

  • Article

Returns a list of rows with pending changes.

Syntax

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.

  • 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. 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.

See Also

Reference

IRowsetUpdate::GetRowStatus