IRowset::AddRefRows

  • Article

Adds a reference count to an existing row handle.

Syntax

HRESULT AddRefRows(
   DBCOUNTITEM   cRows,
   const HROW    rghRows[],
   DBREFCOUNT    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

Reference

IRowset::ReleaseRows