IRowsetRefresh::GetLastVisibleData

Gets the most recent data from either the visible data cache or the data source.

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), then 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.

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.

DB_E_BADROWHANDLE

hRow was invalid.

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.

DB_E_PENDINGINSERT

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

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

Comments

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

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 source. For a complete description of how GetLastVisibleData retrieves data, see “Getting Data” in Chapter 6.

GetVisibleData 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 source 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 source that caused the collision (GetLastVisibleData).

If GetLastVisibleData fails, the memory to which pData points is not freed but its contents are undefined. If, before 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.

There is a difference between calling GetOriginalData and calling 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 source. Consumer B then changes the value in Column 1 to Z. If Consumer A calls GetOriginalData, it gets X. However, if it calls GetLastVisibleData, using a dirty read, it will retrieve Z.