OLE DB Programmer's Reference

IRowsetUpdate::GetOriginalData

Gets the data most recently fetched from or transmitted to the data store; 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), IRowsetUpdate::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 or other 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: 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 row for which a deletion had been transmitted to the data store.
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_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.

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.

IRowsetUpdate::GetOriginalData retrieves the values the row contained when it was last fetched or had changes transmitted to the data store. 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 IRowsetUpdate::GetOriginalData retrieves data, see "Getting Data" in Chapter 6: Getting and Setting Data.

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

  1. The consumer fetches a row.
  2. The consumer calls IRowsetChange::SetData to update values in the row.
  3. The consumer calls IRowsetUpdate::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, IRowsetUpdate::GetOriginalData fetches the values last transmitted to the data store:

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

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

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

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

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.

IRowsetUpdate::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 IRowsetUpdate::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 IRowsetUpdate::GetOriginalData never encounters problems accessing a row. Such rows might exist if the DBPROP_ROWRESTRICT property is VARIANT_TRUE.

If IRowsetUpdate::GetOriginalData fails, the memory to which pData points is not freed but its contents are undefined. If before IRowsetUpdate::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. The same is true if DB_E_ERRORSOCCURRED was returned but the consumer did not request status values in the binding.

See Also

IRowset::GetData | IRowsetRefresh::GetLastVisibleData | IRowsetUpdate::Undo | IRowsetUpdate::Update