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:
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:
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