executePropertyCommand Function
The following functions allow executing a command defined on a property in a Desigo CC system by specifying the name of the command to use:
executePropertyCommand
executePropertyCommandNoScaling
The executePropertyCommand
function allows providing scaled values for the parameters values, while the executePropertyCommandNoScaling
takes non-scaled values as value parameters.
Commands management
Desigo CC scripts can only handle commands that are configured to be executed as software. Consequently, a command can be executed by a script only if its display level is set to Software or GenericDisplayAndSoftware.
Command Name
It is unique per property which means that a property cannot have more than one command using the same name. When executing a command identified by its name, it is necessary to specify the name of the system object and the property to command. In this way the command to issue can be identified among the available commands for that property. A command can have name only, alias only, or both.
Syntax
It is possible to command a property by specifying the command name. See the following syntax:
(one instruction)
var result = executePropertyCommand(<objectReference>, <propertyName>, <commandName>, <commandParameters>, <comment>)
var result = executePropertyCommandNoScaling(<objectReference>, <propertyName>, <commandName>, <commandParameters>, <comment>)
(two instructions with variable)
var obj = new BrowserObject(<objectReference>);
var result = executePropertyCommand(obj, <propertyName>, <commandName>, <commandParameters>, <comment>)
var obj = new BrowserObject(<objectReference>);
var result = executePropertyCommandNoScaling(obj, <propertyName>, <commandName>, <commandParameters>, <comment>)
Parameters Usage
Parameter | Type | Default | Use | Annotation |
objectReference | String | - | Mandatory | CNS full path (reference to the system object location). |
propertyName | String | - | Mandatory | Name of the property to command. |
commandName | String | - | Mandatory | Name of the command to execute. |
commandParameters | String Number Boolean Date String Array / Number Array / BigNumber Array / Boolean Array / Date Array JSON object | - | Optional | Parameters necessary to execute a command. For the
For the |
comment | String | - | Optional | This parameter must be specified in order to execute the command successfully when Validation profile = |
Note that:
- If no parameter values are specified for
<commandParameters>
when required by the command, the command execution will fail despite that the instruction was executed with no exceptions. - If the command has only one parameter, it is possible to directly specify the value of the parameter (short notation).
- If the command has more than one parameter, it is necessary to pair the parameters values with their names in a JSON object like the following:
var parameters = {"Priority": 16, "Value": 1}
- The following data types are not supported as parameter data types: PvssBlob and GmsApplSpecific.
- Objects with Validation profile =
Supervised
cannot be commanded using scripts, since it is not possible to specify the required password. - It is not necessary to pass the
<comment>
parameter for commanding objects with Validation profile =Disabled
. - When the
<comment>
parameter is required but no parameter is necessary for the command execution, it is mandatory to specify<commandParameters>
as null.
- While the unit configured for a property must always be the same, the scaled unit may change. In this case it is recommended to use the function
executePropertyCommandNoScaling
which always takes the non-scaled values as parameters values. This means that the provided value is always represented according to the configured unit, regardless of the configured scaled unit which may change.
Result
- The
executePropertyCommand
andexecutePropertyCommandNoScaling
functions return theCommandResult
object with theerror
property that is empty in case of success or indicates the reason why the operation failed.
Error Handling
Errors can occur in case:
- Empty
<objectReference>
. result.error: "The object reference is empty"
- Empty
<propertyName>
; or<aliasId>
= 0; or<commandParameters>
contains errors.
For example, if the date for last execution time of a macro is invalid, the command is not executed, and the following error is traced:"Unable to get value of parameter 'Value' (requested data type: 'PvssTime')"
.
Another example is when a value is out of the range defined by its text group. The result is that even if the value is not defined, the command is successfully executed. It is recommended to pay attention to the validity of the parameters values. result.error: "Invalid input"
- Invalid system object. The property or system object to command is not found.
The target is not found. The system object (node) or property to command is not found in the Desigo CC system or the user has no access to it. (For example, "System1.MyObject" is an invalid object because it does not exist in that specific system.) result.error: "Node not found (System1.MyObject)"
- Invalid
<propertyName>.
(For example, the property "Hello" is not defined.) result.error: "Property not found (Hello)"
- Invalid
<commandName>
type. The command requested on a target property or system object is not found.
The requested command is not available on the target property or system object, or the specified<commandParameters>
does not satisfy the command definition signature (for example, the requested command requires two parameters while<commandParameters>
contains a different number of parameters or parameters with different names).
Another example is: the interface ofexecutePropertyCommand
method requires a string as<commandName>
, while a numeric value is used as parameter; the result is that the numeric value is treated as string but no command with that name is found. result.error: "Command not found"
- Invalid
<commandParameters>
because an array contains different types of values (for example, number and Boolean): result.error:
“Invalid input”
- Command not found
(<commandParameters>
is different from null for a command that does not require any parameter). - Empty, null, or missing
<comment>
, when the commanded object has
Validation profile =Enabled
. - The command execution fails, and the Console expander displays:
The validation rules require a non-empty comment
.
Examples of Use
How to set the "Operational Status" Organization Mode property to "In Maintenance"
var parameters = {"Value": 1};
var object = new BrowserObject("System1.ManagementView:ManagementView.SystemSettings.OrganizationModes.OperationalStatus");
var result = executePropertyCommand(object, "Value", "Write", parameters);
//1 is the value corresponding to "In Maintenance" in the text group TxG_Operational
Note that the "Value"
property of the Organization Mode object model has a command with name "Write"
: Such command requires another parameter named "Value"
of type GmsEnum (see the command definition of GenericWriteEnum), whose affected property is "Value"
.
How to set the "Open and Close" Organization Mode property to "Open"
var object = new BrowserObject("System1.ManagementView:ManagementView.SystemSettings.OrganizationModes.OpenClose");
var result = executePropertyCommand(object, "Value", "Write", 0);
var result = executePropertyCommand(object, "Value", "Write", 1);
//0 is "Open" in TxG_OpenClose text group
//1 is "Close" in TxG_OpenClose text group
As in the previous example, the "Value"
property of the Organization Mode object model has a property named "Value"
on which the "Write"
command is defined. Such command requires a parameter called "Value"
of type GmsEnum (see the command definition of GenericWriteEnum), whose affected property is "Value"
. (The short notation is used as the parameter required is only one.) To set back the Organization Mode "Open and Close"
to "Close"
, just change the parameter value.
How to set the Present Value property of a BACnet Analog Value with a specific value of priority 11
var val = 21.5;
var prio = 11; //11 is "Priority - 11" in the TxG_BACnetPriorityLevels text group
var parameters = {"Value": val, "Priority": prio};
var result = executePropertyCommand("System1.ManagementView:ManagementView.FieldNetworks.MyBACnetNet.Hardware.5000/5000SimDev1_5000.5000/0Local_IO.5000/1AV_1", "Present_Value", "WritePrio", parameters);
The result of the call is the Present Value—of the BACnet Analogue Value—set to the required value with priority 11. Note that the command BACnetAnalogWithPriority
is named "WritePrio"
and requires two parameters specified by array and array of arrays. Additionally, the BACnet driver must be started (not in simulation mode).
If the “Present_Value”
property has a scaled unit, the value 21.5 is intended to be provided according to the configured scaled unit. If the configuration of the scaled unit changes, the script must be updated accordingly, otherwise the commanded value changes its meaning.
If the scaled unit is not provided, 21.5 indicates the value according to the unit configured for the property.
To prevent issues due to the change of scaled units, consider using the executePropertyCommandNoScaling
function which allows providing the non-scaled value. This means that 21.5 always indicates the value according to the unit configured for the property, regardless of the configured scaled unit, which may change.
For example:
var parameters = {"Value": 2.15, "Priority": 11};
var result = executePropertyCommandNoScaling("System1.ManagementView:ManagementView.FieldNetworks.MyBACnetNet.Hardware.5000/5000SimDev1_5000.5000/0Local_IO.5000/1AV_1", "Present_Value", "WritePrio", parameters);
How to set the Present Value property of a BACnet Analog Value using "Manual Operator" priority
var result = executePropertyCommand("System1.ManagementView:ManagementView.FieldNetworks.MyBACnetNet.Hardware.5000/5000SimDev1_5000.5000/0Local_IO.5000/1AV_1", "Present_Value", "Write", 19);
The result of the call is the Present Value—of the BACnet Analogue Value—set to the required value with priority 8 (Manual Operator) which is also the default value. Note that the command BACnetAnalogWithPriority
is named "Write"
and requires two parameters, one of which provided by default thus allowing the use of the short notation.
The value assigned to the parameter is intended to be scaled according to the scaled unit.
In case you want to set the value regardless of the scaled unit:
var result = executePropertyCommandNoScaling("System1.ManagementView:ManagementView.FieldNetworks.MyBACnetNet.Hardware.5000/5000SimDev1_5000.5000/0Local_IO.5000/1AV_1", "Present_Value", "Write", 1.9);
How scaled and non-scaled values work
Assuming that you have two Virtual Analog objects, both with Unit = kW and Scaled unit = W for the Value property.
var result1 = executePropertyCommand(
"System1.ApplicationView:ApplicationView.Logics.VirtualObjects.VirtualAnalog1",
"Value", "Write", 19);
var result2 = executePropertyCommandNoScaling(
"System1.ApplicationView:ApplicationView.Logics.VirtualObjects.VirtualAnalog2",
"Value", "Write", 19);
The first instruction, that uses executePropertyCommand
, results in the VirtualAnalog1 Value to be set to 19 W because the input value 19 is intended to be scaled according to the scaled unit, which is W.
The first instruction, that uses executePropertyCommandNoScaling
, results in the VirtualAnalog2 Value to be set to 19000 W because no scaling is applied, meaning that the input value 19 is in kW which is the unit configured for the property.
How to set an OPC Binary Output property to True
var boolParam = 1;
//or var boolParam = true; or var boolParam = "true";
var result = executePropertyCommand("System1.ManagementView:ManagementView.FieldNetwork .MyOPCNet.Server_Matrikon.Group_3.BinaryOutput1", "Value", "Write", boolParam);
The result of the call is an OPC Binary Output set to True. Note also that the GenericWriteBool
command is named "Write"
.
Commanding a property – How to read the date of the last backup execution and write it as last execution time for a macro
var object = new
BrowserObject("System1.ManagementView:ManagementView.ManagementSystem.Servers.Server");
var timeResult = read(object, "Backup.LastSucceededDate");
if (!timeResult.error)
{
var result =
executePropertyCommand("System1.ApplicationView:ApplicationView.Logics.MacroRoot.MyMacro",
"LastExecutionTime", "Write", timeResult.value);
}
Commanding a property – How to write a date as last execution time for a macro
var result =
executePropertyCommand("System1.ApplicationView:ApplicationView.Logics.MacroRoot.MyMacro",
"LastExecutionTime", "Write", myTime);
Note that the value of a date/time parameter can be retrieved using the input from a PvssTime property or it can be created using one of the following:
- JavaScript Date instance. For example:
//Take the current date and time
var myTime = Date.now();
//Set a custom date and time (for example, January 21, 2015, 10:11:12.130 PM), using the
constructor "new Date(year, month[, day[, hour[, minutes[, seconds[, milliseconds]]]]])"
var myTime = new Date(2015, 1, 21, 22, 11, 12, 130);
- A string formatted according to the culture of the user running the script. For example:
var myTime = "01/21/2014 10:11:12 AM";
After creating the date/time parameter value, it can be used as follows:
var result =
executePropertyCommand("System1.ApplicationView:ApplicationView.Logics.MacroRoot.MyMacro",
"LastExecutionTime", "Write", myTime);
The resulting last execution time for MyMacro is "1/21/2015 10:11:12 PM"
.
How to set the value of a property of type BitString
A BitString value can be set by passing an integer value or a string that contains a binary value. The following instructions are equivalent:
executePropertyCommand("System1.ApplicationView:ApplicationView.Logics.VirtualObjects.MyBitString", "Value", "Write", 8);
executePropertyCommand("System1.ApplicationView:ApplicationView.Logics.VirtualObjects.MyBitString", "Value", "Write", "1000");
How to command a property for an object with Validation profile = Enabled
The following example shows how to set the Operational Status Organization Mode to In Maintenance, when Operational Status Organization Mode has Validation profile = Enabled.
var parameters = {"Value" : 1};
var object = new BrowserObject("System1.ManagementView:ManagementView.SystemSettings.OrganizationModes.OperationalStatus");
var result = executePropertyCommand(object, "Value", "Write", parameters, "my comment");
How to write an array of strings into a string array property
var stringArray = ["hello", "world"];
executePropertyCommand("System1.ManagementView:ManagementView.FieldNetworks.OPC_Net.Server_Softing.Group_Output.String_Array_Output", "Value", "Write", stringArray);
How to read an array of analog values from an analog array property
read("System1.ManagementView:ManagementView.FieldNetworks.OPC_Net.Server_Softing.Group_Output.R8_Array_Output", "Value")
for (var i = 0; i < readAnalogArray.value.value.length; i++) {
console(readAnalogArray.value.value[i])
}