Format
Caller(Depth [,Suffix] [,CallingDataObjectType])
Returns
Returns the name of the calling data object or fetches it by appending a suffix to it, depending on the parameters.
Inputs
Depth: The index of the calling data object in the call stack. 0 indicates the currently processed data object, -1 is the caller of the currently processed data object, -2 is the caller of the caller of the currently processed data object, and so on.
Behaviour: Required
Dimensions: SingleValue
Valid data types: Integer
Suffix: If this parameter is null (default) then the name of the 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). The function will filter the call stack by the CallingDataObjectType first and then apply the Depth parameter to find the requested entry. 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 Caller(), Initial(), and Current() 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.
Call Stack Example
During the evaluation of an expression, P2 Server creates an internal call stack and the Caller() 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
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 | This is similar to Caller(0). |
| {Calculation} = Caller(0) | Cattle | To get the name of the calculation, use Caller(0,"", CalculationTag") |
| {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} = Caller(-4) | Error | Returns an error since the call stack is not that deep |
| {Calculation} = Initial() | Archer |
Note: By default, functions that use the call stack search for entity names. If you want the calculation name when using Current() or Caller(0), then you should pass "CalculationTag" as the last parameter i.e. Caller(0, null, "CalculationTag").
So, the call stack Depth index can vary what it points to, depending on what the function is passing for the CallingDataObjectType. I.e. If it’s looking for entities, then Caller(0) 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 Caller(), Initial(), 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: Caller(0)
Result: Returns the name of the current entity which is being processed. This is similar to using the Entity keyword.
Expression: Caller(-1)
Result: Returns the name of the calling entity.
Expression: Caller(-1, "[Oil Producing Well]:Choke")
Result: Appends "[Oil Producing Well]:Choke" to the name of the calling entity and evaluates the generated expression.
Expression: Caller(-1, null, "CalculationTag")
Result: Returns the name of the calling calculation tag.
Expression: Caller(-1, "Value", "CalculationTag")
Result: Appends "Value" to the name of the calling calculation tag and evaluates the generated expression.
Expression: Caller(-1, ":Choke") * 1.4
Result: Will multiply the value of the Choke attribute attached to the calling entity by 1.4.
Expression: Caller(-1, ":Choke!Current Position") * 1.4
Result: Will multiply the Current Position attribute value of the Choke attribute attached to the calling entity by 1.4.
Expression: DDGet("P2 Corporate", 1, Caller(-1), ":Choke!Current Position", "", "Oil Producing Well")
Result: Will return the value of the current choke position attached to the calling entity, for Oil Producing Wells in the P2 Corporate hierarchy.