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.

 

NOTICE
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

BrowserObject

Point

-

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

BigNumber

Boolean

Date

String Array / Number Array / BigNumber Array / Boolean Array / Date Array

JSON object

-

Optional

Parameters necessary to execute a command.

For the executeCommand function the parameters values must be provided scaled according to the scaled unit of the property that is commanded; if the scaled unit is not set, the value is intended to be in the specified unit (where applicable).

 

For the executeCommandNoScaling function the parameters values must be provided non-scaled according to the unit of the property that is commanded regardless of the scaled unit that may be specified (where applicable).

comment

String

-

Optional

This parameter must be specified in order to execute the command successfully when Validation profile = Enabled.

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 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.

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

}