{"id":28028,"date":"2017-06-16T15:07:18","date_gmt":"2017-06-16T07:07:18","guid":{"rendered":"http:\/\/localhost\/help\/?page_id=28028"},"modified":"2024-07-04T16:12:46","modified_gmt":"2024-07-04T08:12:46","slug":"initial","status":"publish","type":"page","link":"https:\/\/oihelp.corporate.ifs.com\/help\/p2-server\/calculations\/initial\/","title":{"rendered":"Initial()"},"content":{"rendered":"\n

Format<\/h2>\n

Initial([Suffix] [,CallingDataObjectType])<\/strong><\/p>\n

Returns<\/h2>\n

Returns the name of the initial calling data object or fetches it by appending a suffix to it, depending on the parameters.<\/p>\n

Inputs<\/h2>\n

Suffix: <\/b>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.
\nBehaviour: Optional
\nDimensions: SingleValue
\nValid data types: Null, String<\/p>\n

CallingDataObjectType: <\/b>The type of the calling data object to filter by in the call stack. Valid values are: CalculationDataset, CalculationTag and Entity (default).\u00a0If this parameter is omitted, the function will return an entity name (see note at end of the Call Stack Example).
\nBehaviour: Optional
\nDimensions: SingleValue
\nValid data types: String<\/p>\n

How it Works<\/h2>\n

The\u00a0Initial(), Current<\/a>(), and Caller<\/a>() functions work by using an internal call stack to fetch the name of an entity.\u00a0These functions operate in a similar way to the Entity<\/em> keyword<\/a>, and are useful for creating templated calculations<\/a>.<\/p>\n

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.\u00a0<\/p>\n

The call stack lives only during the evaluation of an expression, and every expression which is being evaluated (i.e. every request sent to IFS OI Server) has its own call stack. Each item in the call stack has an associated type<\/em>, which shows what was added. The type can be a calculation dataset, calculation tag, or entity.<\/p>\n

The Initial() function is different to the Caller() and Current() functions, in that it operates from the other end of the call stack.\u00a0Initial() 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.<\/p>\n

Call Stack Example<\/strong><\/p>\n

During the evaluation of an expression, IFS OI Server creates an internal call stack and the Current() function allows you to access information from this call stack.\u00a0<\/p>\n

If you have the following configuration with Archer, Ballard, and Cattle entities, then during the evaluation of {Archer:Choke}<\/em>, the call stack will look like this:<\/p>\n\n\n\n\n\n\n
Expression<\/strong><\/td>\nCall stack (with type)<\/strong><\/td>\n<\/tr>\n
{Archer:Choke}<\/td>\nArcher - entity<\/td>\n<\/tr>\n
{Ballard:Choke}<\/td>\nBallard - entity
\nArcher - entity<\/td>\n<\/tr>\n
{Cattle:Choke}<\/td>\nCattle - entity
\nBallard - entity
\nArcher - entity<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Now let's create a calculation tag called {Calculation}<\/strong> and point {Cattle:Choke} to this tag, so that {Calculation}={Cattle:Choke}.\u00a0In this scenario, Archer<\/em> calls Ballard<\/em>, which calls Cattle<\/em>, which calls Calculation<\/em>.<\/p>\n

When {Calculation} is evaluated, the call stack will be:<\/p>\n

    \n
  1. Calculation (this is the name of the expression being evaluated)\u00a0<\/em>\u2013 calculation tag<\/li>\n
  2. Cattle \u2013 entity<\/li>\n
  3. Ballard \u2013 entity<\/li>\n
  4. Archer \u2013 entity (this is the top of the call stack, and the starting point for Initial())<\/em><\/li>\n<\/ol>\n

    Now, let's assign different expressions to\u00a0{Calculation} so we can see what the outcomes would be, given the above call stack:<\/p>\n\n\n\n\n\n\n\n\n\n\n
    Calculation<\/strong><\/td>\nResult<\/strong><\/td>\nNotes<\/strong><\/td>\n<\/tr>\n
    {Calculation} = Current()<\/td>\nCattle<\/td>\nThe CallingDataObjectType parameter defaults to filter the stack by entity.<\/em><\/td>\n<\/tr>\n
    {Calculation} = Caller(0)<\/td>\nCattle<\/td>\nThis is similar to Current()<\/em>.<\/td>\n<\/tr>\n
    {Calculation} = Caller(-1)<\/td>\nBallard<\/td>\nThe CallingDataObjectType parameter defaults to filter the stack by entity.<\/em><\/td>\n<\/tr>\n
    {Calculation} = Caller(-2)<\/td>\nArcher<\/td>\nThe CallingDataObjectType parameter defaults to filter the stack by entity.<\/em>\u00a0<\/td>\n<\/tr>\n
    {Calculation} = Caller(-3)<\/td>\nError<\/em><\/td>\nReturns an error since the call stack is not that deep.<\/td>\n<\/tr>\n
    {Calculation} = Initial()<\/span><\/td>\nArcher<\/span><\/td>\nThe CallingDataObjectType parameter defaults to filter the stack by entity.<\/em><\/span><\/td>\n<\/tr>\n
    {Calculation} =\u00a0Initial(null, \"CalculationTag\")<\/span><\/td>\nCalculation<\/span><\/td>\nThe CallingDataObjectType parameter filters the stack by calculation tag.<\/em><\/span><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

    Note: By default, functions that use the call stack search for entity<\/strong> names. If you want the calculation<\/em> name when using Initial(), then you should pass \"CalculationTag\" as the last parameter i.e. Initial(null, \"CalculationTag\")<\/em>.
    \n<\/em>So, the call stack can vary what Initial() is pointing to, depending on what the function is passing for the CallingDataObjectType<\/em>. I.e. If it\u2019s looking for entities, then Initial() will look for the first entity<\/em> type on the call stack, not necessarily the first thing on the call stack.<\/p>\n

    Using the Calculation Tester<\/h2>\n

    The Calculation Tester<\/a>\u00a0is unable to process expressions using the Initial(),\u00a0Caller<\/a>(), and Current<\/a>() functions, because the required entity call stack is not exposed by the Calculation Editor<\/a>.<\/p>\n

    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.<\/p>\n

    Examples<\/h2>\n

    Expression: Initial()<\/span>
    \nResult: Returns the name of the entity that triggered the evaluation.<\/p>\n

    Expression: Initial(\"[Oil Producing Well]:Choke\")<\/span>
    \nResult: Appends \"[Oil Producing Well]:Choke\" to the name of the first entity it finds on the call stack, and evaluates the generated expression.<\/p>\n

    Expression: Initial(null, \"CalculationTag\")<\/span>
    \nResult: Returns the name of the first calculation tag it finds from the call stack.<\/p>\n

    Expression: Initial(\"Value\", \"CalculationTag\")<\/span>
    \nResult: Appends \"Value\" to the name of the first calculation tag it finds on the call stack, and evaluates the generated expression.<\/p>\n

     <\/p>\n","protected":false},"excerpt":{"rendered":"

    Returns the name of the initial calling data object or fetches it by appending a suffix to it, depending on the parameters.<\/p>\n

    Read more<\/i><\/a><\/p>\n","protected":false},"author":1,"featured_media":28078,"parent":3650,"menu_order":124,"comment_status":"closed","ping_status":"closed","template":"","meta":{"footnotes":"","_members_access_role":[],"_members_access_error":""},"categories":[9],"tags":[100],"class_list":["post-28028","page","type-page","status-publish","has-post-thumbnail","hentry","category-tech-ref","tag-calculations","Version-4-5-1","Product-srv"],"_links":{"self":[{"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/pages\/28028","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/comments?post=28028"}],"version-history":[{"count":2,"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/pages\/28028\/revisions"}],"predecessor-version":[{"id":67798,"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/pages\/28028\/revisions\/67798"}],"up":[{"embeddable":true,"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/pages\/3650"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/media\/28078"}],"wp:attachment":[{"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/media?parent=28028"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/categories?post=28028"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/oihelp.corporate.ifs.com\/help\/wp-json\/wp\/v2\/tags?post=28028"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}