IRowsetResynch::ResynchRows | Microsoft OLE DB 2.0 Programmers Reference and Data Access SDK (Microsoft Professional Editions)

OLE DB Programmer's Reference

Gets the data in the data store that is visible to the transaction for the specified rows and updates the rowset's copies of those rows.

HRESULT ResynchRows (    DBCOUNTITEM      cRows,    const HROW       rghRows[],    DBCOUNTITEM     *pcRowsResynched,    HROW           **prghRowsResynched,    DBROWSTATUS    **prgRowStatus);

Parameters

cRows

[in]
The count of rows to resynchronize. If cRows is zero, IRowsetResynch::ResynchRows ignores rghRows and reads the current value of all active rows.

rghRows

[in]
An array of cRows row handles to be resynchronized. If cRows is zero, this argument is ignored.

pcRowsResynched

[out]
A pointer to memory in which to return the number of rows the method attempted to resynchronize. The caller may supply a null pointer if no list is desired. If the method fails with an error other than DB_E_ERRORSOCCURRED, the provider sets *pcRowsResynched to zero.

prghRowsResynched

[out]
A pointer to memory in which to return the array of row handles the method attempted to resynchronize. If cRows is not zero, the elements of this array are in one-to-one correspondence with those of rghRows. If cRows is zero, the elements of this array are the handles of all active rows in the rowset. When cRows is zero, IRowsetResynch::ResynchRows will add to the reference count of the rows whose handles are returned in prghRowsResynched.

The rowset allocates memory for the handles and the client should release this memory with IMalloc::Free when no longer needed. This argument is ignored if pcRowsResynched is a null pointer and must not be a null pointer otherwise. If *pcRowsResynched is zero on output or the method fails, the provider does not allocate any memory and ensures that *prghRowsResynched is a null pointer on output.

If pcRowsResynched is a null pointer, prghRowsResynched and prgRowStatus are ignored.

If pcRowsResynched is not a null pointer and if *pcRowsResynched is zero on output or the method fails, the provider does not allocate any memory and ensures that *prghRowsResynched and *prgRowStatus are null pointers on output.

prgRowStatus

[out]
A pointer to memory in which to return an array of row status values. The elements of this array correspond one-to-one with the elements of *prghRowsResynched. If no errors occur while resynchronizing a row, the corresponding element of *prgRowStatus is set to DBROWSTATUS_S_OK. If the method fails while resynchronizing a row, the corresponding element is set as specified in DB_S_ERRORSOCCURRED. If prgRowStatus is a null pointer, no row status values are returned.

The rowset allocates memory for the row status values and returns the address to this memory; the client releases this memory with IMalloc::Free when it is no longer needed. This argument is ignored if pcRowsResynched is a null pointer. If *pcRowsResynched is zero on output or if the method fails with an error other than DB_E_ERRORSOCCURRED, the provider does not allocate any memory and ensures that *prgRowStatus is a null pointer on output.

If pcRowsResynched is a null pointer, prghRowsResynched and prgRowStatus are ignored.

Return Code

S_OK

The method succeeded. All rows were successfully resynchronized. The following value can be returned in *prgRowStatus:

The row was successfully resynchronized. The corresponding element of *prgRowStatus contains DBROWSTATUS_S_OK.

DB_S_ERRORSOCCURRED

An error occurred while resynchronizing a row, but at least one row was successfully resynchronized. Successes can occur for the reason listed under S_OK. The following errors can occur:

An element of rghRows was invalid or referred to a row that this thread does not have access to. The corresponding element of *prgRowStatus contains DBROWSTATUS_E_INVALID.
Resynchronizing a row was canceled during notification. The row was not resynchronized, and the corresponding element of *prgRowStatus contains DBROWSTATUS_E_CANCELED.
An element of rghRows referred to a row for which a deletion had been transmitted to the data store. The corresponding element of *prgRowStatus contains DBROWSTATUS_E_DELETED.
The row was not resynchronized due to reaching a limit on the server, such as a query execution timing out. The error in the corresponding element of *prgRowStatus contains DBROWSTATUS_E_LIMITREACHED.
An element of rghRows referred to a row on which a storage object was open. The corresponding element of *prgRowStatus contains DBROWSTATUS_E_OBJECTOPEN.
An element of rghRows referred to a pending insert row. The corresponding element of *prgRowStatus contains DBROWSTATUS_E_PENDINGINSERT.
DBPROP_STRONGIDENTITY was VARIANT_FALSE, and an element of rghRows referred to a row for which an insertion had been transmitted to the data store. The row was not resynchronized, and the corresponding element of *prgRowStatus contains DBROWSTATUS_E_NEWLYINSERTED.

E_FAIL

A provider-specific error occurred.

E_INVALIDARG

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

E_UNEXPECTED

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

DB_E_ERRORSOCCURRED

Errors occurred while resynchronizing all of the rows. Errors can occur for the reasons listed under DB_S_ERRORSOCCURRED.

DB_E_NOTREENTRANT

The provider called a method from IRowsetNotify in the consumer that had not yet returned, and the provider does not support reentrancy in this method.

DB_SEC_E_PERMISSIONDENIED

The consumer did not have sufficient permission to resynchronize the rows.

Comments

IRowsetResynch::ResynchRows refreshes the values in the rowset's copy of each of the specified rows with the currently visible contents of the underlying row. Changes made to the row by the current transaction are always visible to IRowsetResynch::ResynchRows, including changes made by other rowsets in the same transaction. Whether changes made by other transactions are visible to IRowsetResynch::ResynchRows depends on the isolation level of the current transaction.

If a specified row has been deleted from the data store and this deletion is visible, IRowsetResynch::ResynchRows returns DBROWSTATUS_E_DELETED in the error status array for the row and the row is treated as a deleted row.

Any changes transmitted to the data store are not lost; they will be committed or aborted when the transaction is committed or aborted. All pending changes are lost because they exist only in the rowset's copy of the row and IRowsetResynch::ResynchRows overwrites the contents of this copy. The pending change status is removed from the row.