Format
Initial([Suffix] [,CallingDataObjectType])
Returns
Returns the name of the initial calling data object or fetches it by appending a suffix to it, depending on the parameters.
Inputs
Suffix: If this parameter is null (default) then the name of the initial calling data object will be returned. If this parameter is a string, it will be appended to the name of the calling data object and it will be evaluated/fetched.
Behaviour: Optional
Dimensions: SingleValue
Valid data types: Null, String
CallingDataObjectType: The type of the calling data object to filter by in the call stack. Valid values are: CalculationDataset, CalculationTag and Entity (default). If this parameter is omitted, the function will return an entity name (see note at end of the Call Stack Example).
Behaviour: Optional
Dimensions: SingleValue
Valid data types: String
How it Works
The Initial(), Current(), and Caller() functions work by using an internal call stack to fetch the name of an entity. These functions operate in a similar way to the Entity keyword, and are useful for creating templated calculations.
Whenever an attribute value is evaluated, the name of the entity is added to an internal stack and these functions allow you to access these names from the stack. It is important to note that these functions operate based on this internal call stack, and not on hierarchies.
The call stack lives only during the evaluation of an expression, and every expression which is being evaluated (i.e. every request sent to P2 Server) has its own call stack. Each item in the call stack has an associated type, which shows what was added. The type can be a calculation dataset, calculation tag, or entity.
The Initial() function is different to the Caller() and Current() functions, in that it operates from the other end of the call stack. Initial() always gets the very first entry from the call stack, that is, the one that started the calculation chain. This function is useful when you don't know how deep the call stack would be.
Call Stack Example
During the evaluation of an expression, P2 Server creates an internal call stack and the Current() function allows you to access information from this call stack.
If you have the following configuration with Archer, Ballard, and Cattle entities, then during the evaluation of {Archer:Choke}, the call stack will look like this:
| Expression | Call stack (with type) |
| {Archer:Choke} | Archer - entity |
| {Ballard:Choke} | Ballard - entity Archer - entity |
| {Cattle:Choke} | Cattle - entity Ballard - entity Archer - entity |
Now let's create a calculation tag called {Calculation} and point {Cattle:Choke} to this tag, so that {Calculation}={Cattle:Choke}. In this scenario, Archer calls Ballard, which calls Cattle, which calls Calculation.
When {Calculation} is evaluated, the call stack will be:
- Calculation (this is the name of the expression being evaluated) – calculation tag
- Cattle – entity
- Ballard – entity
- Archer – entity (this is the top of the call stack, and the starting point for Initial())
Now, let's assign different expressions to {Calculation} so we can see what the outcomes would be, given the above call stack:
| Calculation | Result | Notes |
| {Calculation} = Current() | Cattle | The CallingDataObjectType parameter defaults to filter the stack by entity. |
| {Calculation} = Caller(0) | Cattle | This is similar to Current(). |
| {Calculation} = Caller(-1) | Ballard | The CallingDataObjectType parameter defaults to filter the stack by entity. |
| {Calculation} = Caller(-2) | Archer | The CallingDataObjectType parameter defaults to filter the stack by entity. |
| {Calculation} = Caller(-3) | Error | Returns an error since the call stack is not that deep. |
| {Calculation} = Initial() | Archer | The CallingDataObjectType parameter defaults to filter the stack by entity. |
| {Calculation} = Initial(null, "CalculationTag") | Calculation | The CallingDataObjectType parameter filters the stack by calculation tag. |
Note: By default, functions that use the call stack search for entity names. If you want the calculation name when using Initial(), then you should pass "CalculationTag" as the last parameter i.e. Initial(null, "CalculationTag").
So, the call stack can vary what Initial() is pointing to, depending on what the function is passing for the CallingDataObjectType. I.e. If it’s looking for entities, then Initial() will look for the first entity type on the call stack, not necessarily the first thing on the call stack.
Using the Calculation Tester
The Calculation Tester is unable to process expressions using the Initial(), Caller(), and Current() functions, because the required entity call stack is not exposed by the Calculation Editor.
These types of expressions would work only if they are evaluated through attribute values. For testing purposes, we recommend replacing these calls with the desired entity names in the Calculation Editor.
Examples
Expression: Initial()
Result: Returns the name of the entity that triggered the evaluation.
Expression: Initial("[Oil Producing Well]:Choke")
Result: Appends "[Oil Producing Well]:Choke" to the name of the first entity it finds on the call stack, and evaluates the generated expression.
Expression: Initial(null, "CalculationTag")
Result: Returns the name of the first calculation tag it finds from the call stack.
Expression: Initial("Value", "CalculationTag")
Result: Appends "Value" to the name of the first calculation tag it finds on the call stack, and evaluates the generated expression.