Using Formulas
Formulas are used for calculating values and statuses of input channels and calculating values of commands. Formulas processing is performed by the Server application.
Formulas are enterd in the Formula column of the Input channels and Output channels tables of the configuration database. To enable the formula, tick the checkbox in the Formula used column. The Formulas table contains additional functions and data structures which can be used in formulas for input and output channels.
Formula Writing Rules
The general rules of writing and using formulas:
- Formulas use the expressions syntax of C# language. Many of Microsoft .NET classes are accessible, for example, Math and DateTime classes.
- New constants, fields, properties and methods can be added to use in formulas.
- If at least one formula contains an error, Server operation is impossible. Information about errors in formulas is written in the Server application log.
The rules for calculating input channel formulas:
- Channels of the Discrete and Real types are calculated when the channels data are received by Server. Use these channel types if formula does not refer to data of other channels.
- Channels of the Calculated * and Switching counter types are calculated permanently in order according to the channel numbers. A formula of a calculated channel usually refers to data of other channels.
- Channels of the Minute * and Hourly * types are calculated periodically, once per minute or once per hour. Use these channel types to create accumulated values, for example, energy consumption or operating time.
- For channels of the Discrete and Real types statuses of the channels after calculating are equal to the statuses of these channels received by Server if status calculation does not specified explicitly.
- The statuses of the other types of channels are set to Defined if status calculation does not specified explicitly.
- An input channel formula that does not contain ";" (semicolon) symbol calculates the input channel value only.
- If an input channel formula contains ";", the formula calculates the input channel value and status. The first part before semicolon is a formula for value calculation and the second part after semicolon calculates status.
- If the channel limits are specified, the channel status is recalculated taking the limits into account after calculating the channel formula.
- A formula for calculating a channel value must return a real number of the double type, and the formula for calculating the status returns an integer having the int type.
The rules for calculating output channel formulas:
- Formulas are processed for output channels having the Standard and Binary command types.
- A formula for calculating the value of a standard command must return a real number of the double type, and the formula for calculating data of a binary command returns an array of bytes of the byte[] type.
Existing Formulas
The variables accessible in formulas:
| Variable | Value Type | Description |
|---|---|---|
| CnlVal, Cnl | double | The input channel value transmitted to Server before calculation |
| CnlStat | int | The input channel status transmitted to Server before calculation |
| CmdVal, Cmd | double | The command value transmitted to Server before calculation |
| CmdData | byte[] | The command data transmitted to Server before calculation |
| CnlNum | int | The channel number for which the formula is calculated |
| E | double | The natural logarithmic base, specified by the constant, e |
| PI | double | The ratio of the circumference of a circle to its diameter, specified by the constant, π |
The functions accessible in formulas:
| Fucntion | Value Type | Description |
|---|---|---|
| N(n) | int | Returns the specified channel number for updating numbers on cloning |
| Val() | double | Gets the current value of the formula channel |
| Val(n) | double | Gets the current value of the channel n |
| SetVal(n, val) | double | Sets the current value of the channel n |
| Stat() | int | Gets the current status of the formula channel |
| Stat(n) | int | Gets the current status of the channel n |
| SetStat(n, stat) | int | Sets the current status of the channel n |
| SetData(n, val, stat) | double | Sets the current value and status of the channel n |
| Abs(x) | double | Calculates the absolute value of a number |
| Sin(x) | double | Calculates the sine of the specified angle |
| Cos(x) | double | Calculates the cosine of the specified angle |
| Tan(x) | double | Calculates the tangent of the specified angle |
| Exp(x) | double | Calculates e raised to the specified power |
| Ln(x), Log(x) | double | Calculates the natural (base e) logarithm of a specified number |
| Sqr(x) | double | Calculates the square of a specified number |
| Sqrt(x) | double | Calculates the square root of a specified number |
Additional formulas, including formulas for calculating averages, are available on GitHub.
Debugging Formulas
If you develop custom formulas, check their syntax and validate whether they work correctly. If the Server service fails to compile the formulas at startup, information about the error is written in the Server log file, and the source code of the formulas that Server tries to compile is available in CalcEngine.cs, which is located in the Server log directory, by default C:\SCADA\ScadaServer\Log\
To develop complex formulas, it is recommended to use Microsoft Visual Studio Community Edition. Add a refererence to the FormulaTester.dll assembly in the project. As an example, use the project mentioned above, which contains formulas.