IRowset::AddRefRows

OLE DB Programmer's Reference

Adds a reference count to an existing row handle.

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

IRowset::ReleaseRows

1998-2001 Microsoft Corporation. All rights reserved.



Microsoft Ole Db 2.0 Programmer's Reference and Data Access SDK
Microsoft OLE DB 2.0 Programmers Reference and Data Access SDK (Microsoft Professional Editions)
ISBN: 0735605904
EAN: 2147483647
Year: 1998
Pages: 1083

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net