API for reading/writing of field variables¶

Introduction

The APIs described below, supplied by the IUAVariable, InformationModel and IUANode classes, allow single variables or sets of multiple variables to be read/written. Typically, multiple variables are read/written together for the following requirements:

Read/write an entire set of variables before proceeding with other operations. This is essential, for example, when writing recipes.
Limit the number of communications with the field to support performance.

The table below indicates the APIs to use for various purposes:

Purpose	API
Read a known field variable value.	IUAVariable.RemoteRead(timeoutMilliseconds)
Read the values of multiple known field variables.	InformationModel.RemoteRead(variables, timeoutMilliseconds)
Read the values of multiple known field variables that are children of a specific node.	IUANode.ChildrenRemoteRead(childVariables, timeoutMilliseconds)
Read the values of all the field variables that are children of a specific node.	IUANode.ChildrenRemoteRead(timeoutMilliseconds)
Write a known field variable value.	IUAVariable.RemoteWrite(value, timeoutMilliseconds)
Write the values of multiple known field variables.	InformationModel.RemoteWrite(variableValues, timeoutMilliseconds)
Write the values of multiple known field variables that are children of a specific node.	IUANode.ChildrenRemoteWrite(childVariableValues, timeoutMilliseconds)

Management of exceptions

The methods described below generate an exception when there is an error in execution. The exception can be captured and managed using the try and catch instructions.

IUAVariable.RemoteRead(timeoutMilliseconds)¶

Returns the value of the variable on which it invokes. The argument, optional, sets a timeout period.

UAValue RemoteRead(double timeoutMilliseconds);

Arguments

timeoutMilliseconds double

Timeout period, in milliseconds, after which the API generates an exception.

Note

if not specified, the predefined value of the argument is 30000, or 30 seconds.

Returns

UAValue

Variable value.

Example

In the following example, the Speed variable value is read and given in an information message.

var currentSpeed = Project.Current.GetVariable("Model/Motor/Speed");
var value = currentSpeed.RemoteRead();
Log.Info(value.ToString());

IUAVariable.RemoteWrite(value, timeoutMilliseconds)¶

Writes the value indicated in the first argument in the variable on which it invokes. The second argument, optional, sets a timeout period.

void RemoteWrite(UAValue value, double timeoutMilliseconds);

Arguments

value UAValue

Value to write.

timeoutMilliseconds double

Timeout period, in milliseconds, after which the API generates an exception.

Note

if not specified, the predefined value of the argument is 30000, or 30 seconds.

Example

Below is an example in which the value 42 is written in the Speed variable.

var currentSpeed = Project.Current.GetVariable("Model/Motor/Speed");
currentSpeed.RemoteWrite(42);

InformationModel.RemoteRead(variables, timeoutMilliseconds)¶

Returns a list of variables of interest.

static IEnumerable<RemoteVariableValue> RemoteRead(IEnumerable<RemoteVariable> variables, double timeoutMilliseconds);

Arguments

variables IEnumerable<RemoteVariable>

List of the variables of interest.

timeoutMilliseconds double

Timeout period, in milliseconds, after which the API generates an exception.

Note

if not specified, the predefined value of the argument is 30000, or 30 seconds.

Returns

IEnumerable<RemoteVariableValue>

List of the variables of interest, expressed as a pair of the following properties of the RemoteVariableValue class:

Variable IUAVariable : variable
Value UAValue: value of the variable

Example

Below is an example in which the values of three tag variables are read. To do it, the variables of interest are included, searched with the Get() method in the remoteVariables list, which is passed as argument of the RemoteRead() method. The values read are then displayed using three different text boxes.

var tag1 = Project.Current.Get<Tag>("CommDrivers/CodesysDriver1/CodesysStation1/Tags/Application/PLC_PRG/VAR1");
var tag2 = Project.Current.Get<Tag>("CommDrivers/CodesysDriver2/CodesysStation1/Tags/Application/PLC_PRG/VAR1");
var tag3 = Project.Current.Get<Tag>("CommDrivers/CodesysDriver3/CodesysStation1/Tags/Application/PLC_PRG/VAR1");

var remoteVariables = new List<RemoteVariable>()
{
    new RemoteVariable(tag1),
    new RemoteVariable(tag2),
    new RemoteVariable(tag3),
};
var values = InformationModel.RemoteRead(remoteVariables).ToList();

textbox1.Text = values[0].Value;
textbox2.Text = values[1].Value;
textbox3.Text = values[2].Value;

InformationModel.RemoteWrite(variableValues, timeoutMilliseconds)¶

Writes the values in the variables on interest. The second argument, optional, sets a timeout period.

static void RemoteWrite(IEnumerable<RemoteVariableValue> variableValues, double timeoutMilliseconds);

Arguments

variableValues IEnumerable<RemoteVariable>

List of the variables whose value we want to write, expressed as a pair of the RemoteVariableValue class following properties:

Variable IUAVariable : variable
Value UAValue: value of the variable

timeoutMilliseconds double

Timeout period, in milliseconds, after which the API generates an exception.

Note

if not specified, the predefined value of the argument is 30000, or 30 seconds.

Example

Below is an example in which the values of two tag variables are written: the value 0 for the tag3 variable, and the value 123 for the tag1 variable. To do it, the variables of interest are included, searched with the Get() method in the remoteVariableValues list, which is passed as argument of the RemoteWrite() method.

var tag1 = Project.Current.Get<Tag>("CommDrivers/CodesysDriver1/CodesysStation1/Tags/Application/PLC_PRG/VAR1");
var tag3 = Project.Current.Get<Tag>("CommDrivers/CodesysDriver1/CodesysStation1/Tags/Application/PLC_PRG/VAR3");

var remoteVariableValues = new List<RemoteVariableValue>()
{
    new RemoteVariableValue(tag3, 0),
    new RemoteVariableValue(tag1, 123)
};
InformationModel.RemoteWrite(remoteVariableValues);

IUANode.ChildrenRemoteRead(timeoutMilliseconds)¶

Returns the list of all the direct child variables of the node on which it invokes. The argument, optional, sets a timeout period.

IEnumerable<RemoteChildVariableValue> ChildrenRemoteRead(double timeoutMilliseconds);

Arguments

timeoutMilliseconds double

Timeout period, in milliseconds, after which the API generates an exception.

Note

if not specified, the predefined value of the argument is 30000, or 30 seconds.

Returns

IEnumerable<RemoteChildVariableValue>

List of the direct child variables of the node, expressed as a pair of the RemoteChildVariableValue class following properties:

RelativePath string : path relative to the variable inside the node
Value UAValue: value of the variable

Example

Below is an example in which the API returns the reads list of all the variables contained in the myNode node. For each variable (item), a message is generated that shows the relative path and value.

If the API returns an error or if the set timeout time is reached, the code in the following example generates an error message composed of “ChildrenRemoteRead failed:” and an expected error code for the API.

var myNode = Project.Current.Get("CommDrivers/Driver1/Station1/Tags/TagStructure1");
try
{
    var reads = myNode.ChildrenRemoteRead();
    foreach (var item in reads)
        Log.Info("Tag " + item.RelativePath + " has value " + item.Value);
}
catch (Exception ex)
{
    Log.Error("ChildrenRemoteRead failed: " + ex.ToString());
}

IUANode.ChildrenRemoteRead(childVariables, timeoutMilliseconds)¶

Returns a list of all the variables of interest children of the node on which it invokes. The argument, optional, sets a timeout period.

IEnumerable<RemoteChildVariableValue> ChildrenRemoteRead(IEnumerable<RemoteChildVariable> childVariables, double timeoutMilliseconds);

Arguments

childVariables IEnumerable<RemoteChildVariable>

List of the variables of interest, expressed as relative paths inside the node on which the API is invoked.

timeoutMilliseconds double

Timeout period, in milliseconds, after which the API generates an exception.

Note

if not specified, the predefined value of the argument is 30000, or 30 seconds.

Returns

IEnumerable<RemoteChildVariableValue>

List of the variables of interest, expressed as a pair of the RemoteChildVariableValue class following properties:

RelativePath string : path relative to the variable inside the node
Value UAValue: value of the variable

Example

Below is an example in which the API returns a reads list that contains the variables of interest contained in the myNode node. The two variables of interest were added in the myVariables list: one directly the child of the node (Tag1) and the other inside a child node (NestedStructure/Tag2).

var myVariables = new List<RemoteChildVariable>()
{
    new RemoteChildVariable("Tag1"),
    new RemoteChildVariable("NestedStructure/Tag2")
};
var myNode = Project.Current.Get("CommDrivers/Driver1/Station1/Tags/TagStructure1");
try
{
    var reads = myNode.ChildrenRemoteRead(myVariables);
}
catch (Exception ex)
{
    Log.Error("ChildrenRemoteRead failed: " + ex.ToString());
}

IUANode.ChildrenRemoteWrite(childVariableValues, timeoutMilliseconds)¶

Writes the values of the variables of interest children of the node on which it invokes. The argument, optional, sets a timeout period.

void ChildrenRemoteWrite(IEnumerable<RemoteChildVariableValue> childVariableValues, double timeoutMilliseconds);

Arguments

childVariableValues IEnumerable<RemoteChildVariableValue>

List of the variables whose value we want to write, expressed as a pair of the RemoteChildVariableValue class following properties:

RelativePath string : path relative to the variable inside the node
Value UAValue: value of the variable

timeoutMilliseconds double

Timeout period, in milliseconds, after which the API generates an exception.

Note

if not specified, the predefined value of the argument is 30000, or 30 seconds.

Example

Below is an example in which the API writes the values of the variables defined in the valuesToWrite list and contained in the myNode node. For each variable in the valuesToWrite list, the first argument indicated is the relative path of the variable, and the second argument is the value to write.

var valuesToWrite = new List<RemoteChildVariableValue>()
{
    new RemoteChildVariableValue("Tag1", 4),
    new RemoteChildVariableValue("Tag2", "Hello world"),
    new RemoteChildVariableValue("Tag3", true),
    new RemoteChildVariableValue("NestedStructure/Tag1", 5.9)
};
var myNode = Project.Current.Get("CommDrivers/Driver1/Station1/Tags/TagStructure1");
try
{
    myNode.ChildrenRemoteWrite(valuesToWrite);
}
catch (Exception ex)
{
    Log.Error("ChildrenRemoteWrite failed: " + ex.ToString());
}