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

Note that:

• 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 and executePropertyCommandNoScaling functions return the CommandResult object with the error property that is empty in case of success or indicates the reason why the operation failed.

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])

}