Rules with Lua scripts

Scripts written in the Lua programming language can be used to describe the algorithms for checking the values of tags in Process Control rules. Lua scripts provide the capabilities to not only check the values of tags but also to add various information to registered events and process logs.

A Lua script must consist of one or more functions. The names of the functions must be unique among all rules with Lua scripts. A function that is used to track the values of tags is called a trigger function. A trigger function must return a value of true to register an event.

If a variable is indicated in a script, the variable must be initialized either in that specific script (to be applied only in that script) or in a separate global script (to be applied in all rules with Lua scripts). A global script can also contain auxiliary functions that can be used in rules with Lua scripts.

A trigger function is called whenever the value of any tag used in the function is changed. The function is first called when all values of tags used in the function are received.

To obtain the values of a tag, the code of a function contains an entry that looks as follows:

tag'main_tag_parameters[:field_name][@modifier]'[.transmission_direction]

where:

• main_tag_parameters are the mandatory parameters that identify the tag in the application. Parameters are separated by a colon. The main parameters consist of the following parameters from the tags table:
  • Device
  • Tag name
  • Tag ID
• field_name is the name of the field within the tag field structure represented by the Structural values parameter in the tags table. If a field is embedded into other fields, its name is indicated together with the names of all parent fields separated by a colon. If the field_name parameter is not specified, the main value within the tag field structure is checked.
• modifier defines how the obtained value is presented. The following modifiers are available:
  • str means that the obtained value is converted into a string value.
  • type means that the name of the data type from the obtained value is passed as the value.
  • loc means that the passed value is the assigned localized name for the obtained value (if there is no localized named, the obtained value is converted into a string value).

  If a modifier is not specified, the actual obtained value is used. In this case, the data type of the value is not changed.

• transmission_direction defines the direction in which the obtained value is transmitted. The transmission direction can be defined by one of the following parameters:
  • R means that the value was received when it was read from a device.
  • W means that the value was received when it was written to a device.
  • RW refers to any direction of the obtained value.

  If the transmission direction is not defined, the value obtained from any direction is used.

Records for obtaining the values of tags can be used in expressions (for example, assigning values to variables or comparing values).

To perform various operations with a Lua script, you can use auxiliary functions supported by the Server. The names of auxiliary functions begin with an underscore (_).

The main auxiliary functions for adding information via Lua scripts are as follows:

• Function for adding parameters to use as additional variables in events:

  _AddEventParam('parameter_name', parameter_value)

  Any name and value can be defined for a parameter. To use a parameter and its value in events, this parameter must be specified in event type parameters as follows: $extra.<parameter_name>.

• Functions for adding entries to the process log in which the Lua script is executed (this is normally a process whose name starts with the word Filter). A record defined by an argument of the function (variable or constant) is added to the log:
  • To create a record with the Errors level:

    _WriteErrorLog(function_argument)

  • To create a record with the Warning level:

    _WriteWarningLog(function_argument)

  • To create a record with the Info level:

    _WriteInfoLog(function_argument)

  • To create a record with the Debug level:

    _WriteDebugLog(function_argument)

  • To create a record with the Debug level that may contain multiple arguments of the function:

    print(function_argument1, function_argument2,…)

    Variables or constants defined by function arguments are separated by a tab character in a log record.

  Records are not created in the log if the level of the record is lower than the logging level set for the process.