INFO: IRowsetResynch is Superceded by IRowsetRefresh

• Microsoft Data Access SDK, version 2.0
• Microsoft OLE DB, version 2.0
• Microsoft Data Access Components version 2.1 SP2

SUMMARY

The following information is from the Data Access Software Development Kit (SDK) version 2.0 OLREADME file:

IRowsetResynch is an interface defined in OLE DB 1.x that allows consumers to retrieve the current values for rows that may have been changed in the data store since retrieved. In OLE DB 2.0, IRowsetResynch is superceded by IRowsetRefresh, which provides better control over when data values are updated from the data store.

In future releases of OLE DB, a common service component will expose IRowsetRefresh over providers that currently expose only IRowsetResynch. In the interim, consumers can work with legacy providers that support only IRowsetResynch by directly calling that interface. This interface is documented here for those customers.

MORE INFORMATION

The following information is from the Readme.txt file:

IRowsetResynch::GetVisibleData

HRESULT GetVisibleData (
HROW hRow,
HACCESSOR hAccessor,
void * pData);

Parameters

The handle of the row for which to get the visible data.
This can be the handle of a row with a pending delete.

The handle of the accessor to use. If hAccessor is the handle of a null accessor (cBindings in IAccessor::CreateAccessor was zero), then GetVisibleData does not get any data values.

A pointer to a buffer in which to return the data. The consumer allocates memory for this buffer.

The method succeeded. The status of all columns bound by the accessor is set to DBSTATUS_S_OK, DBSTATUS_S_ISNULL, or DBSTATUS_S_TRUNCATED.

An error occurred while returning data for one or more columns, but data was successfully returned for at least one column.

A provider-specific error occurred.

pData was a null pointer and hAccessor was not a null accessor.

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

hAccessor was invalid. It is possible for a reference accessor or an accessor that has a binding that uses provider-owned memory to be invalid for use with this method, even if the accessor is valid for use with IRowset::GetData or IRowsetChange::SetData.

The specified accessor was not a row accessor.

hRow was invalid.

hRow referred to a row for which a deletion had been transmitted to the data source.

Errors occurred while returning data for all columns. To determine what errors occurred, the consumer checks the status values.

The provider was unable to retrieve the visible data due to reaching a limit on the server, such as a query execution timing out.

DBPROP_STRONGIDENTITY was VARIANT_FALSE and hRow referred to a row for which an insertion had been transmitted to the data source.

The provider called a method from IRowsetNotify in the consumer and the method has not yet returned.

The rowset was in delayed update mode and hRow referred to a pending insert row.

E_NOINTERFACE
DB_E_BADBINDINFO
DB_E_BADORDINAL
DB_E_BADSTORAGEFLAGS
DB_E_UNSUPPORTEDCONVERSION

Comments

IRowsetResynch::ResynchRows

   HRESULT ResynchRows (
      ULONG            cRows, <BR/>
      const HROW       rghRows[],<BR/>
      ULONG*           pcRowsResynched, <BR/>
      HROW**           prghRowsResynched, <BR/>
      DBROWSTATUS**    prgRowStatus); 

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

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

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, the provider sets *pcRowsResynched to zero.

A pointer to memory in which to return the array of row handles the method attempted to resynchronize. If cRows is not zero, then 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, 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 0 on output or the method fails, the provider does not allocate any memory and ensures that *prghRowsResynched is a null pointer on output.

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 the method fails, the provider does not allocate any memory and ensures that *prgRowStatus is a null pointer on output.

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.

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 source. 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 source. The row was not resynchronized and the corresponding element of *prgRowStatus contains DBROWSTATUS_E_NEWLYINSERTED.

A provider-specific error occurred.

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

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

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

The provider called a method from IRowsetNotify in the consumer and the method has not yet returned.

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

Comments

Additional query words: kbDatabase kbOLEDB kbSDKDataAc

Keywords :
Version : WINDOWS:2.0,2.1 SP2
Platform : WINDOWS
Issue type : kbinfo