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

IRowset::AddRefRows

Adds a reference count to an existing row handle.

HRESULT AddRefRows(
   ULONG         cRows,
   const HROW    rghRows[],
   ULONG         rgRefCounts[],
   DBROWSTATUS   rgRowStatus[]);

Parameters

cRows

[in]
The number of rows for which to increment the reference count.

rghRows

[in]
An array of row handles for which to increment the reference count. The reference count of row handles is incremented by one for each time they appear in the array.

rgRefCounts

[out]
An array with cRows elements in which to return the new reference count for each row handle. The consumer allocates memory for this array. If rgRefCounts is a null pointer, no reference counts are returned.

rgRowStatus

[out]
An array with cRows elements in which to return values indicating the status of each row specified in rghRows. If no errors occur while incrementing the reference count of a row, the corresponding element of rgRowStatus is set to DBROWSTATUS_S_OK. If an error occurs while incrementing the reference count of a row, the corresponding element is set as specified in DB_S_ERRORSOCCURRED. The consumer allocates memory for this array. If rgRowStatus is a null pointer, no row statuses are returned.

Return Code

S_OK

The method succeeded. The reference count of all rows was successfully incremented. The following value can be returned in *prgRowStatus:

The reference count of the row was successfully incremented. The corresponding element of *prgRowStatus contains DBROWSTATUS_S_OK.

DB_S_ERRORSOCCURRED

An error occurred while incrementing the reference count of a row, but the reference count of at least one row was incremented. Successes can occur for the reason listed under S_OK. The following errors can occur:

• A row handle was invalid. The reference count of the row was not incremented, and the corresponding element of rgRowStatus contains DBROWSTATUS_E_INVALID.
  
  
• A row handle referred to a row that had a reference count of zero. The reference count of the row was not incremented, and the corresponding element of rgRowStatus contains DBROWSTATUS_E_INVALID.
  
  
• A row handle referred to a row for which a deletion had been transmitted to the data store. The reference count of the row was not incremented, and the corresponding element of rgRowStatus contains DBROWSTATUS_E_DELETED.
  
  
• The consumer encountered a recoverable, provider-specific error, such as an RPC failure when transmitting the change to a remote server. The corresponding element of rgRowStatus contains DBROWSTATUS_E_FAIL.

E_FAIL

A provider-specific error occurred.

E_INVALIDARG

rghRows was a null pointer, and cRows was not zero.

E_UNEXPECTED

ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state.

DB_E_ERRORSOCCURRED

Errors occurred while incrementing the reference count of all of the rows. Errors can occur for the reasons listed under DB_S_ERRORSOCCURRED.

Comments

IRowset::AddRefRows must be supported for implementing multiple references to the same row even if the rowset does not support IRowsetIdentity.

It is always possible for a consumer to call IRowset::AddRefRows while it is processing a method in IRowsetNotify. That is, the rowset must be reentrant through IRowset::AddRefRows during notification.

If IRowset::AddRefRows encounters an error while incrementing the reference count of a row, it sets the corresponding element in rgRowStatus to the appropriate DBROWSTATUS value and continues processing.

If a row handle is duplicated in rghRows, the corresponding row will have its reference count incremented by 1 for each time it appears in the array.

See Also

IRowset::ReleaseRows