Chapters and Detail Groupings

Each grouping of a detail set, such as the orders for a particular customer, is treated as a subset with a particular beginning and end. A chapter identifies this detail group. A chapter is usually a partial key to the details. Because it is partial, it might lead to a set rather than a single row. The functions that take a chapter as a parameter, such as IRowsetLocate::GetRowsAt, use the beginning, membership, and end specified by the chapter to limit the rows that the request may return.

Chapters are opened as they are used, with usage tracked by reference counts. This is done transparently and allows the provider to minimize overhead dedicated to chapters. A reference count is taken on the chapter handle each time it is retrieved through IRowsetLocate::GetRowsAt on the parent rowset or by calling IChapteredRowset::AddRefChapter. The reference counts must be explicitly released by using IChapteredRowset::ReleaseChapter on the child rowset (that is, the rowset on which the chapter handle is used).

Although a chapter value may be held in a column of a table, that value is not the same thing as the physical instantiation of the chapter. The chapter may be instantiated when a command is executed or on demand when the chapter value is used. In any case, the actual chapter belongs not to the rowset that had the value column but to the rowset within which the chapter is defined. In the hierarchy example shown in Hierarchical Rowsets, the chapter handles for the Customer-Orders portion of the hierarchy above are in the order_rows column in Customer but the members of the chapter are in the Orders rowset. Hence, the release of a chapter is an action on the rowset owning the content. (In the example above, the consumer would use pOrders->ReleaseChapter(...).

When chapters and bookmarks are used together, the chapter does not qualify the bookmark. But methods that take bookmarks also take a chapter, and if several bookmarks (IRowsetLocate::GetRowsByBookmark) are used, they must all be in the same chapter. This is a consequence of managing the overheads of chapters. Because multiple chapters may contain a reference to the same row, the consumer needs to choose which chapter to use. The chapter acts to restrict the domain of rows, which can be retrieved. Bookmarks are unique within the chapter from which they are returned.