IDSSSort Interface Reference

Inherited by IDSSSort2.

Detailed Description

The IDSSSort interface is used to specify how the analytic engine sorts the rows or columns generated by a template.

: In this document, for simplicity, we always imagine that we are sorting the rows of a template. However the same sort object is also used to sort the columns of the template. In that case the words row and column should be interchanged.

A sort interface is used in the following circumstances:

On each axis of the template, to describe the sort for that axis.
On each attribute, to describe the default sort for the attribute.
In an expression, to order the inputs to a non-commutative aggregation function. For example, the running total function depends on the order of its inputs.

There are several different types of sort. Each method works by generating a key value for each of the rows to be sorted. The rows are then sorted so that the values are in ascending (or descending) order. The types of sort differ by how they generate the value. Possible sources are

From a form of an attribute on the rows axis (this is the only root method available when using a sort as part of an attribute's definition).
From a column in the body of the XTabbed data. (This is known as a metric sort.)
There is also a pseudo-sort whose sole effect is to move the position of subtotal rows.

: The SortType property records the type of sort that is in use. Any the properties that are relevant to the current sort type are useful. As a convenience to our client we modify this property whenever the user writes a non-trivial value to a property that is only used in one sort type. We assume that the user wouldn't be setting this property if they did not want to use it. (Setting the property to NULL does not express interest, and should not change the SortType.)

Public Member Functions

HRESULT Ascending ([in] VARIANT_BOOL Ascending)

True to sort the elements into ascending order This property indicates which way the rows are sorted.

HRESULT Ascending ([out, retval] VARIANT_BOOL *pAscending)

True to sort the elements into ascending order This property indicates which way the rows are sorted.

HRESULT Attribute ([in] IDSSAttribute *pAttribute)

Specifies the attribute if sorting on an attribute form This property is used when we need an attribute value to determine the sort.

HRESULT Attribute ([out, retval] IDSSAttribute ppAttribute)

Specifies the attribute if sorting on an attribute form This property is used when we need an attribute value to determine the sort.

HRESULT Consolidation ([in] IDSSConsolidation *pConsolidation)

The consolidation used if sorting by a consolidation The Consolidation property holds the consolidation object used if the sort depends on a consolidation.

HRESULT Consolidation ([out, retval] IDSSConsolidation ppConsolidation)

The consolidation used if sorting by a consolidation The Consolidation property holds the consolidation object used if the sort depends on a consolidation.

HRESULT CustomGroup ([in] IDSSCustomGroup *pCustomGroup)

The custom group used if sorting by a custom group The CustomGroup property holds the custom group object used if the sort depends on a custom group.

HRESULT CustomGroup ([out, retval] IDSSCustomGroup ppCustomGroup)

The custom group used if sorting by a custom group The CustomGroup property holds the custom group object used if the sort depends on a custom group.

HRESULT Dimension ([in] IDSSDimension *pDimension)

The dimension used if sorting by a dimension The Dimension property holds the dimension object used if the sort depends on a dimension.

HRESULT Dimension ([out, retval] IDSSDimension ppDimension)

The dimension used if sorting by a dimension The Dimension property holds the dimension object used if the sort depends on a dimension.

HRESULT Elements ([out, retval] IDSSElements ppElements)

Collection of elements used to modify metric sort This sort returns a collection of elements.

HRESULT Form ([in] IDSSAttributeForm *pForm)

The attribute form whose value(s) are used as the key The Form property stores an IDSSAttributeForm object.

HRESULT Form ([out, retval] IDSSAttributeForm ppForm)

The attribute form whose value(s) are used as the key The Form property stores an IDSSAttributeForm object.

HRESULT Index ([in] Int32 Index)

The index number of this sort in its collection This property gives the index number of this sort in the Sorts collection that contains it.

HRESULT Index ([out, retval] Int32 *pIndex)

The index number of this sort in its collection This property gives the index number of this sort in the Sorts collection that contains it.

HRESULT Locale ([in] Int32 Locale)

Locale setting to use if sort involves ordering text strings Locale is a numeric property.

HRESULT Locale ([out, retval] Int32 *pLocale)

Locale setting to use if sort involves ordering text strings Locale is a numeric property.

HRESULT Metric ([in] IDSSMetric *pMetric)

The metric used if sorting on value of a metric When we perform a metric sort, we need to know which metric to sort by.

HRESULT Metric ([out, retval] IDSSMetric ppMetric)

The metric used if sorting on value of a metric When we perform a metric sort, we need to know which metric to sort by.

HRESULT SortType ([in] EnumDSSSortType SortType)

Indicates which type of sort this is A sort object is in effect a union of several different types of sort.

HRESULT SortType ([out, retval] EnumDSSSortType *pSortType)

Indicates which type of sort this is A sort object is in effect a union of several different types of sort.

HRESULT Subtotal ([in] IDSSTemplateSubtotal *pSubtotal)

Template Subtotal used if sorting on value of a metric Subtotal is an object-valued property.

HRESULT Subtotal ([out, retval] IDSSTemplateSubtotal ppSubtotal)

Template Subtotal used if sorting on value of a metric Subtotal is an object-valued property.

HRESULT SubtotalsPosition ([in] EnumDSSSubtotalsPosition Position)

Enumeration specifying where the sort places subtotals We sort rows in the grid using their key values.

HRESULT SubtotalsPosition ([out, retval] EnumDSSSubtotalsPosition *pPosition)

Enumeration specifying where the sort places subtotals We sort rows in the grid using their key values.

Member Function Documentation

HRESULT IDSSSort::Ascending ( [in] VARIANT_BOOL Ascending )

True to sort the elements into ascending order This property indicates which way the rows are sorted.
If Ascending is True then the rows are sorted so that lower rows have larger key values. Conversely setting Ascending to False reverses the order of the rows.
Setting this property has no affect on the SortType property.

This property is not used when positioning 'subtotal' rows, since the SubtotalsPosition property indicates if the subtotals are to go before or after the other rows. This means this property is ignored if the SortType is DssSortSubtotalsPosition. The property is relevant for the other types of sorts.

Returns:
Usual COM result code:

S_OK

HRESULT IDSSSort::Ascending ( [out, retval] VARIANT_BOOL * pAscending )

True to sort the elements into ascending order This property indicates which way the rows are sorted.
If Ascending is True then the rows are sorted so that lower rows have larger key values. Conversely setting Ascending to False reverses the order of the rows.
Setting this property has no affect on the SortType property.

This property is not used when positioning 'subtotal' rows, since the SubtotalsPosition property indicates if the subtotals are to go before or after the other rows. This means this property is ignored if the SortType is DssSortSubtotalsPosition. The property is relevant for the other types of sorts.

Returns:
Usual COM result code:

S_OK

HRESULT IDSSSort::Attribute ( [in] IDSSAttribute * pAttribute )

Specifies the attribute if sorting on an attribute form This property is used when we need an attribute value to determine the sort.
This is relevant to for sorting on an attribute form (DssSortAttributeForm). Setting this property (to a non-null value) changes the SortType to DssSortAttributeForm.
Returns:
Usual COM result code:

S_OK

HRESULT IDSSSort::Attribute ( [out, retval] IDSSAttribute ppAttribute )

Specifies the attribute if sorting on an attribute form This property is used when we need an attribute value to determine the sort.
This is relevant to for sorting on an attribute form (DssSortAttributeForm). Setting this property (to a non-null value) changes the SortType to DssSortAttributeForm.
Returns:
Usual COM result code:

S_OK

HRESULT IDSSSort::Consolidation ( [in] IDSSConsolidation * pConsolidation )

The consolidation used if sorting by a consolidation The Consolidation property holds the consolidation object used if the sort depends on a consolidation.
We need a consolidation for DssSortConsolidationDefault. This sort specifies that we want to put rows in the order defined in a consolidation.
Setting this property changes the sort type to DssSortConsolidationDefault.

Parameters:

pConsolidation Could be NULL

Returns:
Usual COM result code:

S_OK

HRESULT IDSSSort::Consolidation ( [out, retval] IDSSConsolidation ppConsolidation )

The consolidation used if sorting by a consolidation The Consolidation property holds the consolidation object used if the sort depends on a consolidation.
We need a consolidation for DssSortConsolidationDefault. This sort specifies that we want to put rows in the order defined in a consolidation.
Setting this property changes the sort type to DssSortConsolidationDefault.

Parameters:

ppConsolidation Could be NULL

Returns:
Usual COM result code:

S_OK

HRESULT IDSSSort::CustomGroup ( [in] IDSSCustomGroup * pCustomGroup )

The custom group used if sorting by a custom group The CustomGroup property holds the custom group object used if the sort depends on a custom group.
We need a custom group for DssSortCustomGroupDefault. This sort specifies that we want to put rows in the order defined in a custom group.
Setting this property changes the sort type to DssSortCustomGroupDefault.

Parameters:

pCustomGroup Could be NULL

Returns:
Usual COM result code:

S_OK

HRESULT IDSSSort::CustomGroup ( [out, retval] IDSSCustomGroup ppCustomGroup )

The custom group used if sorting by a custom group The CustomGroup property holds the custom group object used if the sort depends on a custom group.
We need a custom group for DssSortCustomGroupDefault. This sort specifies that we want to put rows in the order defined in a custom group.
Setting this property changes the sort type to DssSortCustomGroupDefault.

Parameters:

ppCustomGroup Could be NULL

Returns:
Usual COM result code:

S_OK

HRESULT IDSSSort::Dimension ( [in] IDSSDimension * pDimension )

The dimension used if sorting by a dimension The Dimension property holds the dimension object used if the sort depends on a dimension.
We need a dimension for DssSortDimensionForm and DssSortDimensionDefault. In both cases the sort is applied by actually sorting whatever attributes replace the dimension.
Setting this property changes the sort type to DssSortDimensionForm, unless it was previously DssSortDimensionDefault.

Parameters:

pDimension Could be NULL

Returns:
Usual COM result code:

S_OK

HRESULT IDSSSort::Dimension ( [out, retval] IDSSDimension ppDimension )

The dimension used if sorting by a dimension The Dimension property holds the dimension object used if the sort depends on a dimension.
We need a dimension for DssSortDimensionForm and DssSortDimensionDefault. In both cases the sort is applied by actually sorting whatever attributes replace the dimension.
Setting this property changes the sort type to DssSortDimensionForm, unless it was previously DssSortDimensionDefault.

Parameters:

ppDimension Could be NULL

Returns:
Usual COM result code:

S_OK

HRESULT IDSSSort::Elements ( [out, retval] IDSSElements ppElements )

Collection of elements used to modify metric sort This sort returns a collection of elements.
These elements are used to modify the effect of a metric or hierarchical sort by specifying particular sort columns.
Accessing the collection does not change the sort type. Adding a member to the collection changes the sort type to DssSortMetric, unless the sort type was previously DssSortMetricHierarchical.

Returns:
Usual COM result code:

S_OK

HRESULT IDSSSort::Form ( [in] IDSSAttributeForm * pForm )

The attribute form whose value(s) are used as the key The Form property stores an IDSSAttributeForm object.
For attribute form sorts, and for dimension forms this property refers to the form of the attribute whose value is used as a sort key. Usually this form should correspond to a base form of the attribute, so we get a single key value. However a user may sort by a form that maps to multiple base forms on an attribute. In that case the sort applies lexicographically to each form, in order of ascending base form ID.
Since this property is usually used when sorting by attribute form, setting this property will change the SortType property to read DssSortAttributeForm. However if the type was previously DssSortDimensionForm then it is not changed.

It is implementation dependent if this property reverts to Nothing if the SortType is set to some value other than DssSortAttributeForm or DssSortDimensionForm. It is probably easier to leave it alone.

Parameters:

pForm The new value of the property. May be NULL

pForm The existing value of the property. Could be NULL

Returns:
Usual COM result code:

S_OK

HRESULT IDSSSort::Form ( [out, retval] IDSSAttributeForm ppForm )

The attribute form whose value(s) are used as the key The Form property stores an IDSSAttributeForm object.
For attribute form sorts, and for dimension forms this property refers to the form of the attribute whose value is used as a sort key. Usually this form should correspond to a base form of the attribute, so we get a single key value. However a user may sort by a form that maps to multiple base forms on an attribute. In that case the sort applies lexicographically to each form, in order of ascending base form ID.
Since this property is usually used when sorting by attribute form, setting this property will change the SortType property to read DssSortAttributeForm. However if the type was previously DssSortDimensionForm then it is not changed.

It is implementation dependent if this property reverts to Nothing if the SortType is set to some value other than DssSortAttributeForm or DssSortDimensionForm. It is probably easier to leave it alone.

Parameters:

ppForm The existing value of the property. Could be NULL

Returns:
Usual COM result code:

S_OK

HRESULT IDSSSort::Index ( [in] Int32 Index )

The index number of this sort in its collection This property gives the index number of this sort in the Sorts collection that contains it.
The sorts in the Sorts collection are applied in ascending order. The later sorts in the collection are only used to resolve ties between earlier sorts in the collection.
The API assigns the Index numbers. These numbers are always in the range 1 to Sorts.Count, where Sorts is the collection that contains this Sort object. The user may reassign the value of this property provided a valid value is used. The other sorts in the collection is assigned index numbers that preserves their relative order.

Parameters:

Index New Index number for this sort. Must be in range 1 to Sorts.Count.

Returns:
Usual COM result code:

S_OK

E_INVALIDARG Returned if Index is not in correct range.

HRESULT IDSSSort::Index ( [out, retval] Int32 * pIndex )

The index number of this sort in its collection This property gives the index number of this sort in the Sorts collection that contains it.
The sorts in the Sorts collection are applied in ascending order. The later sorts in the collection are only used to resolve ties between earlier sorts in the collection.
The API assigns the Index numbers. These numbers are always in the range 1 to Sorts.Count, where Sorts is the collection that contains this Sort object. The user may reassign the value of this property provided a valid value is used. The other sorts in the collection is assigned index numbers that preserves their relative order.

Parameters:

pIndex Existing index number for this sort. Must be in range 1 to Sorts.Count.

Returns:
Usual COM result code:

S_OK

E_INVALIDARG Returned if Index is not in correct range.

HRESULT IDSSSort::Locale ( [in] Int32 Locale )

Locale setting to use if sort involves ordering text strings Locale is a numeric property.
It is a number that represents a locale, that is which represents the combination of a location and language. If this sort involves ordering text strings then this locale is used to determine the correct order for the strings. The property is necessary because different languages require a different alphabetical order.
If this property is set to its default value (LOCALE_USER_DEFAULT) then a project wide property giving the locale is used instead. A project wide property is not sufficient because a warehouse might contain strings from several different languages. For example an attribute could have an English name and a German name property.

The enumeration of values for Locale is taken from the Win32 API. Please consult Win32 STK documentation to find out the available constants and which to locale each one corresponds.

As it happens LOCALE_USER_DEFAULT is equal to 1024.

Parameters:

Locale New value for the Locale property

Returns:
Usual COM result code:

S_OK

HRESULT IDSSSort::Locale ( [out, retval] Int32 * pLocale )

Locale setting to use if sort involves ordering text strings Locale is a numeric property.
It is a number that represents a locale, that is which represents the combination of a location and language. If this sort involves ordering text strings then this locale is used to determine the correct order for the strings. The property is necessary because different languages require a different alphabetical order.
If this property is set to its default value (LOCALE_USER_DEFAULT) then a project wide property giving the locale is used instead. A project wide property is not sufficient because a warehouse might contain strings from several different languages. For example an attribute could have an English name and a German name property.

The enumeration of values for Locale is taken from the Win32 API. Please consult Win32 STK documentation to find out the available constants and which to locale each one corresponds.

As it happens LOCALE_USER_DEFAULT is equal to 1024.

Parameters:

pLocale Current value for the Locale property

Returns:
Usual COM result code:

S_OK

HRESULT IDSSSort::Metric ( [in] IDSSMetric * pMetric )

The metric used if sorting on value of a metric When we perform a metric sort, we need to know which metric to sort by.
This property contains the metric that we use. At report execution time the sort is invalid unless this metric actually appears on the template. (Note that because of autoprompts we may not be able to determine earlier whether or not a sort is invalid.)
Setting this property to a non-NULL value changes the to DssSortMetric, unless the sort type was previously DssSortMetricHierarchical.

Parameters:

pMetric A valid metric object, or NULL.

Returns:
Usual COM result code:

S_OK

HRESULT IDSSSort::Metric ( [out, retval] IDSSMetric ppMetric )

The metric used if sorting on value of a metric When we perform a metric sort, we need to know which metric to sort by.
This property contains the metric that we use. At report execution time the sort is invalid unless this metric actually appears on the template. (Note that because of autoprompts we may not be able to determine earlier whether or not a sort is invalid.)
Setting this property to a non-NULL value changes the to DssSortMetric, unless the sort type was previously DssSortMetricHierarchical.

Parameters:

ppMetric Return a valid metric object, or NULL.

Returns:
Usual COM result code:

S_OK

HRESULT IDSSSort::SortType ( [in] EnumDSSSortType SortType )

Indicates which type of sort this is A sort object is in effect a union of several different types of sort.
This property records which of the options this sort is currently using. A client of this interface needs to examine this property to determine which of the properties of the sort are currently meaningful.
Unlike most type properties, a client can write to this property. It is permitted to change the type of an existing sort. When the client modifies a property that is only used by one type of sort we automatically modify the sort's type to be the type that uses the property.

If the type put in is DssSortAttributeForm, we change the Subtotals position to DssSubtotalsPositionFirst if it was a DssSubtotalsPositionMix, since Mix does not make sense to an attribute form sort.

The enumeration of possible sort types is defined in the following table:

Name Meaning

DssSortReserved Not a valid sort type.

DssSortSubtotalsPosition This sort modifies the meaning of DssSubtotalsPositionDefault for subsequent sorts in the collection.

DssSortAttributeForm The sort discriminates on the value of a form of an attribute.

DssSortAttributeDefault Apply the attribute default sort.

DssSortMetric The sort discriminates by taking values from the body of the grid. That is the values are taken from some metric.

DssSortMetricHierarchical Same as DssSortMetric except that the sort pays attention to the hierarchy induced by the template. We sort elements and subtotals of each unit in turn. Later units are only used to break ties in earlier units.

DssSortGroupByMetric This sort only makes sense if it is applied to the template axis that contains the metrics unit. It indicates that we want to group together all the rows that use the same metric. The metrics appear in the same order as they do on the metrics unit of the template.

DssSortGroupBySubtotal This sort pays attention to the Attribute property. It groups together rows if they have the same template subtotal in their header for the given attribute. Rows that do not have a subtotal for the attribute are also put together.

DssSortDimensionForm This sort is similar to the attribute form sort. It is applied to whatever attribute(s) are substituted for the given dimension.

DssSortDimensionDefault This sort is similar to the default attribute sort. It applies to whatever attribute(s) are substituted for the given dimension.

DssSortConsolidationDefault Sort the rows so that the consolidation is put into its natural order.

DssSortCustomGroupDefault Sort the rows so that the custom group is put into its natural order.

DssSortValue This sort can only be used in an expression. It says sort the data that to which we want to apply the OLAP function so that it is in ascending/descending order.

Parameters:

SortType The new type for this sort.

Returns:
Usual COM result code:

S_OK

HRESULT IDSSSort::SortType ( [out, retval] EnumDSSSortType * pSortType )

Indicates which type of sort this is A sort object is in effect a union of several different types of sort.
This property records which of the options this sort is currently using. A client of this interface needs to examine this property to determine which of the properties of the sort are currently meaningful.
Unlike most type properties, a client can write to this property. It is permitted to change the type of an existing sort. When the client modifies a property that is only used by one type of sort we automatically modify the sort's type to be the type that uses the property.

If the type put in is DssSortAttributeForm, we change the Subtotals position to DssSubtotalsPositionFirst if it was a DssSubtotalsPositionMix, since Mix does not make sense to an attribute form sort.

The enumeration of possible sort types is defined in the following table:

Name Meaning

DssSortReserved Not a valid sort type.

DssSortSubtotalsPosition This sort modifies the meaning of DssSubtotalsPositionDefault for subsequent sorts in the collection.

DssSortAttributeForm The sort discriminates on the value of a form of an attribute.

DssSortAttributeDefault Apply the attribute default sort.

DssSortMetric The sort discriminates by taking values from the body of the grid. That is the values are taken from some metric.

DssSortMetricHierarchical Same as DssSortMetric except that the sort pays attention to the hierarchy induced by the template. We sort elements and subtotals of each unit in turn. Later units are only used to break ties in earlier units.

DssSortGroupByMetric This sort only makes sense if it is applied to the template axis that contains the metrics unit. It indicates that we want to group together all the rows that use the same metric. The metrics appear in the same order as they do on the metrics unit of the template.

DssSortGroupBySubtotal This sort pays attention to the Attribute property. It groups together rows if they have the same template subtotal in their header for the given attribute. Rows that do not have a subtotal for the attribute are also put together.

DssSortDimensionForm This sort is similar to the attribute form sort. It is applied to whatever attribute(s) are substituted for the given dimension.

DssSortDimensionDefault This sort is similar to the default attribute sort. It applies to whatever attribute(s) are substituted for the given dimension.

DssSortConsolidationDefault Sort the rows so that the consolidation is put into its natural order.

DssSortCustomGroupDefault Sort the rows so that the custom group is put into its natural order.

DssSortValue This sort can only be used in an expression. It says sort the data that to which we want to apply the OLAP function so that it is in ascending/descending order.

Parameters:

pSortType The existing type of this sort.

Returns:
Usual COM result code:

S_OK

HRESULT IDSSSort::Subtotal ( [in] IDSSTemplateSubtotal * pSubtotal )

Template Subtotal used if sorting on value of a metric Subtotal is an object-valued property.
This property is only used with a metric or hierarchical sort. Both of these sorts could need to select from one of the subtotals on the template. This property is always NULL on an attribute.
If the Sort contains subtotal elements, then all of the elements must have the same subtotal as is given by this property. For a hierarchical sort there are no elements, and this property indicates which subtotal to use.

The subtotal specified in this property should only have one corresponding metric sort. We require that the metric have at least one metric sort corresponding to this subtotal. So the 'all' subtotal cannot be used in this property.

If this property is NULL then we use the metric's default subtotal at report execution time if we need to select a metric subtotal. Setting this property to a non-NULL value changes the to DssSortMetric, unless the sort type was previously DssSortMetricHierarchical.

Changing the metric will set this property to NULL, and removes subtotal elements from the collection.

Parameters:

pSubtotal A template subtotal object taken from the template using this sort.

Returns:
Usual COM result code:

S_OK

OBJSVR_E_BAD_SUBTOTAL The subtotal does not specify a unique subtotal for this metric (either because the metric has no subtotal for this template subtotal, or because it has several which could happen with the All subtotal only).

HRESULT IDSSSort::Subtotal ( [out, retval] IDSSTemplateSubtotal ppSubtotal )

Template Subtotal used if sorting on value of a metric Subtotal is an object-valued property.
This property is only used with a metric or hierarchical sort. Both of these sorts could need to select from one of the subtotals on the template. This property is always NULL on an attribute.
If the Sort contains subtotal elements, then all of the elements must have the same subtotal as is given by this property. For a hierarchical sort there are no elements, and this property indicates which subtotal to use.

The subtotal specified in this property should only have one corresponding metric sort. We require that the metric have at least one metric sort corresponding to this subtotal. So the 'all' subtotal cannot be used in this property.

If this property is NULL then we use the metric's default subtotal at report execution time if we need to select a metric subtotal. Setting this property to a non-NULL value changes the to DssSortMetric, unless the sort type was previously DssSortMetricHierarchical.

Changing the metric will set this property to NULL, and removes subtotal elements from the collection.

Parameters:

ppSubtotal The template metric subtotal. May be NULL.

Returns:
Usual COM result code:

S_OK

OBJSVR_E_BAD_SUBTOTAL The subtotal does not specify a unique subtotal for this metric (either because the metric has no subtotal for this template subtotal, or because it has several which could happen with the All subtotal only).

HRESULT IDSSSort::SubtotalsPosition ( [in] EnumDSSSubtotalsPosition Position )

Enumeration specifying where the sort places subtotals We sort rows in the grid using their key values.
However a problem arises for the attribute form sort when we consider subtotal rows that sum data across the selected attribute. These rows do not correspond to an element in the data warehouse, and so we cannot read the sort key from the look-up table in the warehouse.
Instead we use this property. It either tells us to put the subtotal rows before all the ordinary rows, or to put them after all the ordinary rows, or to use the default setting. The default setting is to use the same setting as was used in the previous sort in the Sorts collection. If this is the first sort in the collection then we put subtotal rows before ordinary rows.

Because this property is relevant for all types of Sort, setting this method doesn't modify the sort type, except that it turns DssSortReserved into DssSortSubtotalsPosition.

The property is set to DssSubtotalsPositionMix on a new sort object.

This property takes its values from the following enumeration (DSSSort_Subtotals):

Name Meaning

DssSubtotalsPositionReserved Never used

DssSubtotalsPositionMix No special treatment.

DssSubtotalsPositionFirst Put subtotal rows before ordinary rows.

DssSubtotalsPositionLast Put subtotal rows after ordinary rows.

DssSubtotalsPositionInherit Use the same subtotal position as was used for the previous sort in the collection.

The meaning of this property is not affected by the value of the Ascending property. DssSubtotalsFirst means that subtotals go first regardless of whether the sorts are ascending or descending.

This property is meaningful for all types of sorts, in the sense that it can be used to modify the meaning of the default subtotals position in later sorts, even if this sort does not actually need to use the property to find a key value for subtotal rows.

Returns:
Usual COM result code:

S_OK

DSSCOM_E_RESERVED_VALUE Cannot set to the reserved value

E_INVALIDARG New value was not in the enumeration

HRESULT IDSSSort::SubtotalsPosition ( [out, retval] EnumDSSSubtotalsPosition * pPosition )

Enumeration specifying where the sort places subtotals We sort rows in the grid using their key values.
However a problem arises for the attribute form sort when we consider subtotal rows that sum data across the selected attribute. These rows do not correspond to an element in the data warehouse, and so we cannot read the sort key from the look-up table in the warehouse.
Instead we use this property. It either tells us to put the subtotal rows before all the ordinary rows, or to put them after all the ordinary rows, or to use the default setting. The default setting is to use the same setting as was used in the previous sort in the Sorts collection. If this is the first sort in the collection then we put subtotal rows before ordinary rows.

Because this property is relevant for all types of Sort, setting this method doesn't modify the sort type, except that it turns DssSortReserved into DssSortSubtotalsPosition.

The property is set to DssSubtotalsPositionMix on a new sort object.

This property takes its values from the following enumeration (DSSSort_Subtotals):

Name Meaning

DssSubtotalsPositionReserved Never used

DssSubtotalsPositionMix No special treatment.

DssSubtotalsPositionFirst Put subtotal rows before ordinary rows.

DssSubtotalsPositionLast Put subtotal rows after ordinary rows.

DssSubtotalsPositionInherit Use the same subtotal position as was used for the previous sort in the collection.

The meaning of this property is not affected by the value of the Ascending property. DssSubtotalsFirst means that subtotals go first regardless of whether the sorts are ascending or descending.

This property is meaningful for all types of sorts, in the sense that it can be used to modify the meaning of the default subtotals position in later sorts, even if this sort does not actually need to use the property to find a key value for subtotal rows.

Returns:
Usual COM result code:

S_OK

DSSCOM_E_RESERVED_VALUE Cannot set to the reserved value

E_INVALIDARG New value was not in the enumeration


Public Member Functions
HRESULT	Ascending ([in] VARIANT_BOOL Ascending)
	True to sort the elements into ascending order This property indicates which way the rows are sorted.
HRESULT	Ascending ([out, retval] VARIANT_BOOL *pAscending)
	True to sort the elements into ascending order This property indicates which way the rows are sorted.
HRESULT	Attribute ([in] IDSSAttribute *pAttribute)
	Specifies the attribute if sorting on an attribute form This property is used when we need an attribute value to determine the sort.
HRESULT	Attribute ([out, retval] IDSSAttribute ppAttribute)
	Specifies the attribute if sorting on an attribute form This property is used when we need an attribute value to determine the sort.
HRESULT	Consolidation ([in] IDSSConsolidation *pConsolidation)
	The consolidation used if sorting by a consolidation The Consolidation property holds the consolidation object used if the sort depends on a consolidation.
HRESULT	Consolidation ([out, retval] IDSSConsolidation ppConsolidation)
	The consolidation used if sorting by a consolidation The Consolidation property holds the consolidation object used if the sort depends on a consolidation.
HRESULT	CustomGroup ([in] IDSSCustomGroup *pCustomGroup)
	The custom group used if sorting by a custom group The CustomGroup property holds the custom group object used if the sort depends on a custom group.
HRESULT	CustomGroup ([out, retval] IDSSCustomGroup ppCustomGroup)
	The custom group used if sorting by a custom group The CustomGroup property holds the custom group object used if the sort depends on a custom group.
HRESULT	Dimension ([in] IDSSDimension *pDimension)
	The dimension used if sorting by a dimension The Dimension property holds the dimension object used if the sort depends on a dimension.
HRESULT	Dimension ([out, retval] IDSSDimension ppDimension)
	The dimension used if sorting by a dimension The Dimension property holds the dimension object used if the sort depends on a dimension.
HRESULT	Elements ([out, retval] IDSSElements ppElements)
	Collection of elements used to modify metric sort This sort returns a collection of elements.
HRESULT	Form ([in] IDSSAttributeForm *pForm)
	The attribute form whose value(s) are used as the key The Form property stores an IDSSAttributeForm object.
HRESULT	Form ([out, retval] IDSSAttributeForm ppForm)
	The attribute form whose value(s) are used as the key The Form property stores an IDSSAttributeForm object.
HRESULT	Index ([in] Int32 Index)
	The index number of this sort in its collection This property gives the index number of this sort in the Sorts collection that contains it.
HRESULT	Index ([out, retval] Int32 *pIndex)
	The index number of this sort in its collection This property gives the index number of this sort in the Sorts collection that contains it.
HRESULT	Locale ([in] Int32 Locale)
	Locale setting to use if sort involves ordering text strings Locale is a numeric property.
HRESULT	Locale ([out, retval] Int32 *pLocale)
	Locale setting to use if sort involves ordering text strings Locale is a numeric property.
HRESULT	Metric ([in] IDSSMetric *pMetric)
	The metric used if sorting on value of a metric When we perform a metric sort, we need to know which metric to sort by.
HRESULT	Metric ([out, retval] IDSSMetric ppMetric)
	The metric used if sorting on value of a metric When we perform a metric sort, we need to know which metric to sort by.
HRESULT	SortType ([in] EnumDSSSortType SortType)
	Indicates which type of sort this is A sort object is in effect a union of several different types of sort.
HRESULT	SortType ([out, retval] EnumDSSSortType *pSortType)
	Indicates which type of sort this is A sort object is in effect a union of several different types of sort.
HRESULT	Subtotal ([in] IDSSTemplateSubtotal *pSubtotal)
	Template Subtotal used if sorting on value of a metric Subtotal is an object-valued property.
HRESULT	Subtotal ([out, retval] IDSSTemplateSubtotal ppSubtotal)
	Template Subtotal used if sorting on value of a metric Subtotal is an object-valued property.
HRESULT	SubtotalsPosition ([in] EnumDSSSubtotalsPosition Position)
	Enumeration specifying where the sort places subtotals We sort rows in the grid using their key values.
HRESULT	SubtotalsPosition ([out, retval] EnumDSSSubtotalsPosition *pPosition)
	Enumeration specifying where the sort places subtotals We sort rows in the grid using their key values.