IRow::GetSourceRowset

OLE DB Programmer's Reference

Returns an interface pointer on the rowset that contains the row represented by a row object.

HRESULT GetSourceRowset(    REFIID        riid,    IUnknown    **ppRowset,    HROW         *phRow );

Parameters

riid

[in]
The interface ID (IID) of the requested interface to return in ppRowset. This argument is ignored if ppRowset is a null pointer.

ppRowset

[out]
A pointer to memory in which to return the interface for the rowset. If the caller sets ppRowset to a null pointer, no rowset is returned. If the provider does not have a rowset object as the source for the row, it sets *ppRowset to a null pointer. If IRow::GetSourceRowset fails, the provider must attempt to set *ppRowset to a null pointer.

phRow

[out]
A pointer to memory in which to return the row handle of this row within the source rowset. If phRow is a null pointer, no row handle is returned. If the provider does not have a rowset object as the source for the row, it sets *phRow to NULL. If IRow::GetSourceRowset fails, the provider must attempt to set *phRow to NULL.

Return Code

S_OK

The method succeeded.

DB_E_DELETEDROW

The row was either a pending delete row or a row for which a deletion had already been transmitted to the data store.

DB_E_NOSOURCEOBJECT

The provider did not have a rowset object as the source for the row. Therefore, it set *ppRowset and *phRow to NULL.

E_FAIL

A provider-specific error occurred.

E_INVALIDARG

ppRowSet and phRow were null pointers.

E_NOINTERFACE

The rowset did not support the interface specified in riid.

E_UNEXPECTED

ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state.

Comments

By providing ppRowset, phRow, or both, the caller may request the source rowset, the row handle, or both. The provider increments the reference count of any row handle that is returned to the consumer.

If the row object was created as a result of executing a command or if it was instantiated directly by calling IBindResource::Bind or ICreateRow::CreateRow, no source rowset exists and the provider must return DB_E_NOSOURCEOBJECT.

IRow::GetSourceRowset returns an interface pointer on the rowset from which the row object was created. The consumer can call IRowset::GetData using the row handle returned in *phRow. If the consumer held a reference to the source rowset, IRow::GetSourceRowset does not affect the next fetch position of the rowset. If the consumer did not hold a reference to the source rowset, it is provider-specific whether or not that previous next fetch position is returned. However, the consumer can call IRowset::RestartPosition to reset it to a known position.

1998-2001 Microsoft Corporation. All rights reserved.