IParentRowset::GetChildRowset
Returns the child rowset corresponding to a chapter-valued column in the parent rowset.
Syntax
HRESULT GetChildRowset(
IUnknown *pUnkOuter,
DBORDINAL iOrdinal,
REFIID riid,
IUnknown **ppRowset);
Parameters
pUnkOuter
[in] A pointer to the controlling IUnknown interface if the object is being created as part of an aggregate; otherwise, it is a null pointer.iOrdinal
[in] The ordinal of the chapter-valued column in the parent rowset.riid
[in] The requested interface to return in *ppRowset.ppRowset
[out] A pointer to memory in which to return the interface for the child rowset. If an error occurs, *ppRowset is set to a null pointer.
Return Code
S_OK
The method succeeded.E_INVALIDARG
ppRowset was a null pointer.E_NOINTERFACE
The interface specified in riid was not supported on the rowset.E_OUTOFMEMORY
The provider was unable to allocate sufficient memory in which to create the rowset.E_UNEXPECTED
ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state.DB_E_NOAGGREGATION
pUnkOuter was not a null pointer, and the provider is an OLE DB 1.0 or 1.1 provider that does not support aggregation of the rowset object being created.pUnkOuter was not a null pointer, and riid was not IID_IUnknown.
DB_E_OBJECTOPEN
The referenced rowset has already been opened.The provider is single-chaptered, and a child rowset is still open.
DB_E_BADORDINAL
The column specified by iOrdinal was not a chapter-valued column or did not exist.
Comments
IParentRowset::GetChildRowset can be called only once for each child rowset and if called, must be called before any calls to IRowsetInfo::GetReferencedRowset for that child. The pUnkOuter argument specified in IParentRowset::GetChildRowset defines the controlling unknown for all references to that child rowset for the lifetime of the parent. The parent rowset must use addref on this controlling unknown to guarantee that it doesn't go away before the parent. Even though the controlling unknown is constant for the lifetime of the parent, the consumer must not assume that rowset states, such as accessors, row position, and so on, are held when all references to the rowset are released. Furthermore, providers must ensure that the next fetch position within the child rowset is reset once all references to that child rowset have been released. Calling IParentRowset::GetChildRowset for a child rowset that has already been obtained returns DB_E_OBJECTOPEN.