IParentRowset is used to retrieve child rowsets from a hierarchical rowset. For more information, see "Hierarchical Rowsets" in Chapter 4.
IParentRowset is a mandatory interface on a hierarchical rowset.
The consumer calls IParentRowset::GetChildRowset in order to create an aggregated instance of the child rowset corresponding to a chapter-valued column in the parent rowset.
| Method | Description |
| GetChildRowset | Returns the child rowset corresponding to a chapter-valued column in the parent rowset. |
Returns the child rowset corresponding to a chapter-valued column in the parent rowset.
HRESULT GetChildRowset(
IUnknown * pUnkOuter,
ULONG 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 Value
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 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
GetChildRowset can be called only once for each child rowset and, if called, must be called before any calls to GetReferencedRowset for that child. The pUnkOuter argument specified in 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 state, 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 GetChildRowset for a child rowset that has already been obtained returns DB_E_OBJECTOPEN.
See Also