This section provides the syntax and design of functions, procedures, modifiers, and keywords that are used in expressions in the RPAS calculation engine. There are important distinctions between each of these definitions.
Functions are separated into two types: single result functions and multiple result functions.
Functions (single result) – Mechanisms for performing operations within an expression that are controlled and executed by the calculation engine.
Functions are most commonly used in RPAS.
Most functions in base RPAS return only a single measure.
Calculation engine controls and executes the evaluation of a function.
Functions may be used in expressions with other functions and keywords.
Multiple result functions – Similar to the features and behavior of single result functions, but with semantic and syntactic differences.
There can be more than one left-hand side (result) measure that can be specified implicitly by position in the expression or explicitly by label.
Left-hand side measures have to be at same intersection; however, the calendar hierarchy can be dropped or added.
The result(s) from a multiple result function cannot be used as arguments to another function, nor can the result(s) be chained with other operations to form long expression.
Expressions can be used as arguments to multiple result functions.
Multiple result functions cannot be part of a cycle group.
Procedures are mechanisms for performing operations in an expression where the calculation engine controls the execution, which is performed by the procedure itself.
Procedures can only use measures or scalars
Procedure executes the evaluation (instead of RPAS/calculation engine), but the calculation engine still controls protection processing, sequence of calculation, when the procedure is called, and so on.
Procedures can have multiple arguments on the left and right hand sides.
Procedures cannot be used with functions, other procedures, keywords, and certain modifiers.
Because of their flexibility and the control available to the developer, procedures can be used for a wide variety of special calculations and activities.
Procedures require a different syntax. The syntax uses “<-“ instead of “=” in the expression.
Modifiers directly modify the source or destination of measures, to override the level, aggregation type, position, and so on.
Modifier Syntax
<measure>.<modifier>
Keywords appear in expressions or as arguments inside functions to return specific data values.
The syntax is as quick and straightforward to implement as possible. Function names, keywords, and so on are currently in lowercase.
Keywords are allowed, but they are kept to a minimum. Function parameters are comma separated and may be optional; however, they are positional, so that the absence of a parameter needs to be specified by commas if a subsequent parameter is supplied.
The table below displays the syntax conventions used in this procedure.
|
Indicator |
Definition |
|
[…] |
All options listed in brackets are optional. |
|
{…|…} |
Options listed in “{}” with “|” separators are mutually exclusive (either/or). |
|
{…,…} |
Options listed in “{}” with “,” separators way are a complete set. |
|
Bold |
Labels. |
|
Italics |
Italics indicate a temporary placeholder for a constant or a measure. |
|
Italics/meas |
This indicates that the placeholder can be either a constant or a measure. |
|
Bold Italics |
This indicates a numeric placeholder for the dynamic portion of a label. Usually a number from 1 to N. |
|
Normal |
Normal text signifies required information. |
|
Underlined |
This convention is used to identify the function or procedure name. |
The following is the functional syntax used in this document:
Large square brackets [ ] are used to indicate an optional parameter.
Small square brackets [ ] are part of the expression syntax and are used to specify a hierarchy, dimension, and/or position.
Large braces { } indicate a choice where one of the items (which will be separated by a pipe sign "|" ) must be selected.
Small braces {} are part of the expression syntax, and are used to specify a measure set for functions that accept a variable number of arguments (that is, {<measureset>} ).
Parameters of a specific type (such as expressions or dimension names) are shown in angle brackets <>.
A plus “+” sign is used to specify an intersection, which is done by connecting two or more dimension specifications.
Keywords, modifiers, function names, and procedure names are shown in bold.
Many functions in RPAS require the specification of a hierarchy, dimension, or a combination thereof, to define the level at which an expression is evaluated. When defining the hierarchy and dimension names in expressions square brackets [ ] must be used.
In the document, the following syntax is used to designate a hierarchy and dimension:
Hierarchy, Dimension, and Position Syntax
[<hierarchy>].[<dimension>].[[<position>]]
Note: position is noted as optional because it can only be specified in a limited number of functions.
For simplicity of parsing and clarity of rule writing, the <hierarchy> must be supplied in all cases, even when, as in calendar index functions, it might be implied from the context. Functions that require a hierarchy and dimension specification have standard validation rules whereby [<hierarchy>] must be a valid hierarchy name, [<dimension>] must be a valid dimension in [<hierarchy>], and [<position>] must be a valid position name in [<dimension>]. If the position name starts with a number, the position name must be nested in a pair of double quotes. In some functions or procedures, one of the hierarchical keywords top, bottom, or current (used conditionally based on context) can be used to specify the dimension. Should this validation fail, an error will be generated.
Some functions (such as cover) have what are referred to as "inverse" functions. This is required, as all expressions in a rule group must be algorithmic inverses of each other. Each function states whether it has an inverse, and, if so, what the syntax of the inverse is.
An inverse function is only relevant when the function encompasses the whole of the expression. Functions embedded in longer expressions do not have inverses, though the expression itself may have an inverse as long as the measure being "solved" for is not an input into the function. Functions that have inverses usually have enough scope in their syntax to cover the eventualities that would typically cause them to be embedded in longer expressions (such as code to prevent an error result).
The following special syntax should be used for functions with multiple results.
The left-hand side measures in a multiple result expression are comma-separated and can be identified by a labeling mechanism.
Label Syntax
<measure>:<label>
Valid label names are specified by the multiple result function syntax. If a multiple result function specifies valid labels, the function can be used in an expression without specifying all possible results. The multiple result function itself is aware of which results are being stored and may be able to run faster by skipping the computation of unneeded results.