IDSSReportManipulation Interface Reference

Inherited by IDSSReportManipulation2.

List of all members.

---

Detailed Description

The IDSSReportManipulation interface provides various methods for report manipulation operations and let the user to retrieve a result report instance that contains these changes.

The desired usage for this interface is as follows:

1. User obtains the IDSSReportManipulation interface from IDSSReportServices interface by passing in a report instance, a flags, and a user runtime.

2. User makes a sequence of report manipulation operations by calling various methods on the interface.

3. User can call the get_ManipulationType anytime to check the latest aggregated manipulation type.

4. User can call the validate methods (get_ValidationLevel and get_ValidationIssues) to check whether the report instance can be executed as a subset report of a base report. If the result fails, information about validation failures will be returned by the method.

5. User can call the Cancel method to forfeit all the report manipulation and the method will return the original report instance without any modification. Once the Cancel method is called, the user can no longer apply any additional manipulation on the report instance.

6. User can call the ApplyFix method to fix the problem that was found out by the subset validation so that the report can be executed as a subset report of a base report.

7. User can call the Accept method to retrieve the result report instance after she finishes all manipulations. Once the Accept method is called, the user can no longer apply any additional manipulation on the report instance.

Public Member Functions
HRESULT	Accept ([out] VARIANT_BOOL *pIsNewInstance,[out, retval] IDSSReportInstance ppReportInstance)
	The method lets the user retrieve the final report instance that includes all the modifications done by user.
HRESULT	AddDerivedMetric ([in] VARIANT *pInput,[in] Int32 Position,[in] BSTR Name,[in, optional] BSTR DisplayName)
	Adds a newly created metric to the subset template.
HRESULT	AddMetric ([in] IDSSObjectInfo *pObject,[in] Int32 Position,[in, optional] BSTR DisplayName)
	The method adds a metric or a prompt on metric to the view template.
HRESULT	AddPercentToTotalMetric ([in] IDSSMetric *pOriginalMetric,[in, defaultvalue(DssAxisNone)] Int32 AxesBitmap,[in, optional] IDSSCollection *pUnitsOnAxes,[in, optional] IDSSCollection *pUnits)
	Creates a "percent to total" metric starting from a given metric.
HRESULT	AddRankMetric ([in] IDSSMetric *pOriginalMetric,[in] VARIANT_BOOL Ascending,[in, optional] IDSSObjectInfo *pBreakByObject,[in, defaultvalue(FALSE)] VARIANT_BOOL Dynamic)
	Creates a "rank" metric starting from a given metric.
HRESULT	AddTransformationMetric ([in] IDSSMetric *pOriginalMetric,[in] IDSSRole *pRole,[in, defaultvalue(DssMetricFormulaIdentity)] EnumDSSMetricFormulaType eFormulaType)
	Creates a "transformation" metric starting from a given metric.
HRESULT	AddUnit ([in] IDSSObjectInfo *pObject,[in] Int32 AxisIndex,[in] Int32 UnitIndex,[in, optional] BSTR DisplayName)
	The method adds a template unit to the view template.
HRESULT	ApplyDeltaXML ([in] IDispatch *pDeltaXML,[in] IDSSXMLContext *pXMLContext,[out, retval] IDispatch ppElement)
	This method is used mainly for 4-tier manipulations.
HRESULT	ApplyFix ()
	The method fixes the problem that found out by the subset validation so that the report instance can be executed as a subset report of a base report.
HRESULT	ApplyGraphDelta ([in] IDispatch *pPropertiesXML)
	Apply the graph manipulations as described by the XML that's passed in.
HRESULT	ApplyObjectLock ([in] IDSSObjectInfo *pObject,[in] VARIANT_BOOL Value)
	Sets a boolean property on a template unit or a template metric corresponding to the given object, meaning that the object should not be removed from the subset report.
HRESULT	ApplyStyle ([in] VARIANT *pStyle)
	The method uses the Style passed in, and applies it to the template of the report (view template if this is a subset report).
HRESULT	AxisSubtotals ([in] EnumDSSAxisName Axis,[in] EnumDSSSubtotalStyle Style,[in] VARIANT *pSubtotal,[in] IDSSMetric *pMetric)
	The method adds an axis subtotal for a metric or all the metrics on the template.
HRESULT	Cancel ([out, retval] IDSSReportInstance ppReportInstance)
	The method lets the user cancel all the report manipulations applied so far and returns the original report instance without any modification.
HRESULT	ChangeDisplayName ([in] IDSSObjectInfo *pObject,[in] BSTR DisplayName)
	Changes the Alias (Display Name) of a given object on the template.
HRESULT	ClearTemplate ()
	Clears the subset template to a state similar to the one after creation.
HRESULT	ClearTemplateUnit ([in] IDSSObjectInfo *pObject)
	Clears the specified template unit to a state similar to the one after creation, with the difference that the metrics on the TemplateMetrics unit are preserved.
HRESULT	ConvertMetricIntoDerivedMetric ([in] IDSSMetric *pMetric)
	Note: This method is not supported in the 7.
HRESULT	FormatAxis ([in] EnumDSSAxisName Axis,[in] EnumDSSFormat Format,[in] IDispatch *pFormatXML)
	This method lets the user change a particular format on a particular axis.
HRESULT	FormatUnit ([in] IDSSObjectInfo *pObject,[in] EnumDSSFormat Format,[in] IDispatch *pFormatXML)
	This method lets the user change a particular format on a particular unit or metric.
HRESULT	HideBanding ([in] VARIANT_BOOL HideBanding)
	This method controls the hiding/showing of banding on the report.
HRESULT	HideSubtotals ([in] VARIANT_BOOL Value)
	This method controls the hiding/showing of subtotals on the template.
HRESULT	HideThresholds ([in] IDSSMetric *pMetric,[in] VARIANT_BOOL HideThresholds)
	This method controls the hiding/showing of thresholds for a particular metric or for all the metrics on the report.
HRESULT	Locale ([in] Int32 Locale)
	This read-write, numeric property represents a locale (combination of a location and language) to be used during certain manipulations.
HRESULT	Locale ([out, retval] Int32 *pLocale)
	This read-write, numeric property represents a locale (combination of a location and language) to be used during certain manipulations.
HRESULT	MakeNormal ()
	The method attempts to change a report to a normal (i.
HRESULT	ManipulationType ([out, retval] EnumDSSManipulationType *pManipulationType)
	The method lets the user retrieve the latest aggregated manipulation type.
HRESULT	PageBy ([in] BSTR ElementID)
	The method sets a current element on a template unit.
HRESULT	PivotUnit ([in] IDSSObjectInfo *pObject,[in] Int32 AxisIndex,[in] Int32 UnitIndex)
	The method moves a template unit from one place on a template to another.
HRESULT	RemoveInaccessibleMetrics ()
	This method checks and removes from the view template the metrics for which the user does not have Execute rights.
HRESULT	RemoveSorting ([in] EnumDSSAxisName Axis)
	Removes all sorting information (all sorts defined) on the given axis.
HRESULT	RemoveSubtotals ([in] IDSSMetric *pMetric)
	The method removes all subtotals associated with a metric or all metrics on the template.
HRESULT	RemoveUnit ([in] IDSSObjectInfo *pObject,[in, defaultvalue(TRUE)] VARIANT_BOOL TargetView)
	The method removes a template unit from either the view or the base template.
HRESULT	SetFilter ([in] IDSSFilter *pFilter,[in, defaultvalue(TRUE)] VARIANT_BOOL TargetView,[in, defaultvalue(DssEmbeddedModelInherit)] EnumDSSEmbeddedModel EmbeddedModel)
	Set a new filter to the report instance.
HRESULT	SetTemplate ([in] IDSSTemplate *pTemplate,[in, defaultvalue(TRUE)] VARIANT_BOOL TargetView,[in, defaultvalue(DssEmbeddedModelInherit)] EnumDSSEmbeddedModel EmbeddedModel)
	Set a new template to the report instance.
HRESULT	SetTemplatePrompt ([in] IDSSPrompt *pPrompt)
	This method sets the template prompt property on the base template.
HRESULT	Sort ([in] EnumDSSAxisName eAxis,[in] EnumDSSSortType eSortType,[in] VARIANT_BOOL Ascending,[in] EnumDSSSubtotalsPosition eSubtotalsPosition,[in] IDSSObjectInfo *pSortingObject,[in] VARIANT *pAdditionalInfo,[in] SAFEARRAY(BSTR)*pElementsArray)
	Adds a single key sort to a given axis, before any other existing sorts on the axis.
HRESULT	UnitSubtotals ([in] IDSSObjectInfo *pObject,[in] VARIANT_BOOL IsAdd,[in] VARIANT *pSubtotal,[in] IDSSMetric *pMetric)
	The method adds a unit subtotal for a metric or all the metrics on the template.
HRESULT	UpdateDerivedMetricExpression ([in] IDSSMetric *pMetric,[in] VARIANT *pInput,[in, optional] BSTR Name,[in, optional] BSTR DisplayName)
	Changes a derived metric by re-defining its expression.
HRESULT	ValidationIssues ([out, retval] IDSSValidationIssues ppValidationIssues)
	The report validator returns a collection of validation issues resulted from its checks on whether the report instance can be executed as a subset report of a base report (see also IDSSReportValidator).
HRESULT	ValidationLevel ([out, retval] EnumDSSValidationLevel *pValidationLevel)
	This property returns a code indicating whether the report instance can be executed as a subset report of a base report.

---

Member Function Documentation

HRESULT IDSSReportManipulation::Accept (  [out] VARIANT_BOOL *  pIsNewInstance, [out, retval] IDSSReportInstance   ppReportInstance )

The method lets the user retrieve the final report instance that includes all the modifications done by user. Once the user makes this call, she can no longer make any report manipulation operations on the report instance. Parameters: pIsNewInstance  Boolean property indicates whether the result report instance is the same as the one supplied by the user. ppReportInstance  The result report instance. It may be a different report instance than the one supplied by the user. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::AddDerivedMetric (  [in] VARIANT *  pInput, [in] Int32  Position, [in] BSTR  Name, [in, optional] BSTR  DisplayName )

Adds a newly created metric to the subset template. The metric is specified through an expression that can refer to metrics on the base report, other derived metrics, or even metrics from outside the report. It can also be specified as a reference to an existing metric, in which case this is used as an "original" from which an identical copy is made, embedded in the view template (see also the section below for exceptions). A derived metric is a metric that is on the view template but not on the base template, it is embedded in the view template and has IsDecomposable set to true. See also IDSSParserXgi for error values coming from the parser. The search sequence used, while parsing, for resolving a symbol S (name of an object) appearing in the expression is this (suggested by what the user is actually presented with on the screen): 1. Look for an object on the view template, having S as its Alias 2. Look for an object in the working set having S as its name 3. Look for an object in the metadata (the usual search) having S as its name In case of a name ambiguity at one stage, there is no attempt to recover and the manipulation fails. If a reference to a metric is provided through the pInput argument: If the metric is already existing on the view template, it is used as it is (not copied). However, if it is embedded into another container, an error will be issued. If the metric is already embedded into the view template (or its container), it will only be put on the template (not copied). If the metric is disabled, it will be enabled (not copied). If the metric is specified through a text expression, this cannot contain disabled metrics. This method can also create more general metrics, that are not, strictly, according to the definition given above, derived metrics. If the input metric specification does not obey the rules for a derived metric, the identical copy will be embedded in the base and will be referred from the view, i.e. it will reside on the view template; the new metric will have IsDecomposable set to false. (The final configuration created by the method in this case is similar to that of non-derived, SQL metrics). However, there are certain limitations. As an example, we don't allow the use of existing derived metrics in defining such non-derived metrics. As a general rule: use simple non-derived, SQL metrics as building blocks to define (more and more complex) derived metrics. Parameters: pInput  String (BSTR): The text-represented expression defining the new metric. Pointer: reference to a metric object. Position  The position of the metric in the template metrics unit. If it's 0, the metric will be added to the end of the collection. Name  The metric name. DisplayName  The metric alias on the template. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::AddMetric (  [in] IDSSObjectInfo *  pObject, [in] Int32  Position, [in, optional] BSTR  DisplayName )

The method adds a metric or a prompt on metric to the view template. If the metric is a disabled metric, it will be enabled. Parameters: pObject  The metric object or a prompt on metric object. It should not be NULL. Position  The position of the metric in the template metrics unit. If it's 0, the metric will be added to the end of the collection. DisplayName  The metric alias. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::AddPercentToTotalMetric (  [in] IDSSMetric *  pOriginalMetric, [in, defaultvalue(DssAxisNone)] Int32  AxesBitmap, [in, optional] IDSSCollection *  pUnitsOnAxes, [in, optional] IDSSCollection *  pUnits )

Creates a "percent to total" metric starting from a given metric. The equivalent formula for the new metric is: OriginalMetric / (Sum(OriginalMetric){...Dimensionality...}) The Dimensionality is determined by a set of template units specified by the caller through the arguments AxesBitmap, pUnitsOnAxes and pUnits. It gives the level at which the subtotal is calculated (notice that this is the denominator's dimensionality). The following is an outline of how the subtotal level is determined (the bitmap model makes it clear what happens when more than one specification type (argument) for the axes/units is used): 1. For each axis on the template, a bitmap is created, with one bit per template unit. 2. Walk the caller's "Axes" specification (AxesBitmap) and set the bits in the axes bitmaps accordingly, i.e.: if an axis is specified, then set to 1 all the bits of the corresponding bitmap: 3. Walk the "Units on axes" specification (pUnitsOnAxes) and, for every unit identified, mark the corresponding bit and all the bits coming after it in its axis bitmap. 4. Walk the "standalone Units" specification (pUnits) and, for every unit identified, mark (only) the corresponding bit on its axis bitmap. 5. If nothing was specified for Pages and Chapters, then flip (complement bits of) all bitmaps. Else, if anything was specified for Pages or for Chapters, do nothing. 6. Build the dimensionality for the denominator metric by walking the bitmaps and adding dimensionality units (of type Attribute) for all bits that are set in the bitmaps that correspond to a template unit of type attribute. The new metric is in fact a derived metric and has all the related characteristics. Also: Values returned by the AddDerivedMetric manipulation. The grid format of the new metric is set to "percent". The original metric cannot be a disabled metric. The new metric receives a default name that reflects the corresponding formula. The name is localized using the current Locale property set on the manipulator. Parameters: pOriginalMetric  The original metric object. It should not be NULL. AxesBitmap  An axis bitmap, with bit values coming from the EnumDSSAxesBitMap enumeration. For each axis specified through a set bit, all units on the axis are considered in determining the subtotal level. pUnitsOnAxes  A collection of objects, each identifying a template unit. In determining the subtotal level, each unit is considered, together with all units coming after it on its axis. Default is NULL. pUnits  A collection of objects, each identifying a template unit. In determining the subtotal level, each unit (and only it) is considered. Default is NULL. Returns: Usual COM result code: S_OK DSSCOM_E_OBJECT_NOT_FOUND The original metric was not found on the template.

HRESULT IDSSReportManipulation::AddRankMetric (  [in] IDSSMetric *  pOriginalMetric, [in] VARIANT_BOOL  Ascending, [in, optional] IDSSObjectInfo *  pBreakByObject, [in, defaultvalue(FALSE)] VARIANT_BOOL  Dynamic )

Creates a "rank" metric starting from a given metric. The equivalent formula for the new metric is: Rank(OriginalMetric). The sort direction (Ascending) is set as a property on the Rank operator node. The BreakByObject determines the (unit of the) special dimensionality (of type BreakBy) attached to the metric. The new metric is in fact a derived metric and has all the related characteristics. The original metric cannot be a disabled metric. The new metric receives a default name that reflects the corresponding formula. The name is localized using the current Locale property set on the manipulator. Currently, the BreakByObject argument has to specify a unit that, together with the units coming after it on the axis, has to be of type Attribute (a Metrics unit is also accepted in subsequent units). Parameters: pOriginalMetric  The original metric object. It should not be NULL. Ascending  Specifies the sort direction. pBreakByObject  Specifies the template unit over which we rank. It ultimately determines the BreakBy level of the rank. Default is NULL Dynamic  (Currently not used) Returns: Usual COM result code: S_OK DSSCOM_E_OBJECT_NOT_FOUND The original metric was not found on the template. Or: The BreakBy object was not found on the template.

HRESULT IDSSReportManipulation::AddTransformationMetric (  [in] IDSSMetric *  pOriginalMetric, [in] IDSSRole *  pRole, [in, defaultvalue(DssMetricFormulaIdentity)] EnumDSSMetricFormulaType  eFormulaType )

Creates a "transformation" metric starting from a given metric. First, an Identity metric is created; it is equivalent to the original metric with additional transformation (pRole) information attached. If required, another metric is created based on the formula type, the original and the Identity metric. The equivalent formulae/results, based on the formula type, are: EnumDssMetricFormulaIdentity: IdentityMetric EnumDssMetricFormulaDifference: IdentityMetric - OriginalMetric EnumDssMetricFormulaRatio: (IdentityMetric - OriginalMetric) / OriginalMetric The Identity metric is not a derived metric: it is added to (and embedded into) the base report template, and causes SQL execution. In the case of the IdentityMetric formula type, it is also put on the view template (to be seen on the grid). In the other 2 formula cases, the metrics defined on the basis of the Identity metric are, in fact, derived metrics and have all the related characteristics. The original metric cannot be a disabled metric or a compound metric (therefore, it cannot be a derived metric). The Identity metric, once created for a given original metric, will be reused when creating other transformation metrics based on that original metric. Adding a transformation metric in the case of a linked (non-embedded base) template is not allowed. In the case of EnumDssMetricFormulaRatio, the grid format of the new metric is set to "percent". The new metric receives a default name that reflects the corresponding formula. Parameters: pOriginalMetric  The original metric object. It should not be NULL. pRole  The transformation Role object (e.g. Last Year Role, etc.). It should not be NULL. eFormulaType  The type of final formula desired. It has values from the enumeration EnumDSSMetricFormulaType. Returns: Usual COM result code: S_OK DSSCOM_E_OBJECT_NOT_FOUND The original metric was not found on the template. Or: The Role object was not found.

HRESULT IDSSReportManipulation::AddUnit (  [in] IDSSObjectInfo *  pObject, [in] Int32  AxisIndex, [in] Int32  UnitIndex, [in, optional] BSTR  DisplayName )

The method adds a template unit to the view template. The object should be an attribute, a custom group, a consolidation, a metric, a dimension or a prompt. Parameters: pObject  The object can be an attribute, custom group, consolidation, dimension, metric or prompt. It should not be NULL AxisIndex  The axis index. UnitIndex  The unit index. DisplayName  The alias Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::ApplyDeltaXML (  [in] IDispatch *  pDeltaXML, [in] IDSSXMLContext *  pXMLContext, [out, retval] IDispatch   ppElement )

This method is used mainly for 4-tier manipulations. It can be used as an indirect entry point for many other methods of this interface. The "pDeltaXML" parameter will list the manipulations requested by user in XML format, and the intermediate results (again in XML format) are returned in "ppElement". Parameters: pDeltaXML  List of manipulations requested by user in XML format. pXMLContext  XML working context. ppElement  Intermediate results in XML format. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::ApplyFix (   )

The method fixes the problem that found out by the subset validation so that the report instance can be executed as a subset report of a base report. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::ApplyGraphDelta (  [in] IDispatch *  pPropertiesXML  )

Apply the graph manipulations as described by the XML that's passed in. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::ApplyObjectLock (  [in] IDSSObjectInfo *  pObject, [in] VARIANT_BOOL  Value )

Sets a boolean property on a template unit or a template metric corresponding to the given object, meaning that the object should not be removed from the subset report. The "lock" is not enforced (it is only a suggestion) and is to be used at client's discretion. Parameters: pObject  The object can be an attribute, custom group, consolidation dimension or metric. A NULL reference specifies the template metrics unit. Value  Whether the lock is to be set or cleared. Returns: Usual COM result code: S_OK DSS_COM_OBJECT_NOT_FOUND The given metric was not found on the report(s).

HRESULT IDSSReportManipulation::ApplyStyle (  [in] VARIANT *  pStyle  )

The method uses the Style passed in, and applies it to the template of the report (view template if this is a subset report). Applying a style object will change the formatting of the template to match the style. Parameters: pStyle  String -> Style object name Object -> Style object Returns: Usual COM result code: S_OK DSSCOM_E_KEY_NOT_FOUND The Style object could not be found by name.

HRESULT IDSSReportManipulation::AxisSubtotals (  [in] EnumDSSAxisName  Axis, [in] EnumDSSSubtotalStyle  Style, [in] VARIANT *  pSubtotal, [in] IDSSMetric *  pMetric )

The method adds an axis subtotal for a metric or all the metrics on the template. Parameters: Axis  The axis name, i.e., DssAxisRows, DssAxisColumns, and DssAxisPages. Style  The axis subtotal style, i.e., DssSubtotalNone, DssSubtotalGrandTotal, DssSubtotalOutline, and DssSubtotalCube pSubtotal  The definition of the subtotal. This is either an enumeration constant (e.g., EnumDSSMetricType that corresponds to a system subtotal) or a subtotal object. pMetric  The metric to which the subtotal should apply. If the parameter is NULL, the subtotal is applied to all metrics on the template. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::Cancel (  [out, retval] IDSSReportInstance   ppReportInstance  )

The method lets the user cancel all the report manipulations applied so far and returns the original report instance without any modification. Once the user makes the call, she can no longer make any report manipulation operations on the report instance. Parameters: ppReportInstance  The original report instance without any modification. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::ChangeDisplayName (  [in] IDSSObjectInfo *  pObject, [in] BSTR  DisplayName )

Changes the Alias (Display Name) of a given object on the template. This method can also change the display name of a disabled metric. Parameters: pObject  Specifies the object that determines the template unit or the template metric to have the Alias changed. If NULL, the template metrics unit's Alias is changed. DisplayName  The value for the new Alias. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::ClearTemplate (   )

Clears the subset template to a state similar to the one after creation. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::ClearTemplateUnit (  [in] IDSSObjectInfo *  pObject  )

Clears the specified template unit to a state similar to the one after creation, with the difference that the metrics on the TemplateMetrics unit are preserved. Basically the unit is removed, and then re-added to the template in the same position. Parameters: pObject  The object that determines the template unit. It can be an attribute, custom group, consolidation or dimension. If NULL, the template metrics unit is considered. Returns: Usual COM result code: S_OK DSSCOM_E_OBJECT_NOT_FOUND The object could not be found on the template.

HRESULT IDSSReportManipulation::ConvertMetricIntoDerivedMetric (  [in] IDSSMetric *  pMetric  )

Note: This method is not supported in the 7. 2 release. Converts an existing metric, on the subset or base report, to a derived metric (if appropriate). Parameters: pMetric  The metric object. It should not be NULL. Returns: Usual COM result code: S_OK DSS_COM_OBJECT_NOT_FOUND The given metric was not found on the report(s).

HRESULT IDSSReportManipulation::FormatAxis (  [in] EnumDSSAxisName  Axis, [in] EnumDSSFormat  Format, [in] IDispatch *  pFormatXML )

This method lets the user change a particular format on a particular axis. The user specifies what properties to set or unset on the format by passing in an XML node that contains properties in XML (see IDSSSource2 documentation for more on the XML structure). Parameters: Axis  The Axis to be modified. Format  The Format to be modified. pFormatXML  XML that contains properties that need to be set or unset on the format. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::FormatUnit (  [in] IDSSObjectInfo *  pObject, [in] EnumDSSFormat  Format, [in] IDispatch *  pFormatXML )

This method lets the user change a particular format on a particular unit or metric. The user specifies the template unit by passing in the relevant DSSObject (e.g. attribute or metric). If the user passes in NULL, then the Metrics unit will be modified. The user specifies what properties to set or unset on the format by passing in an XML node that contains properties in XML (see IDSSSource2 documentation for more on the XML structure). Parameters: pObject  Object -> corresponds to a template unit or template metric. NULL -> indicates that the Metrics unit should be modified Format  The Format to be modified. pFormatXML  XML that contains properties that need to be set or unset on the format. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::HideBanding (  [in] VARIANT_BOOL  HideBanding  )

This method controls the hiding/showing of banding on the report. Parameters: HideBanding  Banding will be hidden for VARIANT_TRUE, not hidden otherwise. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::HideSubtotals (  [in] VARIANT_BOOL  Value  )

This method controls the hiding/showing of subtotals on the template. Parameters: Value  Subtotals will be hidden for VARIANT_TRUE, not hidden otherwise. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::HideThresholds (  [in] IDSSMetric *  pMetric, [in] VARIANT_BOOL  HideThresholds )

This method controls the hiding/showing of thresholds for a particular metric or for all the metrics on the report. The method achieves its effect by disabling/enabling the thresholds of the template metric corresponding to the given metric, or of all template metric objects. Parameters: pMetric  The metric for which the thresholds are to be hidden/shown. If null, thresholds will be hidden/shown for all metrics on the report. HideThresholds  Thresholds will be hidden for VARIANT_TRUE, not hidden otherwise. Returns: Usual COM result code: S_OK

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

This read-write, numeric property represents a locale (combination of a location and language) to be used during certain manipulations. Currently, it is used by some of the manipulations that create metrics (e.g. AddPercentToTotalMetric) in the construction of localized default names for the metrics. The enumeration of values for Locale is taken from the Win32 API. The default value is LOCALE_USER_DEFAULT. Parameters: Locale  New value for the Locale property Returns: Usual COM result code: S_OK

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

This read-write, numeric property represents a locale (combination of a location and language) to be used during certain manipulations. Currently, it is used by some of the manipulations that create metrics (e.g. AddPercentToTotalMetric) in the construction of localized default names for the metrics. The enumeration of values for Locale is taken from the Win32 API. The default value is LOCALE_USER_DEFAULT. Parameters: pLocale  Current value for the Locale property Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::MakeNormal (   )

The method attempts to change a report to a normal (i. e. non-subset report). If the report is already a normal report, or if it needs to be a subset report, then this method will do nothing. If this method succeeds in changing the report then it will be considered a SQL manipulation. We say that a report does not need to be a subset report if we do not gain anything from having the subset. For example, if the report has an empty view filter, and a view template that is identical to the base template, then there's no need for this report to be a subset report. When a subset report is changed to a normal report, it uses the view template and base filter as its filter template combination. We do this, because the view template is properly formatted while the base template may not be. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::ManipulationType (  [out, retval] EnumDSSManipulationType *  pManipulationType  )

The method lets the user retrieve the latest aggregated manipulation type. The definition of enumeration EnumDSSManipulationType is as follows: DssManipulationNone 0 The report instance is still valid. DssManipulationFormat 1 The report instance needs to be reformatted. DssManipulationPivot 2 The report instance needs to be cross-tabbed again. DssManipulationSubset 3 The new data can be obtained by applying a subset operation. DssManipulationSQL 4 The new data can be obtained by regenerating SQL. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::PageBy (  [in] BSTR  ElementID  )

The method sets a current element on a template unit. The template unit to which the current element applies is determined by information stored in the ElementID. The method sets the current element for any unit even if the unit is not on the page axis. Parameters: ElementID  The Element ID Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::PivotUnit (  [in] IDSSObjectInfo *  pObject, [in] Int32  AxisIndex, [in] Int32  UnitIndex )

The method moves a template unit from one place on a template to another. If no object is specified, we interpret it as moving the template metrics unit. If the object identifies a template attribute unit replacing a template dimension unit, we will move the template dimension instead of the template attribute. The operation will result in a Pivot manipulation. Parameters: pObject  The object to be moved. NULL indicates the template metrics unit. AxisIndex  The axis to which the unit should be moved. If it is out of range, we move the unit to the row axis. UnitIndex  The unit position on the axis to which the unit should be moved. If it is out of range, we move the unit to the end of the axis. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::RemoveInaccessibleMetrics (   )

This method checks and removes from the view template the metrics for which the user does not have Execute rights. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::RemoveSorting (  [in] EnumDSSAxisName  Axis  )

Removes all sorting information (all sorts defined) on the given axis. Parameters: Axis  The axis to have the sorting removed. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::RemoveSubtotals (  [in] IDSSMetric *  pMetric  )

The method removes all subtotals associated with a metric or all metrics on the template. Parameters: pMetric  The metric whose subtotals should be removed. If the parameter is NULL, all subtotals will be removed. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::RemoveUnit (  [in] IDSSObjectInfo *  pObject, [in, defaultvalue(TRUE)] VARIANT_BOOL  TargetView )

The method removes a template unit from either the view or the base template. If no object is specified, we interpret it as removing the template metrics unit. Parameters: pObject  The object can be an attribute, custom group, consolidation dimension or metric. If it's NULL, it is interpreted as the template metrics unit. TargetView  True if the manipulation targets on the view, otherwise it targets on the base report. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::SetFilter (  [in] IDSSFilter *  pFilter, [in, defaultvalue(TRUE)] VARIANT_BOOL  TargetView, [in, defaultvalue(DssEmbeddedModelInherit)] EnumDSSEmbeddedModel  EmbeddedModel )

Set a new filter to the report instance. The EmbeddedModel controls the embedded model of the result filter. DssEmbeddedModelInherit means the manipulation won't change the embedded relationship of the original filter. If it is embedded originally, the result filter is still embedded. Otherwise, it is still linked. Basically, the manipulation will populate the filter definition and property with the given one. DssEmbeddedModelEmbed means the result filter will be embedded in the report definition. If the original filter is embedded, the manipulation will completely populate the filter with the given one. If the original filter is linked, it will be discarded and a new embedded filter will be created and populated with the given one. DssEmbeddedModelLink means the result filter will be linked in the report definition. The manipulation will make an identical copy of the given filter and link the new one to the report definition. The TargetView indicates whether the view filter or the base filter should be changed. If the TargetView is set to true, the manipulation will replace the definition of the view filter with the one passed in. If the flag is set to false, the manipulation will replace the definition of the base filter with it. Note that the EmbeddedModel will only control the embed model of the base filter. For the view filter, the manipulation will not alter the original embed model. Basically, it will always use DssEmbeddedModelInherit to handle the view filter. Parameters: pFilter  The filter object. It should not be NULL TargetView  True if the manipulation targets on the view, otherwise it targets on the base report. EmbeddedModel  Control the result filter's embedded model, either embedded or linked or do not change the original model Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::SetTemplate (  [in] IDSSTemplate *  pTemplate, [in, defaultvalue(TRUE)] VARIANT_BOOL  TargetView, [in, defaultvalue(DssEmbeddedModelInherit)] EnumDSSEmbeddedModel  EmbeddedModel )

Set a new template to the report instance. The EmbeddedModel controls the embedded model of the result template. DssEmbeddedModelInherit means the manipulation won't change the embedded relationship of the original template. If it is embedded originally, the result template is still embedded. Otherwise, it is still linked. Basically, the manipulation will populate the template's definition and property with the given one. DssEmbeddedModelEmbed means the result template will be embedded in the report definition. If the original template is embedded, the manipulation will completely populate the template with the given one. If the original template is linked, it will be discarded and a new embedded template will be created and populated with the given one. DssEmbeddedModelLink means the result template will be linked in the report definition. The manipulation will make an identical copy of the given template and link the new one to the report definition. The TargetView indicates whether the view template or the base template should be changed. If the TargetView is set to true, the manipulation will replace the definition of the view template with the one passed in. If the flag is set to false, the manipulation will replace the definition of both the view template and the base template with it. Note that the EmbeddedModel will only control the embed model of the base template. For the view template, the manipulation will not alter the original embed model. Basically, it will always use DssEmbeddedModelInherit to handle the view template. The enumeration EnumDSSEmbeddedModel is defined as follows DssEmbeddedModelReserved Hidden. Never used DssEmbeddedModelInherit The manipulation won't change the embedded relationship of the original template. DssEmbeddedModelEmbed The result template will be embedded in the report definition. DssEmbeddedModelLink The result template will be linked in the report definition Parameters: pTemplate  The template object. It should not be NULL. TargetView  True if the manipulation targets on the view, otherwise it targets on the base report. EmbeddedModel  Control the result template's embedded model, either embedded or linked or do not change the original model Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::SetTemplatePrompt (  [in] IDSSPrompt *  pPrompt  )

This method sets the template prompt property on the base template. This method can be used to clear the template prompt property by passing in NULL. Parameters: pPrompt  Prompt object. May be NULL Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::Sort (  [in] EnumDSSAxisName  eAxis, [in] EnumDSSSortType  eSortType, [in] VARIANT_BOOL  Ascending, [in] EnumDSSSubtotalsPosition  eSubtotalsPosition, [in] IDSSObjectInfo *  pSortingObject, [in] VARIANT *  pAdditionalInfo, [in] SAFEARRAY(BSTR)*  pElementsArray )

Adds a single key sort to a given axis, before any other existing sorts on the axis. An n-key sort can be specified through a sequence of calls to this method, in reverse order of the keys and without clearing the sorts between the calls. The sorting object, if present, also specifies the axis - therefore, the two arguments have to be compatible. Note on the hierarchical sort - the interpretation/use of the subtotal (AdditionalInfo) argument: If it is null, nothing is set (and the metric's default subtotal will be considered at execution). If provided: A search is done, among the template's subtotals, for one that corresponds to the caller-supplied subtotal definition and metric. If more than one: First, the Axis info is used: we choose the one that's on the given axis. Then, we'll take the one with a better match based on type: we choose DssTemplateSubtotalList over DssTemplateSubtotalDefinition (Note that we do not consider the DssTemplateSubtotalDefault/All types) If we still have an ambiguity, we'll just choose the first one encountered. If a template subtotal is found, it is set as the Subtotal property's value of the Sort object. Note that if the subtotal is not "turned on" (is not on the axis) we do not turn it on automatically, and no error will be signaled. If no template subtotal is found, we will return an error. Parameters: eAxis  The axis to have the sort added. eSortType  The type of sort to be added. Ascending  The direction of the sort. eSubtotalsPosition  Specifies a change, from this sort on, in how the subtotals are positioned. pSortingObject  The sorting object. pAdditionalInfo  - For an attribute sort, the attribute form to sort on (IDSSAttributeForm) For a hierarchical sort, the subtotal definition, as one of the following: An EnumDSSMetricType value specifying a subtotal (from DssMetricSubtotalSum to DssMetricSubtotalGeometricMean) A reference (IDSSMetric) to a subtotal definition The DSSID (BSTR) of a subtotal definition (metric) For a custom group sort, a value from the EnumDSSOrderParentFirst enumeration specifying the position of parent elements relative to child elements. The options are: parent first, children first and default (in which case the decision on the parent-children order will be made based on the setting of the IsParentFirst property of the related custom group object). pElementsArray  For a metric sort, the collection of elements determining the exact vector (on the grid) that will drive the sort. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::UnitSubtotals (  [in] IDSSObjectInfo *  pObject, [in] VARIANT_BOOL  IsAdd, [in] VARIANT *  pSubtotal, [in] IDSSMetric *  pMetric )

The method adds a unit subtotal for a metric or all the metrics on the template. Parameters: pObject  The object on the template to which the subtotal should be applied. IsAdd  Whether the subtotal should be added or removed. pSubtotal  The definition of the subtotal. This is either an enumeration constant (e.g., EnumDSSMetricType that corresponds to a system subtotal) or a subtotal object. pMetric  The metric to which the subtotal should apply. If the parameter is NULL, the subtotal is applied to all metrics on the template. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::UpdateDerivedMetricExpression (  [in] IDSSMetric *  pMetric, [in] VARIANT *  pInput, [in, optional] BSTR  Name, [in, optional] BSTR  DisplayName )

Changes a derived metric by re-defining its expression. This is done either by re-parsing the expression from a text formula, or by copying the expression from a "source" metric (in which case an identical copy is used). See also IDSSParserXgi.doc for error values coming from the parser. The rules used in resolving the names during parsing are the same as those described at the AddDerivedMetric manipulation. A request with a metric which is not embedded, in either the subset or base report, will fail. A disabled metric can be updated using this method. Recursive definitions (the new expression refers to the metric being updated) are not allowed. The updating of a derived metric with an input expression corresponding to a non-derived metric is not allowed. Parameters: pMetric  The Metric object. It should not be null. pInput  String (BSTR): A text-represented expression used for re-parsing. Pointer: reference to a "source" metric whose expression is to be copied into the expression of the new metric. Name  The metric name. DisplayName  The metric alias. Returns: Usual COM result code: S_OK DSS_COM_OBJECT_NOT_FOUND The given metric was not found on the report(s).

HRESULT IDSSReportManipulation::ValidationIssues (  [out, retval] IDSSValidationIssues   ppValidationIssues  )

The report validator returns a collection of validation issues resulted from its checks on whether the report instance can be executed as a subset report of a base report (see also IDSSReportValidator). This property of the manipulator provides access to the collection of issues. In the case of validation level "recoverable", issues can be "fixed" by calling the ApplyFix method, such that execution as a subset is possible. As an example of issue: the missing, from the base template, of a "leaf" metric used by / needed to evaluate a derived metric. Returns: Usual COM result code: S_OK

HRESULT IDSSReportManipulation::ValidationLevel (  [out, retval] EnumDSSValidationLevel *  pValidationLevel  )

This property returns a code indicating whether the report instance can be executed as a subset report of a base report. The definition of enumeration EnumDSSValidationLevel is as follows: DssValidationGood 1 The resulting report can be completely executed as a subset of a base report. DssValidationRecoverable 2 The resulting report can be executed as a subset of a base report, but some cells may be empty. DssValidationFatal 3 The resulting report cannot be executed as a subset of a base report. DssValidationBadApplyOrder 4 The resulting report can be executed as a subset of a base report, but the result may not be the one expected. DssValidationCircularAction 5 If user chooses to automatically fix the validation issue, it will undo an action the user requested before. Returns: Usual COM result code: S_OK

---