IRowsetResynch::GetVisibleData

  • Article

Gets the data in the data store that is visible to the transaction for the specified row.

Syntax

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

Parameters

  • hRow
    [in] The handle of the row for which to get the visible 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), IRowsetResynch::GetVisibleData 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.

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

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

  • DB_E_NEWLYINSERTED
    DBPROP_STRONGIDENTITY was VARIANT_FALSE, and hRow referred to a row for which an insertion had been transmitted to the data store.

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

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

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 IRowsetResynch::GetVisibleData to retrieve the data in the data store that is visible to the transaction for the specified row. However, IRowsetResynch::GetVisibleData does not affect the values in the rowset's copy of the row.

If IRowsetResynch::GetVisibleData fails for any reason other than DB_E_ERRORSOCCURRED, the memory that pData points to is not freed but its contents are undefined. If before IRowsetResynch::GetVisibleData failed the provider had allocated any memory to be returned 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.