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:

  1. Formulas use the expressions syntax of C# language. Many of Microsoft .NET classes are accessible, for example, Math and DateTime classes.
  2. New constants, fields, properties and methods can be added to use in formulas.
  3. 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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. The statuses of the other types of channels are set to Defined if status calculation does not specified explicitly.
  6. An input channel formula that does not contain ";" (semicolon) symbol calculates the input channel value only.
  7. 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.
  8. If the channel limits are specified, the channel status is recalculated taking the limits into account after calculating the channel formula.
  9. 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:

  1. Formulas are processed for output channels having the Standard and Binary command types.
  2. 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.