MDAC 2.5 SDK - OLE DB Programmer's Reference
Chapter 22: OLE DB for OLAP Objects and Schema Rowsets

Axis Rowsets

There is one rowset for every axis. This rowset has at least 5n+1 columns, where n is the number of dimensions projected along the axis (because there are five default properties that are available for each axis, and one more column for the TUPLE_ORDINAL value). In addition, there might be provider-specific default properties, or the application might have selected additional properties by using the DIMENSION PROPERTIES clause. For this reason, it is possible for a dimension to have more than five columns. The rgcColumns field in the MDAXISINFO structure for this axis points to an array containing the number of columns in the axis rowset for this dimension.

The range rowset is a rowset in which each row corresponds to a cell in the dataset. Each selected cell property appears as a column in this rowset. Range rowsets provide the means for updating the axis rowset. For more information about these rowsets, see "Range Rowsets" in Chapter 23, "Rowsets in OLE DB for OLAP." Also in Chapter 23, see "Creating an Accessor to Fetch Data" for an explanation of how the application, before fetching cell data, can create an accessor that describes the structure of the data buffer.

The axis rowset has columns in the following order:

1. TUPLE_ORDINAL column.
   
   
2. Columns for the outermost dimension.
   
   
3. Columns for dimensions with inner nestings.

• Within the columns for each dimension, the five default properties occur first, followed by any provider-specific properties, followed by the properties explicitly selected in the DIMENSION PROPERTIES clause.

The five default properties for each dimension, in order of their occurrence in the axis rowset, are as follows:

1. MEMBER_UNIQUE_NAME. The unique name of the member. This is the same as the MEMBER_UNIQUE_NAME column of the MEMBERS rowset.
   
   
2. MEMBER_CAPTION. The display name of the member. This is the same as the MEMBER_CAPTION column of the MEMBERS rowset.
   
   
3. LEVEL_UNIQUE_NAME. The name of the level to which this member belongs. This is the same as the LEVEL_UNIQUE_NAME column of the MEMBERS rowset.
   
   
4. LEVEL_NUMBER. The distance of the member from the root, which is zero. This is the same as the LEVEL_NUMBER column of the MEMBERS rowset.
   
   
5. DISPLAY_INFO. This property contains various items of information that help an application render the axis. It is a 4-byte value. The value of the least-significant 2 bytes is a 16-bit unsigned integer that contains the number of children of a member. In the most-significant 2 bytes, each bit potentially conveys one piece of display information. For OLE DB, meanings are defined for only 2 bits (the least-significant bits), as shown in the following illustration.

   

   • The least-significant bit (rightmost bit), if set, indicates that this member is drilled down. That is, at least one child of this member appears on the axis, immediately following the member. This can be tested by the bitmask MDDISPINFO_DRILLED_DOWN. This bit can be used by applications to display a "+" or a "–" next to the member.
     
     
   • The next bit (the second least-significant bit), if set, indicates that the parent of this member is the same as the parent of the immediately preceding member. This can be tested by the bitmask MDDISPINFO_SAME_PARENT_AS_PREV. The use of this bit becomes clear when one considers the problem of displaying the dataset shown in the SalesData example in Chapter 21, "OLE DB for OLAP Concepts." Specifically, how does the application get information about the ancestors of Seattle and Boston ("USA_North" and "USA")? It can do so by using the MDTREEOP_ANCESTORS property on the MEMBERS rowset. After getting the list of ancestors for Seattle, it must do the same for Boston. This is wasteful because the application already got the information when it got the ancestors for Seattle. The bit MDDISPINFO_SAME_PARENT_AS_PREV is useful in this scenario. It will be set for "Boston", and the application can use the ancestor information that it already has instead of querying the schema rowset again.

   Note the following rules about DISPLAY_INFO:

   • The value in the first 2 bytes of DISPLAY_INFO (the count of children) is an unsigned value.
     
     
   • If the number of children exceeds 65535 (the largest 16-bit number possible), the provider still returns 65535 in the first 2 bytes of DISPLAY_INFO. Therefore, the application's interpretation of the number 65535 in this field should be "greater than or equal to 65535 children." If the application wants to know the count of children beyond 65535, it should ask for the CHILDREN_CARDINALITY property in the DIMENSION PROPERTIES clause.
     
     
   • Just like the CHILDREN_CARDINALITY property, the count of children returned in the first 2 bytes of DISPLAY_INFO might not be exact.
     
     
   • MDDISPINFO_DRILLED_DOWN is set only if a child immediately follows a member on the axis. For instance, if the axis has {North_America, South_America, USA}, the MDDISPINFO_DRILLED_DOWN bit is not set for North_America because USA does not immediately follow North_America.
     
     
   • MDDISPINFO_DRILLED_DOWN does not require all the children of a member to be present on the axis, immediately following the member. It just requires at least one child to be present immediately following the member.
     
     
   • The bitmasks MDDISPINFO_DRILLED_DOWN and MDDISPINFO_SAME_PARENT_AS_PREV are 32-bit bitmasks. The application should apply them to all 4 bytes of DISPLAY_INFO.

To distinguish these column names, they are prefixed by <dimension_name>. For example, the column names for the SalesRep dimension are: "[SalesRep].[MEMBER_UNIQUE_NAME]", "[SalesRep].[MEMBER_CAPTION]", "[SalesRep].[LEVEL_UNIQUE_NAME]", "[SalesRep].[LEVEL_NUMBER]", "[SalesRep].[DISPLAY_INFO]".

The data type for the TUPLE_ORDINAL value is DBTYPE_UI4. The data types for the five mandatory properties are listed in the following table.

The data types of provider-specific properties and properties selected by using the DIMENSION PROPERTIES clause are available in the PROPERTIES schema rowset. This information is also available by calling IColumnsInfo on the rowset object corresponding to an axis rowset.

Axis Rowset Example

Consider the following dataset:

This dataset has two axes, x and y (0 and 1).

The x-axis has the following elements:

• Two dimensions: SalesRep and Geography.
  
  
• SalesRep dimension has members from the Name level.
  
  
• Geography dimension has members from the Country, Region, and City levels.

  Note that the country Japan has no regions defined in this database. Note also that USA_North has its cities expanded, while USA_South does not have its cities expanded.

The y-axis has the following elements:

• One dimension: Time.
  
  
• Two levels: Quarters and Month.

  Qtr1 and Qtr4 have their months expanded, while Qtr2 and Qtr3 do not.

The MDAXISINFO structure for the x-axis has:

• cbSize = 24 (assuming ULONG values and pointers are 4 bytes each)
  
  
• iAxis = 0
  
  
• cDimensions = 2
  
  
• cCoordinates = 8
  
  
• rgcColumns = pointer to array [5, 5] (no provider-specific mandatory properties)
  
  
• rgpwszDimensionNames = pointer to array [SalesRep, Geography]

The MDAXISINFO structure for the y-axis has:

• cbSize = 24 (assuming ULONG values and pointers are 4 bytes each)
  
  
• iAxis = 1
  
  
• cDimensions = 1
  
  
• cCoordinates = 8
  
  
• rgcColumns = pointer to array [5] (no provider-specific mandatory properties)
  
  
• rgpwszDimensionNames = pointer to array [Quarters]

The axis rowset for the x-axis is shown in the following table. (The value of DISPLAY_INFO is shown in the form "x, y, z", where z = number of children, y = MDDISPINFO_DRILLED_DOWN, and x = MDDISPINFO_SAME_PARENT_AS_PREV.)

(This is the same table continued.)

The axis rowset for the y-axis follows. (The value of DISPLAY_INFO is shown in the form "x, y, z", where z = number of children, y = MDDISPINFO_DRILLED_DOWN, and x = MDDISPINFO_ SAME_PARENT_AS_PREV.)

Note   In this example, it is assumed that the members of the SalesRep and Geography dimensions need to be qualified and that members from all other dimensions need not be qualified (to ensure uniqueness). It is also assumed that all level names are unique without qualification.