IDSSTemplateMetric Interface Reference

Inherited by IDSSTemplateMetric2.

List of all members.

---

Detailed Description

This interface is used to describe a metric in the context of its inclusion on a template.

All of the metrics on a template are placed together in a single template unit (using interface IDSSTemplateMetrics). This interface is a collection of IDSSTemplateMetric objects, one object for each metric.

The metric object needs to identify which metric it represents. However, it may also contain a MetricLimit which is actually an extra filter expression that the engine applies just to this metric when including it on the template.

Public Member Functions
HRESULT	Alias ([in] BSTR Alias)
	Optional metric alias used on the template.
HRESULT	Alias ([out, retval] BSTR *pAlias)
	Optional metric alias used on the template.
HRESULT	EvaluationOrder ([in] Int32 EvaluationOrder)
	Specifies when this unit is evaluated w.
HRESULT	EvaluationOrder ([out, retval] Int32 *pEvaluationOrder)
	Specifies when this unit is evaluated w.
HRESULT	Index ([in] Int32 Index)
	The metric's position in the metrics collection on this template.
HRESULT	Index ([out, retval] Int32 *pIndex)
	The metric's position in the metrics collection on this template.
HRESULT	IsDecomposed ([in, defaultvalue(DssDecomposableDefault)] EnumDSSDecomposable IsDecomposed)
	Whether the metric should be viewed as a composition of simpler metrics when calculating subtotals.
HRESULT	IsDecomposed ([out, retval] EnumDSSDecomposable *pIsDecomposed)
	Whether the metric should be viewed as a composition of simpler metrics when calculating subtotals.
HRESULT	MakeCurrentElement ()
	Make this TemplateMetric to be the current element.
HRESULT	Metric ([in] IDSSMetric *pMetric)
	The metric itself.
HRESULT	Metric ([out, retval] IDSSMetric ppMetric)
	The metric itself.
HRESULT	MetricExports ([out, retval] IDSSExports ppExports)
	Exports into the metric property.
HRESULT	MetricLimit ([out, retval] IDSSExpression ppMetricLimit)
	A (possibly empty) filter expression applied to this metric.
HRESULT	MetricPrompt ([in] IDSSPrompt *pPrompt)
	Prompt property that can be used to set the metric property.
HRESULT	MetricPrompt ([out, retval] IDSSPrompt ppPrompt)
	Prompt property that can be used to set the metric property.

---

Member Function Documentation

HRESULT IDSSTemplateMetric::Alias (  [in] BSTR  Alias  )

Optional metric alias used on the template. Alias is a string property. The purpose of the property is to allow the designer to rename a metric on this template. It is an optional property. If it is not set, it defaults to the real name of the metric. Parameters: Alias  New metric alias for this template. Returns: Usual COM result code: S_OK

HRESULT IDSSTemplateMetric::Alias (  [out, retval] BSTR *  pAlias  )

Optional metric alias used on the template. Alias is a string property. The purpose of the property is to allow the designer to rename a metric on this template. It is an optional property. If it is not set, it defaults to the real name of the metric. Parameters: pAlias  Existing metric alias. If the alias was never set, it defaults to the real metric name (i.e. ObjectInfo.Name) Returns: Usual COM result code: S_OK

HRESULT IDSSTemplateMetric::EvaluationOrder (  [in] Int32  EvaluationOrder  )

Specifies when this unit is evaluated w. r.t. subtotals, other units etc.. EvaluationOrder is a numeric property. It records at what point in the evaluation of the items on this template this metric is evaluated. Many of the entities on a template are evaluated by having the DSS Analytical Engine carry out a calculation. The entities often refer to each other as part of their expressions. Unfortunately, it is not hard to come up with non-distributive expressions, that is with expression that have the property that a different answer is obtained depending on their order of evaluation. In a template we deal with this problem by using EvaluationOrder properties. Each metric, subtotal, consolidation and metric limit in the template has one of these properties. Each property contains a distinct number in the range from 1 to the number of evaluation order properties on the template. These numbers are used to indicate the order in which the calculations are performed. If the user assigns a value to this property on a particular entity then the value on the other entities has to be modified. As usual we keep the other entities in the same relative order as the placement of this entity is modified. Set the property to zero to move this entity to the end of the evaluation order. By default each new entity is assigned -1 indicating the evaluation order is irrelevant. A user must explicitly assign a positive number (0 indicating the end of the current evaluation orders) if he intends to evaluate the entity in certain order. Parameters: EvaluationOrder  New place of this entity in the evaluation order. Either a specific place (using 1 to indicate the first evaluated entity) or use 0 to send this entity to the last place. Returns: Usual COM result code: S_OK

HRESULT IDSSTemplateMetric::EvaluationOrder (  [out, retval] Int32 *  pEvaluationOrder  )

Specifies when this unit is evaluated w. r.t. subtotals, other units etc.. EvaluationOrder is a numeric property. It records at what point in the evaluation of the items on this template this metric is evaluated. Many of the entities on a template are evaluated by having the DSS Analytical Engine carry out a calculation. The entities often refer to each other as part of their expressions. Unfortunately, it is not hard to come up with non-distributive expressions, that is with expression that have the property that a different answer is obtained depending on their order of evaluation. In a template we deal with this problem by using EvaluationOrder properties. Each metric, subtotal, consolidation and metric limit in the template has one of these properties. Each property contains a distinct number in the range from 1 to the number of evaluation order properties on the template. These numbers are used to indicate the order in which the calculations are performed. If the user assigns a value to this property on a particular entity then the value on the other entities has to be modified. As usual we keep the other entities in the same relative order as the placement of this entity is modified. Set the property to zero to move this entity to the end of the evaluation order. By default each new entity is assigned -1 indicating the evaluation order is irrelevant. A user must explicitly assign a positive number (0 indicating the end of the current evaluation orders) if he intends to evaluate the entity in certain order. Parameters: pEvaluationOrder  The current place of this entity in the evaluation order. Returns: Usual COM result code: S_OK

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

The metric's position in the metrics collection on this template. This property returns the index number of the metric among all the metrics appearing on this template. The metrics are indexed from one. Write to this property to change the position of this metric. If this metric is moved the other metrics are renumbered keeping the same relative order as they had before. Parameters: Index  New value of the index. Must be in range of course. Returns: Usual COM result code: S_OK

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

The metric's position in the metrics collection on this template. This property returns the index number of the metric among all the metrics appearing on this template. The metrics are indexed from one. Write to this property to change the position of this metric. If this metric is moved the other metrics are renumbered keeping the same relative order as they had before. Parameters: pIndex  Existing value of the index. Must be in range of course. Returns: Usual COM result code: S_OK

HRESULT IDSSTemplateMetric::IsDecomposed (  [in, defaultvalue(DssDecomposableDefault)] EnumDSSDecomposable  IsDecomposed  )

Whether the metric should be viewed as a composition of simpler metrics when calculating subtotals. This read-write property indicates whether the metric stored on the template unit should be viewed as a composition of simpler metrics when calculating subtotals. Here is the EnumDSSDecomposable enumeration that is used to set values for this property. Symbol Value Meaning DssDecomposableReserved 0 Never used. DssDecomposableDefault 1 Default to use the metric's IsDecomposable property. DssDecomposableFalse 2 Do not view the metric as a composition of simpler metrics when calculating subtotals. (Override the IsDecomposable property of the metric). DssDecomposableTrue 3 View the metric as a composition of simpler metrics when calculating subtotals. (Only valid when the metric's IsDecomposable property is DssDescomposableTrue). DssDecomposableOneLevel 4 Not used by this property. (Only useful for embedded metric). Returns: Usual COM result code: S_OK E_INVALIDARG Try to set the property to be a value other that the valid ones. DSSCOM_E_RESERVED_VALUE Try to set the property to be DssDecomposableReserved. OBJSVR_E_INCONSISTANT_SMARTTOTAL Try to set the property to be DssDecomposableTrue, but the metric itself is not DssDecomposableTrue.

HRESULT IDSSTemplateMetric::IsDecomposed (  [out, retval] EnumDSSDecomposable *  pIsDecomposed  )

Whether the metric should be viewed as a composition of simpler metrics when calculating subtotals. This read-write property indicates whether the metric stored on the template unit should be viewed as a composition of simpler metrics when calculating subtotals. Here is the EnumDSSDecomposable enumeration that is used to set values for this property. Symbol Value Meaning DssDecomposableReserved 0 Never used. DssDecomposableDefault 1 Default to use the metric's IsDecomposable property. DssDecomposableFalse 2 Do not view the metric as a composition of simpler metrics when calculating subtotals. (Override the IsDecomposable property of the metric). DssDecomposableTrue 3 View the metric as a composition of simpler metrics when calculating subtotals. (Only valid when the metric's IsDecomposable property is DssDescomposableTrue). DssDecomposableOneLevel 4 Not used by this property. (Only useful for embedded metric). Returns: Usual COM result code: S_OK E_INVALIDARG Try to set the property to be a value other that the valid ones. DSSCOM_E_RESERVED_VALUE Try to set the property to be DssDecomposableReserved. OBJSVR_E_INCONSISTANT_SMARTTOTAL Try to set the property to be DssDecomposableTrue, but the metric itself is not DssDecomposableTrue.

HRESULT IDSSTemplateMetric::MakeCurrentElement (   )

Make this TemplateMetric to be the current element. Make this TemplateMetric to be the current element. This method is not yet implemented. Returns: Usual COM result code: S_OK

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

The metric itself. The metric that appears in this object. It is persisted using its ObjectID. Parameters: pMetric  Should not be NULL. Returns: Usual COM result code: S_OK

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

The metric itself. The metric that appears in this object. It is persisted using its ObjectID. Parameters: ppMetric  Should not be NULL. Returns: Usual COM result code: S_OK

HRESULT IDSSTemplateMetric::MetricExports (  [out, retval] IDSSExports   ppExports  )

Exports into the metric property. This is a collection interface. It contains exports from this object into the metric object. It is not used to export prompts into the MetricPrompt property (use MetricPrompt.ExportsToPrompt to do this). If the Metric property is NULL then the exports will be NULL as well. Parameters: ppExports  Collection of exports into the metric property. Returns: Usual COM result code: S_OK

HRESULT IDSSTemplateMetric::MetricLimit (  [out, retval] IDSSExpression   ppMetricLimit  )

A (possibly empty) filter expression applied to this metric. A metric limit is a filter expression associated with a metric on the template. The SQL engine applies this filter, in addition to any global filter, when retrieving data for this metric to put it on the template. The reason to have a metric limit is to let users specify a different filter for each metric on the template. Also it can be more convenient to let the filtering appear in the template, rather than in the report definition's filter, or in the metric itself as conditionality. By default the metric limit expression is empty. This is exactly equivalent to saying that there is no metric limit expression. Parameters: ppMetricLimit  The expression interface used to enter the metric limit expression. The expression entered into this interface should be a valid filter expression involving the metric returned by the Metric property. Returns: Usual COM result code: S_OK

HRESULT IDSSTemplateMetric::MetricPrompt (  [in] IDSSPrompt *  pPrompt  )

Prompt property that can be used to set the metric property. MetricPrompt is a read-write prompt-valued property that can be used to define the metric property. Only Object prompts can be used to set this property. If the prompt is canceled or does not return any metrics then the template metric will be removed from the template metrics unit. If the prompt returns a single metric then it is used as the Metric property for this template unit. For any additional metrics (after the first one) new template metric objects is added to the template metrics unit right after the current one. Setting this property automatically sets the Metric to NULL. Parameters: pPrompt  The new value of the prompt. May be NULL. Prompt question = use as underlying prompt instance. Prompt instance (this object) = use this instance Other prompt instance = use underlying prompt object. Prompt object = use first instance in this object based on this prompt object. Returns: Usual COM result code: S_OK OBJSVR_E_NO_PROMPT_TYPE This prompt has not been given a prompt type. OBJSVR_E_CONFLICTS_PROMPT_TYPE Cannot use this prompt - it is not a suitable type.

HRESULT IDSSTemplateMetric::MetricPrompt (  [out, retval] IDSSPrompt   ppPrompt  )

Prompt property that can be used to set the metric property. MetricPrompt is a read-write prompt-valued property that can be used to define the metric property. Only Object prompts can be used to set this property. If the prompt is canceled or does not return any metrics then the template metric will be removed from the template metrics unit. If the prompt returns a single metric then it is used as the Metric property for this template unit. For any additional metrics (after the first one) new template metric objects is added to the template metrics unit right after the current one. Setting this property automatically sets the Metric to NULL. Parameters: ppPrompt  A prompt instance from the template that contains this unit. NULL if the TemplateMetric has no prompt. Returns: Usual COM result code: S_OK OBJSVR_E_NO_PROMPT_TYPE This prompt has not been given a prompt type. OBJSVR_E_CONFLICTS_PROMPT_TYPE Cannot use this prompt - it is not a suitable type.

---