User-defined aggregation function

In order to run application specific aggregation rules, a user-defined aggregation function may be implemented in the class based on the aggregation schema. Attributes maintained by the user-defined aggregation function do not require a data source (assignment). Only one user defined aggregation function may be defined in an aggregation schema, which should maintain all unassigned attributes (except transient attributes) in theAGGREGATION schema. User defined aggregation function is called after running default aggregation functions

User-defined aggregation functions must be implemented as methods of the VIEW data type, i.e. user-defined aggregation functions are not available for ad-hoc aggregations.Aggregation functions are instance functions that are called for each instance in the calling object collection (partition). The calling object for the aggregation function, however, is the aggregation or view instance.

In theVIEW definition, the aggregation function is called without parameters. The implementation of the function requires, however, additional parameters, which are passed when calling the function internally:

bool MyAggregation::Aggregate( set<void> &partition,

AggregationOptions option )

The partition or calling object property is passed internally for providing extended information. The aggregation function must not change the selection state in the partition, since the selection state is used for iterating. When being aware of this fact, the aggregation function may also change the selection state, e.g. in order to skip instances.

When running the aggregation process, the function is called with option InitAggregation in order to initialize a new grouping level instance and AddLow for updating grouping level instance data. Depending on aggregation model type, the function might also be called with AddHigh option in order to update higher level aggregation instances.

Following aggregation options must be supported in a user-defined Aggregate() function:

• InitAggregation (0) - Initialize aggregation values. The function is called when a new grouping instance or a new aggregation instance has been created. The partition parameter may contain an invalid property handle.
• AddLow (1) - Add low level instance (grouping instance) or maintain high level aggregation instance. The partition property passed contains the source instance to be aggregated (selected instance in subset of source collection).
• AddHigh (2) - Add high level instance (aggregation instance). The partition property passed contains the aggregation instance to be aggregated on higher level (selected instance in aggregation collection).
• SubtractLow (-1) - The function is called when a low level instance in the source collection has been deleted or updated (before aggregating the new instance). The partition property passed contains the source instance to be subtracted (selected instance in subset of source collection).

• SubtractHigh (-2) - The function is called when an aggregation instance has been updated. The aggregation property passed contains the aggregation instance to be subtracted.

User-defined aggregation functions have to update the proper value(s) in the aggregation instance. When the aggregation option indicates a high level aggregation operation (2), the property handle passed in partition contains the lower level aggregation instance to be aggregated.

Disaggregation is called in order to update (persistent) aggregation instances properly when source data changes, in order to "subtract" the old value (removing a partition instance or changing its value). When changing the value, the aggregate function is called first with SubtractLow before calling it once again with AddLow in order to "add" the new value(s).

Calling aggregation functions is managed by type context class functions aggregationUpdate() and aggregationRemove(), which may be called from source type event handlers when data has been updated or removed.

Since source instances an aggregation is based on may change, (persistent) aggregation collections should be maintained in order to keep those up-to-date. Otherwise, the aggregation collection has to be recreated from time to time.

Maintaining aggregation collections becomes (usually) possible when the aggregation schema is based on a persistent collection, i.e. when the FROM parameter refers to a persistent collection. Updating aggregation collections is supported by aggregationUpdate() and aggregationRemove() context class functions, which might be called in doBeforeStore() and doBeforeRemove() event handler functions in the type context class of the source collection data type.

aggregationUpdate() and aggregationRemove() subtract the old source instance value (instance before being updated) from the low level grouping instance and all affected aggregation instances. Then, aggregationUpdate() adds the new instance to the corresponding grouping instance and all affected aggregation instance. When dimension values have been updated (explicitly or implicitly), add and subtract usually apply on different aggregation instances.