IRowsetRefresh::GetLastVisibleData

Gets the most recent data either from the provider-implemented data cache that is visible to the transaction or from the data store.

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

Parameters

hRow: [in]
The handle of the row with pending changes for which to get the latest data. This can be the handle of a row with a pending delete.
hAccessor: [in]
The handle of the accessor to use. If hAccessor is the handle of a null accessor (cBindings in IAccessor::CreateAccessor was zero), IRowsetRefresh::GetLastVisibleData does not get any data values.
pData: [out]
A pointer to a buffer in which to return the data. The consumer allocates memory for this buffer.

Return Code

S_OK: 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.
DB_S_ERRORSOCCURRED: An error occurred while returning data for one or more columns, but data was successfully returned for at least one column. To determine the columns for which data was returned, the consumer checks the status values. For a list of status values that can be returned by this method, see "Status Values Used When Getting Data" in "Status" in Chapter 6: Getting and Setting Data.
E_FAIL: A provider-specific error occurred.
E_INVALIDARG: pData was a null pointer, and hAccessor was not a null accessor.
E_UNEXPECTED: ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state.
DB_E_BADACCESSORHANDLE: 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.
DB_E_BADACCESSORTYPE: The specified accessor was not a row accessor. Some providers may return DB_E_BADACCESSORHANDLE instead of this error code when command accessors are passed to the rowset.
DB_E_BADROWHANDLE: hRow was invalid.
DB_E_DELETEDROW: hRow referred to a pending delete row or a row for which a deletion had been transmitted to the data store. Providers are not required to check for this condition, because doing so might slow the method significantly.
DB_E_ERRORSOCCURRED: Errors occurred while returning data for all columns. To determine what errors occurred, the consumer checks the status values. For a list of status values that can be returned by this method, see "Status Values Used When Getting Data" in "Status" in Chapter 6: Getting and Setting Data.
DB_E_NEWLYINSERTED: DBPROP_CHANGEINSERTEDROWS was VARIANT_FALSE, and hRow referred to a row for which the insertion has been transmitted to the data store.
DB_E_PENDINGINSERT: The rowset was in delayed update mode, and hRow referred to a pending insert row.
DB_SEC_E_PERMISSIONDENIED: The consumer did not have sufficient permission to retrieve the rows from the data store.

Comments

If this method performs deferred accessor validation and that validation takes place before any data is transferred, it can also return any of the following return codes for the applicable reasons listed in the corresponding DBBINDSTATUS values in IAccessor::CreateAccessor:

E_NOINTERFACE
DB_E_BADBINDINFO
DB_E_BADORDINAL
DB_E_BADSTORAGEFLAGS
DB_E_UNSUPPORTEDCONVERSION

This method makes no logical change to the state of the object. A consumer calls IRowsetRefresh::GetLastVisibleData to retrieve the latest visible data from the data store.

For providers that cache visible data, this is visible data obtained in the most recent call to IRowsetRefresh::RefreshVisibleData for this row. On a given row with pending changes, until there has been a successful call to refresh the visible data cache with IRowsetRefresh::RefreshVisibleData, this method will return the same data as a call to IRowsetUpdate::GetOriginalData for that row. On a given row with no pending changes, this method will return the same data as a call to IRowset::GetData for that row.

For providers that don't cache visible data or for deferred columns, this is the data currently visible from the data store. For a complete description of how IRowsetRefresh::GetLastVisibleData retrieves data, see "Getting Data" in Chapter 6: Getting and Setting Data.

IRowsetRefresh::GetLastVisibleData is usually used in combination with IRowset::GetData and IRowsetUpdate::GetOriginalData to allow consumers to display collisions occurring with optimistic updates. After a row collision and a call to IRowsetRefresh::RefreshVisibleData to obtain the latest data store values for the conflicting rows, the three GetData-style functions collectively allow consumers access to all three sets of values needed to analyze the collision and decide on a resolution. The consumer can gain access to the pending-change values (GetData), the original values of the rowset before any changes were made (GetOriginalData), and the newly changed values at the data store that caused the collision (GetLastVisibleData).

If IRowsetRefresh::GetLastVisibleData fails for any reason other than DB_E_ERRORSOCCURRED, the memory to which pData points is not freed but its contents are undefined. If before IRowsetRefresh::GetLastVisibleData failed the provider allocated any memory for return to the consumer, the provider frees this memory and does not return it to the consumer. The same is true if DB_E_ERRORSOCCURRED was returned but the consumer did not request status values in the binding.

There is a difference between calling IRowsetUpdate::GetOriginalData and calling IRowsetRefresh::GetLastVisibleData. In a delayed update mode, if data is changed by another consumer, different consumers may retrieve different data. For example, the value in Column 1 is X. In a delayed update mode, Consumer A changes the value in that column to Y but does not transmit this action to the data store. Consumer B then changes the value in Column 1 to Z. If Consumer A calls IRowsetUpdate::GetOriginalData, it gets X. However, if it calls IRowsetRefresh::GetLastVisibleData, using a dirty read, it will retrieve Z.

IRowsetRefresh::GetLastVisibleData

See Also