Skip to content

Formula Modeling

Jump to bottom
Johannes Heucher edited this page Oct 12, 2022 · 4 revisions

Figure 1: Formula Modeling in Mappings Figure 2: Formula Modeling in Conditional Choice Figure 3: Formula Modeling in Conditional Branching Figure 4: Formula Modeling in Templates Figure 5: Formula Modeling in Query Storable

Formula Modeling is used to model complex terms like condition and assignment terms inside the Xyna Process Modeller. It is an essential tool for the following Modeling Blocks:

  • Mappings: Every assignment term has to be modeled by Formula Modeling (cf. fig. 1).
  • Conditional Choices: The Boolean condition term is needed for the Conditional Choice's true/false decisions (cf. fig. 2).
  • Conditional Branching: The Conditional Branching supports a kind of split Formula Modeling. There is a common condition fragment and one condition fragment on every case, except for the default. Together they build a Boolean condition term for each case (cf. fig. 3).
  • Templates: Templates mainly consist of pure text content. Data Types in addition can be dragged into this text to serve as Parameter for specific string-based values during runtime. Formula Modeling is used to work with these Parameters (cf. fig. 4).
  • Query Storable: The filter conditions, sort criteria and the selected data can be modeled with Formula Modeling (cf. fig. 5).
Most of the time the modeled terms are working with certain instances of Data Types. A condition for example checks specific values of some Member Variables of a given source parameter. Mappings also have target parameters, which are the target of an assignment. Source or target parameters of a term are comparable to a Service's Input or Output Parameters.

Table of Contents

Term Constituents

Operators

  • Assignment (only with Mappings): Assignments can be done either directly between a Mapping's Input and Output Parameters or by accessing their Member Variables. The user can decide what shall be done with each of the values hanging on the source parameters.
    • Deep clone (default) (:=): Source parameters and their Member Variables are cloned.
    • Shallow clone (~=): Source parameters are cloned, their Member Variables are referenced.
  • Bracket terms (()): Brackets can be used to change the calculation order of the different term parts.
  • Access to lists ([]): If lists are involved in the assignments, the user can either access single list elements or use the complete list. The single list elements are referenced by square brackets and an index value, e.g. [0].
  • Simple calculations: Combine several values with one of the following arithmetic operators:
    • Summation (+)
    • Subtraction (-)
    • Multiplication (*)
    • Division (÷)
  • Boolean calculations: Combine several values with one of the following Boolean operators:
    • Equals (=)
    • Not equals (≠)
    • ≥, >, ≤, <
    • AND
    • OR
    • NOT (!)
  • Typecasts (#cast()): A given Data Type instance can be casted to a specific subtype of this Data Type (#cast<full></full>).
  • Placeholder (?): The placeholder ? will be substituted by other term fragments forming the final term for evaluation (only Conditional Choice and Conditional Branching).

Functions

A set of static functions amplifies the possible calculations between several values:

  • String-based functions
    • concat (S1, S2, S3, ...):String : Combines one or more parameters into a single string.
    • contains (S, SearchString):Boolean : Checks if a string contains a specified search string.
    • endswith (S, SearchString):Boolean : Checks if a string ends with a certain sequence.
    • glob (S, SearchString):Boolean : Checks if a string matches a certain sequence that contains wildcards * (arbitrary number of arbitrary characters) and ? (one arbitrary character).
    • indexof (S, SearchString):Integer : Returns the index of the first occurrence of the search string within the input string.
    • length (S):Integer : Returns the length of a string.
    • matches (S, RegExp):Boolean : Checks if a string matches a certain regular expression.
    • replaceall (S, RegExp, SubstituteString):String : Returns a string S where all occurrences of the search regular expression RegExp are substituted by a replacement string SubstituteString.
      Please note: Backslashes \ and dollar signs $ in the replacement string have a special meaning and are used for matching groups of the regular expression. Therefore those may cause the result to be different from a result with a literal replacement string.
    • startswith (S, SearchString):Boolean : Checks if a string starts with a certain sequence.
    • substring (S, StartIndex, EndIndex):String : Returns a sequence of a string that is enclosed by StartIndex and EndIndex. The EndIndex is optional and will be replaced by the length of S if missing.
    • tolowercase (S):String : Returns a string with all capital letters converted into lowercase letters.
    • touppercase (S):String : Returns a string with all capital letters converted into capital letters.
    • xpath (Xml, LocationPath, NameSpaceAware):String : Extracts information from an XML string that is referenced by an XPath-based location path. The optional parameter NameSpaceAware defines, if the evaluation should respect name spaces.
  • List-based functions
    • append (A, B):LIST : Appends an element B to a list A of the same Data Type and returns a new list with the elements of list A followed by the appended element B.
    • concatlists (A, B):LIST : Concatenates the elements of two lists of the same Data Type and returns a new list with the elements of list A followed by the elements of list B.
    • length (A):Integer : Returns the length of a list.
  • Type-based functions
    • typeof (D, DATATYPE):Boolean : Verifies if a parameter is an instance of a certain Data Type.
    • new (DATATYPE):DataType : Returns an instance of a given Data Type (only within Mappings).

Values

Constant values can be used to be compared with source parameters (e.g. DeviceType=Modem5), to be assigned to target parameters (e.g. ResultMessage=OK) or to be used as index to access list entries (e.g. Device.Ports[3]:=Port). It is also possible to use them for calculations (e.g. Device.Ports[length(Device.Ports)-1]:=Port).

A special constant value is null. An Output Parameter can be set to null (only with Mappings: ...:=null, ...~=null) or a term can be compared to null (...=null or ...≠null).

Instance Services

Some Data Types supply Instance Services with a simple output type (e.g. String or Boolean). They can be called from out of a source parameter.

Example: The Application XynaPropertyMgmt provides the Data Type Xyna Property. Its Instance Service get can be used to retrieve the value of a certain Xyna Property.

Modeling a Term

The common way to start modeling a term is to insert a new source parameter. This can be done by dragging Data Types from Factory Navigation or Search or Parameters of other Process Steps onto the desired position. The next steps can be taken by mouse or keyboard.

Autocomplete

Figure 8: Context-sensitive menu with possible Member Variables and Instance Services

Pressing <kbd>.</kbd> behind a source or target parameter or one of its Member Variables opens a context-sensitive menu at the current cursor position (cf. fig. 7). If the cursor is right to a source or target parameter or one of its Member Variables, the menu shows Member Variables and Instance Services of that Member Variable's Data Type (cf. fig. 8). The text input field above can be used with that menu for autocompletion.

Keyboard

The fastest way to model terms is by using the keyboard. A blinking cursor indicates the current insertion point. If there is no blinking cursor, the keyboard mode is not active.

<caption>Supported keyboard commands</caption>
Keyboard command Insertion
<kbd>Left</kbd>, <kbd>Right</kbd>, <kbd>Del</kbd>, <kbd>Backspace</kbd> The direction keys, <kbd>Del</kbd> and <kbd>Backspace</kbd> can be used to navigate inside a term like inside an ordinary text field.
<kbd>.</kbd> If the cursor is right to a source or target parameter or to one of its Member Variables, the menu only shows Member Variables and Instance Services of that Member Variable's Data Type (cf. fig. 8). Autocomplete can then help to find the wanted menu entry by keyboard.
<kbd>:</kbd> or <kbd>=</kbd> Inserts the assignment := (only Mappings).
<kbd>~</kbd> Inserts the assignment ~= (only Mappings).
<kbd>+</kbd>, <kbd>-</kbd>, <kbd>*</kbd>, <kbd>/</kbd> Inserts the arithmetic operators (+, -, *, ÷).
<kbd>=</kbd> (in Mappings <kbd>==</kbd>), <kbd>!</kbd>, <kbd>&gt;</kbd>, <kbd>&lt;</kbd> Inserts the Boolean operators (=, !, >, <). If an exclamation point (!) is followed by an equality sign (=), they will be comined to a Not equals (≠) (after leaving the formula).
Analogous behavior: > and = will be combined to ≥, < and = will be combined to ≤ (after leaving the formula).
<kbd>&amp;</kbd> Inserts the AND operator.
<kbd>&#124;</kbd> Inserts the OR operator.
<kbd>(</kbd>, <kbd>)</kbd>, <kbd></kbd>[,]<kbd>]</kbd> Inserts the different brackets (, ), [,].
<kbd>0</kbd> Inserts null
<kbd>?</kbd> Inserts the placeholder ? (only Conditional Choice and Conditional Branching).
<kbd>a</kbd> Inserts #cast()
<kbd>k</kbd> Inserts concat()
<kbd>c</kbd> Inserts contains()
<kbd>e</kbd> Inserts endswith()
<kbd>g</kbd> Inserts glob()
<kbd>i</kbd> Inserts indexof()
<kbd>l</kbd> Inserts length()
<kbd>m</kbd> Inserts matches()
<kbd>r</kbd> Inserts replaceall()
<kbd>s</kbd> Inserts startswith()
<kbd>ALT+s</kbd> Inserts substring()
<kbd>ALT+l</kbd> Inserts tolowercase()
<kbd>u</kbd> Inserts touppercase()
<kbd>x</kbd> Inserts xpath()
<kbd>ALT+x</kbd> Inserts asxflexpression()
<kbd>ALT+a</kbd> Inserts append()
<kbd>ALT+k</kbd> Inserts concatlists()
<kbd>ALT+i</kbd> Inserts typeof()
<kbd>n</kbd> Inserts new()

Mouse

Figure 10: Parameter with an unsolved ambiguity

The mouse can help to move a source or a target parameter inside of a term by dragging it. If the parameter is not connected due to an ambiguity, the possible connections can be shown by clicking on the affected parameter (cf. fig. 10). If the parameter is connected, a click on it will show/hide its connection.

See Also

Clone this wiki locally