Using the Data Shaping Service for OLE DB: A Closer Look
Important
This feature will be removed in a future version of Windows. Avoid using this feature in new development work, and plan to modify applications that currently use this feature. Instead, applications should use XML.
The Data Shaping Service for OLE DB is shipped with the Microsoft Data Access Components in the file Msadds.dll. The Data Shaping Provider allows you to build and manipulate Recordsets obtained from your data provider into hierarchies or to manipulate existing hierarchies.
Rowsets, Chapters, and Hierarchical Rowsets
A rowset object can identify a chapter?a group of rows having some sort of common characteristic within a rowset. When two rowsets have a hierarchical relationship, the parent rowset contains a chapter column. The value of this column for each parent is called a chapter handle and contains the 4-byte value that identifies the child rows. When the chapter handle for a specific parent rowset row is used with the child rowset, it scopes the child rowset to just those rows associated with the parent row, creating the hierarchy. When a new parent row is selected, ADO causes the children to be released as it releases the chapter handles, reads the new chapter handle value, and refers to the correct set of child rows.
Hierarchy Types of the Data Shaping Service
The Data Shaping Service for OLE DB allows you to build two distinct hierarchical types. A relation-based hierarchy can also be considered a filter-based hierarchy because it establishes a parent-child relationship between rowsets. The relationship can be explicitly stated in a command or use a parameterized data provider command to identify the child rows. The parameter values used to execute the data provider command are column values from the parent row.
Computed or group-based hierarchical rowsets are organized in logical groups and are members of the hierarchy structure. This allows you to establish a relationship of a fabricated parent row to a group, or a group to a group. Using the COMPUTE clause of the Shape language, the child rows in a rowset are partitioned and a parent rowset is created. The parent rowset contains one row for each partition in the child rowset.
The Shape Language
When connected to the Data Shaping Service for OLE DB, you can use the Shape language to construct or add to hierarchies. The syntax enables you to create numerous hierarchical relations between rowsetobjects.
You can make a one-to-one, one-to-many, many-to-one, or many-to-many relationship by appending a child rowset to a parent rowset, where each has at least one column value in common. Childless parent rows are also allowed. The following figure shows what relationships can be created.
.gif "possible child-parent relationships")
The Shape command syntax is SHAPE <Rowset> APPEND <append list>. The APPEND clause creates four column types, as described in the following table.
Appended columns |
Description |
|---|---|
Chapter column |
Adds a chapter column to the parent rowset. Defines the child rowset. Defines the relationship between the parent and the child rowset. May be a one-to-one, one-to-many, many-to-one, or many-to-many relationship. Orphans are possible. |
Aggregate function |
For a specific chapter, performs an aggregation function over the child rows. Available functions are MIN, MAX, AVG, SDEV (or STDEV), SUM, COUNT, and ANY. |
CALC column |
Produces a calculation by using an expression over the columns in the row. Uses the Microsoft Jet Expression Service (Msjtes40.dll) to evaluate. Cannot reference other CALC columns. |
New column |
Adds fabricated columns to rowsets. Initial value is NULL. |
You can build a parent rowset from a child rowset, but at least one chapter column in the parent rowset must reference the child rowset. Other parent columns are created by computing an aggregate operation over a column of the child rowset, calculating expressions on a row of a rowset, specifying a grouping column with the BY keyword, or appending a new, empty column. The parent rowset can have all the APPEND column types. The Shape command syntax is SHAPE <Child Rowset> COMPUTE <parent column list [BY grouping column list]>.
Shape Command References
This guide contains Data Shaping Service usage examples, but you can find a more thorough description of the command syntax in the ADO Programmer's Reference in the following topics:
"Shape Commands in General"
"Formal Shape Grammar"
"Shape Append Command"
"Shape Compute Command"
See Also
Reference
Lifetime of Row Handles Within Chapters