IRowsetUpdate::GetOriginalData

Gets the data most recently fetched from or transmitted to the data source; does not get values based on pending changes.

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

Parameters

hRow

[in]
The handle of the row for which to get the original data. This can be the handle of a row with a pending change or delete.

hAccessor

[in]
The handle of the accessor to use. If hAccessor is the handle of a null accessor (cBindingsin IAccessor::CreateAccessor was zero), then GetOriginalData 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
A row handle in rghRows referred to a row on which a storage object or OLE object was open. The corresponding element of *prgRowStatus contains DBROWSTATUS_E_OBJECTOPEN.

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_DELETEDROW
hRow referred to a row for which a deletion had been transmitted to the data source.

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_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.

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.

GetOriginalData retrieves the values the row contained when it was last fetched or had changes transmitted to the data source. It does not retrieve any pending changes or changes made by other rowsets in the same transaction or other applications in other transactions. It also does not affect the current values for the row. For a complete description of how GetOriginalData retrieves data, see "Getting Data" in Chapter 6.

How GetOriginalData works is best illustrated in the following examples. In the first example, GetOriginalData fetches the values last fetched from the data source:

The consumer fetches a row.
The consumer calls IRowsetChange::SetData to update values in the row.
The consumer calls GetOriginalData. The consumer retrieves the values it would have retrieved had it called IRowset::GetData after step 1 and before step 2.

In the second example, GetOriginalData fetches the values last transmitted to the data source:

The consumer fetches a row.
The consumer calls SetData to update values in the row.
The consumer calls Update.
The consumer calls SetData to update values in the row.
The consumer calls GetOriginalData. The consumer retrieves the values it would have retrieved had it called GetData after step 3 and before step 4.

To implement GetOriginalData, the provider usually caches the original values just before making a change to a row and discards the cached values when Undo or Update is called for the row.

If hRow refers to a pending insert row, GetOriginalData returns the column defaults and, for columns without defaults or for which the provider was unable to determine the defaults, NULLs.

Whether GetOriginalData can retrieve the original value of an OLE object that is stored in a column, or a storage object that is created over a BLOB after changes have been made to that OLE object or BLOB, depends on the value of the DBPROP_DELAYSTORAGEOBJECTS rowset property.

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.

GetOriginalData does not enforce any security restrictions. The provider must not create a rowset that includes columns for which the consumer does not have read privileges, so GetOriginalData never encounters problems accessing the data for a column. The rowset can contain columns to which the consumer does not have write permission if DBPROP_COLUMNRESTRICT is VARIANT_TRUE. The methods that fetch rows must not return the handles of rows for which the consumer does not have read privileges, so GetOriginalData never encounters problems accessing a row. Such rows might exist if the DBPROP_ROWRESTRICT property is VARIANT_TRUE.

If GetOriginalData fails, the memory to which pData points is not freed but its contents are undefined. If, before GetOriginalData failed, the provider allocated any memory for return to the consumer, the provider frees this memory and does not return it to the consumer.