Using Lua input and output parameters

Input and output parameters are used to pass information between a Lua script and a trigger action.

Inputs

All inputs from the trigger action are accessed in the Lua script through the DWInput object. They can be any valid data type, although some Lua functions may not support certain types.

Inputs are declared using the Variables dialog in the Execute Lua Script and Execute Lua Function From File actions.
Once they have been declared, they are accessed in the Lua script as DWInput["variable_name"].

For example:

  1. You want to pass a STRING variable string and an INT2 array variable int2_array into a Lua script.

  2. After declaring them as Input Variables, you would access them in the Lua script as DWInput["string"] and DWInput["int2_array"].

Outputs

All outputs of the Lua script are returned to the trigger action through the DWOutput object. They can be any valid data type, although some conversions between Lua types and data types may not be valid.

Outputs are declared using the Variables dialog in the Execute Lua Script and Execute Lua Function From File actions.
Once they have been declared, they are accessed in the Lua script as DWOutput["variable_name"].

For example:

  1. You want to return a STRING variable string_out and an INT2 array variable int2_array_out from a Lua script.

  2. After declaring them as Output Variables, you would use them in the Lua script as DWOutput["string_out"] and DWOutput["int2_array_out"].

Parameter types

Constants

Constant values can be input into functions through quotes.

DWOutput["status"],DWOutput["value"] = dw.variable.read("Local CPU 1","D[0]");

In the example above, Local CPU 1 and D[0] are constant inputs into the dw.variable.read Lua function.

Variables

Variables can be used as inputs into Lua functions anywhere a constant can be used. They can be scalar (single) variables or an array.

local trigname = "LUA_Trigger";
local s,out = dw.trigger.execute(trigname,"subtrigger_echo",i);
DWOutput["o"] = {out["out1"],out["out2"],out["out3"]};
DWOutput["s"] = s;

In the example above, a variable trigname is declared and used as an input into the dw.trigger.execute Lua function. Be aware that certain Lua functions require specific input formats.

For example, the function above requires an associative array i with the names of expected subtrigger inputs as keys values, such as i["one"].

Similarly, the output array has values out["out1"], out["out2"], and out["out3"].
See the Subtrigger Inputs and Outputs below for more information.

Refer to documentation for the specific Lua functions for information on their inputs and outputs.

For an overview of basic concepts of Lua and variables, see Overview of Lua language concepts.

Variable types

All data types (INT1, UINT1, FLOAT4, etc.) are supported as data types for Lua functions except variable types of BINARY, TIMESTAMP, and STRUCT, which are not supported.

Some data types passed into a Lua script as an input parameter may not be able to be converted to a different data type when it is passed back as an output parameter.
For example, in MESInterface IT, a BIT data type passed into a Lua script can only be passed back as an output parameter as a BIT data type.

Lua considers all numerical types to be double-precision floating point numbers, meaning that there are only 53 bits of precision to represent any number. Thus when interfacing with a trigger action, if a 64-bit integer is used that is larger than 9,007,199,254,740,992, precision will be lost.

Arrays

An array passed in as one of the Input Variables can be accessed as follows:

local my_inputs = DWInput["input"];
local i = {one=0,two=0,three=0};
i["one"]=my_inputs[1];
i["two"]=my_inputs[2];
i["three"]=my_inputs[3];

In the example above, an array named input is passed into the Lua script. The array is first accessed in Lua by using DWInput["input"] and set to the Lua variable my_inputs.
It can then be accessed using my_inputs[1], my_inputs[2], and my_inputs[3].

Alternatively, we can also access the first index of that array using DWInput["input"][1].
Note that in Lua, the first array index is 1, not 0.
Also, remember that Lua is a dynamically typed language. Therefore, you should use the input variables types similar to the original data type of the input array.

For an overview of basic concepts of Lua, see Overview of Lua language concepts.

Subtrigger inputs and outputs

Subtriggers require a different format than the normal Input Variables. Each subtrigger input has to be declared by name.
For example, if a subtrigger requires three inputs, "one", "two", and "three", then the Lua script must explicitly create an array, such as "i", with array references of i["one"], i["two"], and i["three"].

See the script example below: 

local my_inputs = DWInput["input"];
local i = {one=0,two=0,three=0};
i["one"]=my_inputs[1];
i["two"]=my_inputs[2];
i["three"]=my_inputs[3];
local s,out = dw.trigger.execute("LUA_Trigger","subtrigger_echo",i);
DWOutput["output"] = {out["out1"],out["out2"],out["out3"]};
DWOutput["s"] = s;

It is also provided as an export file that can be downloaded and then imported into your node using the Workbench:

Trigger_subtrigger_echo.dwx

The same situation applies for outputs from a subtrigger. For example, the "out" array has to be accessed by out["out1"], out["out2"], and out["out3"].