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. For information about the DBROWSTATUS enumerated type, see "Arrays of Errors" in Chapter 13.

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

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 AddRefRows while it is processing a method in IRowsetNotify. That is, the rowset must be reentrant through AddRefRows during notification.

If 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