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). In addition to this, there may be provider-specific default properties, or the application may have selected additional properties by using the DIMENSION PROPERTIES clause. Because of this, it is possible that the number of columns corresponding to a dimension is more than five. The field rgcColumns in the MDAXISINFO structure for this axis points to an array containing the number of columns in the axis rowset for this dimension.

The axis rowset has columns in the following order:

• TUPLE_ORDINAL column.
  
  
• Columns for the outermost dimension.
  
  
• 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:

• MEMBER_UNIQUE_NAME. The unique name of the member. This is the same as MEMBER_UNIQUE_NAME in the MEMBERS rowset.
  
  
• MEMBER_CAPTION. The display name of the member. This is the same as the MEMBER_CAPTION column of the MEMBERS rowset.
  
  
• 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.
  
  
• LEVEL_NUMBER. The distance of the member from the root (zero based, root = 0). This is the same as the LEVEL_NUMBER column of the MEMBERS rowset.
  
  
• 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 below:

  

  • 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 “Cube and Dataset Example” in Chapter 2. 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, then 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 may 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}, then 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 that all the children of a member 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 it to all the 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 types for TUPLE_ORDINAL and the five mandatory properties are:

• TUPLE_ORDINAL — DBTYPE_UI4
  
  
• MEMBER_UNIQUE_NAME — DBTYPE_WSTR
  
  
• MEMBER_CAPTION — DBTYPE_WSTR
  
  
• LEVEL_UNIQUE_NAME — DBTYPE_WSTR
  
  
• LEVEL_NUMBER — DBTYPE_I4
  
  
• DISPLAY_INFO — DBTYPE_UI4.

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.

An Example

Consider a dataset that looks like this:

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

The x-axis has the following elements:

• Two dimensions: Salesperson and Geography.
  
  
• Salesperson 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]. There are 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]. There are no provider-specific mandatory properties
  
  
• rgpwszDimensionNames = pointer to array [Quarters]

The axis rowset for the x-axis is shown in the table below. (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 is as shown below. (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 members from all other dimensions need not be qualified (for ensuring uniqueness). It is also assumed that all level names are unique without qualification.

Effect of DIMENSION PROPERTIES Clause on Axis Rowsets

If the MDX expression contains a DIMENSION PROPERTIES clause that selects properties of members, these properties are available in the axis rowset. Each property appears as a column in the axis rowset, whose name is <level_name>.<property_name>, where <level_name> is the unique name of the level to which the property belogs. The property columns (if any) come after the mandatory columns (MEMBER_UNIQUE_NAME, MEMBER_CAPTION, LEVEL_UNIQUE_NAME, LEVEL_NUMBER, and DISPLAY_INFO) for each dimension.

Note   As mentioned before, MEMBER_UNIQUE_NAME, MEMBER_CAPTION, LEVEL_UNIQUE_NAME, LEVEL_NUMBER, and DISPLAY_INFO are always available in the axis rowset. If these properties are specified in the DIMENSION PROPERTIES clause, they are ignored. The effect is as if they were not in the DIMENSION PROPERTIES clause.

Mandatory Member Properties

All providers are required to support the following mandatory properties for each member:

• CATALOG_NAME
  
  
• SCHEMA_NAME
  
  
• CUBE_NAME
  
  
• DIMENSION_UNIQUE_NAME
  
  
• HIERARCHY_UNIQUE_NAME
  
  
• LEVEL_UNIQUE_NAME
  
  
• LEVEL_NUMBER
  
  
• MEMBER_UNIQUE_NAME
  
  
• MEMBER_NAME
  
  
• MEMBER_TYPE
  
  
• MEMBER_GUID
  
  
• MEMBER_CAPTION
  
  
• MEMBER_ORDINAL
  
  
• CHILDREN_CARDINALITY
  
  
• PARENT_LEVEL
  
  
• PARENT_UNIQUE_NAME
  
  
• PARENT_COUNT
  
  
• DESCRIPTION

The meanings of these properties are the same as the respective columns of the MEMBERS rowset. (See “MEMBERS Rowset” in this chapter.)

The consumer can include any of these properties in the axis rowset by specifying them on the DIMENSION PROPERTIES clause.

Axis Rowsets and Calculated Members

Calculated members have well-defined values for all the mandatory member properties. They have a name, a unique name (which can be the qualified name or a different unique name generated by the provider), and so on. Most of these are derived from the member definition in the WITH clause or in the CREATE clause.

The following properties need special mention:

• MEMBER_GUID is always NULL.
  
  
• MEMBER_CAPTION is the same as the member name.
  
  
• CHILDREN_CARDINALITY is usually zero.

The values of the nonmandatory member properties, if any, are provider-defined.