IRowsetUpdate::GetPendingRows

Returns a list of rows with pending changes.

HRESULT GetPendingRows (
   HCHAPTER                  hChapter,
   DBPENDINGSTATUS      dwRowStatus,
   ULONG *                     pcPendingRows,
   HROW **                     prgPendingRows,
   DBPENDINGSTATUS **   prgPendingStatus);

Parameters

hChapter

[in]
The chapter handle. For nonchaptered rowsets, hChapter is ignored.

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 Chapter 5.

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 Chapter 5. 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 hChapter 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

GetPendingRows increments the reference of each row handle it returns in *prgPendingRows. The consumer must call ReleaseRows for these rows. If multiple changes are made to a single row, 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 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 Chapter 5.

See Also

IRowsetUpdate::GetRowStatus