IParentRowset::GetChildRowset

  • Article

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.

See Also

Reference

IRowsetInfo::GetReferencedRowset