IDSSTemplateMetrics Interface Reference

Detailed Description

The IDSSTemplateMetrics interface is exposed as part of the definition of a template.

It contains a collection of all the metrics that appears on the template.

Public Member Functions

HRESULT _NewEnum ([out, retval] IUnknown pp_NewEnum)

Enumerator for this collection.

HRESULT Add ([in] IDSSObjectInfo *pInfo,[out, retval] IDSSTemplateMetric ppTemplateMetric)

Insert a new member into the collection.

HRESULT Count ([out, retval] Int32 *pCount)

The number of metrics in this 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 Item ([in] VARIANT *pIndex,[out, retval] IDSSTemplateMetric ppTemplateMetric)

Access a member of the collection by index number or ID.

HRESULT MetricLimit ([out, retval] IDSSExpression ppMetricLimit)

A (possibly empty) filter expression applied to metrics on the unit.

HRESULT MetricLimitType ([in] EnumDSSMetricLimitType MetricLimitType)

The way of defining metric limits.

HRESULT MetricLimitType ([out, retval] EnumDSSMetricLimitType *pMetricLimitType)

The way of defining metric limits.

HRESULT MetricsPrompt ([in] IDSSPrompt *pPrompt)

Prompt that can be used to define the collection of template metrics.

HRESULT MetricsPrompt ([out, retval] IDSSPrompt ppPrompt)

Prompt that can be used to define the collection of template metrics.

HRESULT Remove ([in] VARIANT *pMember)

Delete a member from the collection.

HRESULT TemplateUnit ([out, retval] IDSSTemplateUnit ppTemplateUnit)

The IDSSTemplateUnit interface.

Member Function Documentation

HRESULT IDSSTemplateMetrics::_NewEnum ( [out, retval] IUnknown pp_NewEnum )

Enumerator for this collection.
This is the standard property used to return the objects in a collection. It returns an enumerator object. Calling methods on the enumerator object retrieves the contents of the collection.
After the enumerator object has been obtained it is possible for both the members of the collection to change. The effect of this change on the members of the collection that are returned by the enumeration object is implementation dependent.

Note that the user does not retrieve the contents of the collection until he or she calls the Next method on the enumerator object. This property does not presuppose that all of the objects are retrieved simultaneously.

Parameters:

pp_NewEnum An IUnknown pointer to the enumerator object. The object is returned using the standard IEnumVARIANT interface.

Returns:
Usual COM result code:

S_OK

HRESULT IDSSTemplateMetrics::Add ( [in] IDSSObjectInfo * pInfo,

[out, retval] IDSSTemplateMetric ppTemplateMetric

)

Insert a new member into the collection.
Insert an object into the collection for a new metric.
This call returns the existing template metric if this metric is already in the collection.

Parameters:

pInfo This metric, as a DSS Object, to be added to the collection.

ppTemplateMetric The template metric object for this metric.

Returns:
Usual COM result code:

S_OK

HRESULT IDSSTemplateMetrics::Count ( [out, retval] Int32 * pCount )

The number of metrics in this template.
Returns the number of objects in this collection.
Parameters:

pCount The number of objects in this collection.

Returns:
Usual COM result code:

S_OK

HRESULT IDSSTemplateMetrics::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 Metric Limit on this template 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 IDSSTemplateMetrics::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 Metric Limit on this template 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 IDSSTemplateMetrics::Item ( [in] VARIANT * pIndex,

[out, retval] IDSSTemplateMetric ppTemplateMetric

)

Access a member of the collection by index number or ID.
Return a template metric from the collection. The index parameter can take one of several forms.
The contents of the collection are numbered from 1 to Count.

Parameters:

pIndex Number = index number into the collection of the desired object. String = ID of the desired metric. Pointer = reference to an IDSSMetric object.

ppTemplateMetric The requested member of the collection. NULL if none was found

Returns:
Usual COM result code:

S_OK

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

A (possibly empty) filter expression applied to metrics on the unit.
The metric limit is a filter expression associated with metrics on the template. The SQL engine will apply this filter, in addition to any global filter, when retrieving data for these metrics to put it on the template. The reason to have metric limit is to let users specify a different filter for metrics 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 each 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.

Returns:
Usual COM result code:

S_OK

HRESULT IDSSTemplateMetrics::MetricLimitType ( [in] EnumDSSMetricLimitType MetricLimitType )

The way of defining metric limits.
The property specifies the way of defining metric limits
Here is the EnumDSSMetricLimitType enumeration that is used to set values for this property.

Symbol Value Meaning

DssMetricLimitReserved 0 Never used

DssMetricLimitAND 1 AND individual expressions (Default)

DssMetricLimitOR 2 OR individual expressions

DssMetricLimitExpression 3 A single metric limit expression is applied to entire template

Returns:
Usual COM result code:

S_OK

HRESULT IDSSTemplateMetrics::MetricLimitType ( [out, retval] EnumDSSMetricLimitType * pMetricLimitType )

The way of defining metric limits.
The property specifies the way of defining metric limits
Here is the EnumDSSMetricLimitType enumeration that is used to set values for this property.

Symbol Value Meaning

DssMetricLimitReserved 0 Never used

DssMetricLimitAND 1 AND individual expressions (Default)

DssMetricLimitOR 2 OR individual expressions

DssMetricLimitExpression 3 A single metric limit expression is applied to entire template

Returns:
Usual COM result code:

S_OK

HRESULT IDSSTemplateMetrics::MetricsPrompt ( [in] IDSSPrompt * pPrompt )

Prompt that can be used to define the collection of template metrics.
MetricsPrompt is a read-write prompt-valued property that can be used to define the template metrics collection of this object.
Only Object prompts can be used to set this property. If the prompt is canceled or does not return any metrics then the template unit is removed from the template. Otherwise, each metric returned by the prompt is added as a template metric to our collection.

Setting this property automatically clears our collection.

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 hasn't been given a prompt type.

OBJSVR_E_CONFLICTS_PROMPT_TYPE Can't use this prompt - it is not a suitable type.

HRESULT IDSSTemplateMetrics::MetricsPrompt ( [out, retval] IDSSPrompt ppPrompt )

Prompt that can be used to define the collection of template metrics.
MetricsPrompt is a read-write prompt-valued property that can be used to define the template metrics collection of this object.
Only Object prompts can be used to set this property. If the prompt is canceled or does not return any metrics then the template unit is removed from the template. Otherwise, each metric returned by the prompt is added as a template metric to our collection.

Setting this property automatically clears our collection.

Parameters:

ppPrompt A prompt instance from the template that contains this unit. NULL if the TemplateMetrics has no prompt.

Returns:
Usual COM result code:

S_OK

OBJSVR_E_NO_PROMPT_TYPE This prompt hasn't been given a prompt type.

OBJSVR_E_CONFLICTS_PROMPT_TYPE Can't use this prompt - it is not a suitable type.

HRESULT IDSSTemplateMetrics::Remove ( [in] VARIANT * pMember )

Delete a member from the collection.
Remove an object from the collection. The object to be removed can be referred to in several different ways depending on the type used in the VARIANT argument.
Removing a metric from this collection does not remove it from the project. It does delete the TemplateMetric.

Parameters:

pMember Number = index number into the collection of the desired object. String = ID of the desired object. Pointer = reference to an IDSSMetric object.

Returns:
Usual COM result code:

S_OK

HRESULT IDSSTemplateMetrics::TemplateUnit ( [out, retval] IDSSTemplateUnit ppTemplateUnit )

The IDSSTemplateUnit interface.
This property returns the IDSSTemplateUnit interface on this unit. This interface is used to access a few common properties for all template units. Most notably it records where the unit appears on the template. It also contains a Properties collection.
This interface is also available by calling QueryInterface.

Returns:
Usual COM result code:

S_OK


Public Member Functions
HRESULT	_NewEnum ([out, retval] IUnknown pp_NewEnum)
	Enumerator for this collection.
HRESULT	Add ([in] IDSSObjectInfo *pInfo,[out, retval] IDSSTemplateMetric ppTemplateMetric)
	Insert a new member into the collection.
HRESULT	Count ([out, retval] Int32 *pCount)
	The number of metrics in this 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	Item ([in] VARIANT *pIndex,[out, retval] IDSSTemplateMetric ppTemplateMetric)
	Access a member of the collection by index number or ID.
HRESULT	MetricLimit ([out, retval] IDSSExpression ppMetricLimit)
	A (possibly empty) filter expression applied to metrics on the unit.
HRESULT	MetricLimitType ([in] EnumDSSMetricLimitType MetricLimitType)
	The way of defining metric limits.
HRESULT	MetricLimitType ([out, retval] EnumDSSMetricLimitType *pMetricLimitType)
	The way of defining metric limits.
HRESULT	MetricsPrompt ([in] IDSSPrompt *pPrompt)
	Prompt that can be used to define the collection of template metrics.
HRESULT	MetricsPrompt ([out, retval] IDSSPrompt ppPrompt)
	Prompt that can be used to define the collection of template metrics.
HRESULT	Remove ([in] VARIANT *pMember)
	Delete a member from the collection.
HRESULT	TemplateUnit ([out, retval] IDSSTemplateUnit ppTemplateUnit)
	The IDSSTemplateUnit interface.