ALLOCATE statement (PEL)
The ALLOCATE statement distributes a cost or resource from a source MemberSet to a destination MemberSet that receives the distribution. The ALLOCATE statement can apply when the source and the destination are in a single model or apply when the source MemberSet and the destination MemberSet belong to different models.
When the source MemberSet and the destination MemberSet are in different models, the process is referred to as cross-model allocation. When ALLOCATE performs a cross-model allocation, also provides member mapping that creates a one-to-one correspondence between members of the source model and members of the destination model.
ALLOCATE (
Target,
Source,
Ratio
[,
Cross_model_mapping_source,
Cross_model_mapping_target,
] )
Parameters
- Target
Specifies the set of cells to receive the allocation. Must be of type Scope.
- Source
Specifies the source of an allocation relative to the Target. Must be of type Number.
- Ratio
Specified a scaling factor to be applied to the Source. Must be of type Number.
- Cross-Model Mapping Source
Specifies the members of the source model to be mapped to target model members. Must be of type Scope.
- Cross-Model Mapping Target
Specifies the members in the target model that correspond to source model members. Must be of type Scope.
Remarks
Member mapping for cross-model allocation is necessary when a misalignment occurs between dimensions or dimension members in two different models. That is, when the dimensions in one model do not have a one-to-one correspondence with the dimensions in a second model. For example, when a destination model contains a dimension that is not part of the source model, a dimension misalignment exists.
In such a case, you must define the correspondence with the cross-model mapping parameters.
Different kinds of allocation rules have different restrictions regarding parameters in the Allocate statement.
Single-model allocation rules
Rules that perform allocations in a single model, or single-model allocation rules, allow parameter use without restriction. That is, you can use parameters of any type to represent an argument in a single-model allocation rule.
PushCrossModelAllocation rule
A PushCrossModelAllocation rule is saved to the source model, and is said to push data to a different model called the destination model.
In a PushCrossModelAllocation rule, you can use parameters of any type to represent the Target, Source, or Ratio arguments. If you use a parameter to represent the Target, Source, or Ratio arguments, the evaluated parameter expression must match the data type of the argument.
You may not use parameters of any kind to represent the Cross-Model Mapping Source or Cross-Model Mapping Target arguments.
Note
If you use a member or member set parameter for Target or Source, the value will always refer to the source model. Thus, if you use a rule with such a parameter in a job, the user permissions are determined by the user security scope in the source model. User permissions in the Target model do not affect the parameter reference.
PullCrossModelAllocation rule
A PullCrossModelAllocation rule is saved to the destination model, and is said to pull data from the source model.
In a PullCrossModelAllocation rule, you can use parameters of primitive type to represent the Target, Source, or Ratio arguments. That is, you can use parameters of type Integer, Real, String, or Boolean to represent these arguments. You may not use arguments of type Member or Member Set.
You may not use parameters of any kind to represent the Cross-Model Mapping Target or Cross-Model Mapping Target arguments.
Single model example
The following example is taken from the Alpine Ski House sample application included with Planning Business Modeler. This example shows how to use an ALLOCATE statement to allocate a percent of revenue to a corporate forecast where all allocations are in a single model.
/* Outer scope */
SCOPE (
{[Scenario].[All Members].[BaseCase],
[Scenario].[All Members].[DownCase],
[Scenario].[All Members].[UpCase]},
[Time].[Annual].[Year2005]: [Time].[Annual].[Year2009],
[BusinessProcess].[Standard].[ALLOC],
[Currency].[ASH_Currency].[USD],
[Flow].[All Members].[None],
[Entity].[LegalEnt].[U],
[Account].[SummaryAcct].[680001]);
ALLOCATE (
/* Destination scope (U.S.). This scope is a further restriction of the outer scope */
(
[Account].[SummaryAcct].[680001],
[Currency].[ASH_Currency].[USD],
[Entity].[LegalEnt].[U],
[BusinessProcess].[Standard].[ALLOC]
),
// Source value to allocate, in USD
(
[Account].[SummaryAcct].[680001],
[Entity].[LegalEnt].[A1],
[Currency].[ASH_Currency].[USD],
[BusinessProcess].[Standard].[ALLOC]
),
// Ratio value (U and A1 in USD)
(
([Account].[SummaryAcct].[680001],
[Entity].[LegalEnt].[U],
[Currency].[ASH_Currency].[USD],
[Scenario].[All Members].[Actuals],
[Time].[Annual].[Year2004],
[BusinessProcess].[Standard].[INPUT])
/
([Account].[SummaryAcct].[680001],
[Entity].[LegalEnt].[A1],
[Currency].[ASH_Currency].[USD],
[Scenario].[All Members].[Actuals],
[Time].[Annual].[Year2004] ,
[BusinessProcess].[Standard].[INPUT])
)
);
END SCOPE;
Cross-model example
In a cross-model allocation, the rule must specify a one-to-one mapping between the members of the source model and the members of the destination model.
In a cross-model allocation, member correspondence is established by position. If a destination model has a dimension that does not occur in the source model, we recommend that you explicitly create a mapping to a NONE member. Otherwise, the PEL compiler detects an error and the rule fails to validate.
The following example shows a cross-model allocation rule taken from the Alpine Ski House sample application that is included with Planning Server. This example calculates corporate allocation balances for resorts in the US. The rule uses an identity ratio, which means that the destination values should match the values in the source cells. In addition, the rule creates a cross model mapping that maps source account values to destination accounts that have the same account number in the FLOW dimension.
Note
In a cross-model allocation, the SCOPE expression refers to the source model.
/* Outer scope */
SCOPE(
[Scenario].[All Members].[Actuals],
[Time].[Monthly].[January Year2003]:[Time].[Monthly].[September Year2004],
[BusinessProcess].[Standard].[Input],
[TimeDataView].[All Members].[PERIODIC],
{ [Account].[ExpAcct].[680001],[Account].[ExpAcct].[690001]},
[Currency].[ASH_Currency].Members,
[Entity].[ResortEnt].[ASHR].LeafMembers,
[Product].[LOB].[NONE]
);
ALLOCATE(
// Members receiving distribution.
// this keyword indicates Destination has same members as outer scope
*/
this,
// Source to be distributed.
// () indicates same as value in current tuple */
(),
// Ratio of source to destination.
// 1 indicates same
1,
// Begin cross-model parameters.
// Maps ExpAcct -> ResortAcct with matching account numbers
// Cross-model source members (ExpAcct)
(
{[Account].[ExpAcct].[680001],[Account].[ExpAcct].[690001]}
),
// Cross-model destination members (ResortAcct)
(
{[Account].[ResortAcct].[680001],[Account].[ResortAcct].[690001]}
)
);
END SCOPE;