Navigating Hierarchical Rowsets

When the consumer executes a hierarchical query, the method returns the requested interface on the root rowset. This root rowset contains one or more chapter columns.

Before using a chapter, the consumer must obtain a pointer to the child rowset by passing the ordinal of the chapter-valued column to either IParentRowset::GetChildRowset or IRowsetInfo::GetReferencedRowset. Consumers use GetChildRowset to obtain an aggregated instance of the child rowset. They use GetReferencedRowset to obtain a reference on a previously retrieved rowset or to create an instance of a nonaggregated rowset if the child rowset does not already exist.

Calling IRowsetInfo::GetReferencedRowset for a child rowset that has already been obtained takes an additional reference count on that rowset. Calling GetReferencedRowset for a child rowset that has not previously been obtained returns the requested interface on a nonaggregated instance of the rowset.

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 GetChildRowset defines the controlling unknown for all references to that child rowset for the lifetime of the parent. The parent rowset must call 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 information, such as accessors and row position, is held when all references to the rowset are released. Furthermore, providers must ensure that the next fetch position within the child rowset is reset after 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.

For example, after executing the above command and calling IParentRowset::GetChildRowset with the ordinal of the order_rows column, the consumer can get an additional reference on the Orders rowset by calling IRowsetInfo::GetReferencedRowset on the Customer rowset with the ordinal of the order_rows column.

The consumer navigates rows inside a chapter by using methods such as IRowset::GetNextRows, IRowsetLocate::GetRowsAt, and IRowsetLocate::GetRowsByBookmark, passing the chapter handle obtained from a parent rowset as an input argument to the method. For example, suppose the Customer rowset has a row for Jones containing a chapter chJonesOrders. Jones's orders are fetched by calling IRowset::GetNextRows on the Customer rowset and passing chJonesOrders as an input argument to the method.