Chapters

Chapters are used to identify a group of rows within a rowset. The group of rows may have a common characteristic, such as satisfying a filter condition or having a common parent in a hierarchical rowset, and may have an imposed order. Chapter handles are defined as follows:

typedef ULONG HCHAPTER;
# define DB_NULL_HCHAPTER  0x00  // Always invalid

Chapters are assumed to have significant overhead, so they must be managed. This is done automatically according to the following rules:

• The rules for sequential rowsets take precedence, so a grouped sequential rowset's chapters can be opened only in the proper sequence and cannot be revisited after they have been scanned. It may be necessary to close a prior chapter before the next can be opened.
  
  
• A chapter is opened upon use, if it is not already in an active state.

When the reference count on a chapter is released to zero, then the resources needed to manage the chapter can be discarded or marked as discardable. Note, however, that if the reference count on a chapter falls to zero and the chapter contains rows with pending changes, the chapter's resources might not be freed until the pending change status on the rows is cleared, either through a call to IRowsetUpdate::Update or IRowsetUpdate::Undo.