executeCommand Functions

The following methods allow executing a command on a system object by indicating the alias of the command to use.

  • executeCommand
  • executeCommandNoScaling

 

The executeCommand function allows providing scaled values for the parameters values, while the executeCommandNoScaling 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 Alias

It is unique per system object which means that a system object cannot have more than one property using the same alias. When executing a command identified by its alias, only the name of the object must be specified, because the target property can be identified searching for the only property that has the given alias. In this way, the command can be identified among the available commands for all the properties of that object. A command can have name only, alias only, or both.

Syntax

It is possible to command a system object by specifying the command alias. See the following syntax:

 

(one instruction)

var result = executeCommand(<objectReference>, <aliasId>, <commandParameters>, <comment>)

 

var result = executeCommandNoScaling(<objectReference>, <aliasId>, <commandParameters>, <comment>)

 

(two instructions with variable)

var obj = new BrowserObject(<objectReference>);
var result = executeCommand(obj, <aliasId>, <commandParameters>, <comment>)

 

var obj = new BrowserObject(<objectReference>);
var result = executeCommandNoScaling(obj, <aliasId>, <commandParameters>, <comment>)

Parameters Usage

Parameter

Type

Default

Use

Annotation

objectReference

String

BrowserObject

Point

-

Mandatory

CNS full path (reference to the system object location).

aliasId

Integer

-

Mandatory

Alias identifier of the command to execute. Its value can be obtained by checking the text group: Command Macro.

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, parameters values must be provided scaled and 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 and 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.

Result

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

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 access and print to Console the result of a command execution call

function printCommandResult(commandResult) {

    if (commandResult.error)

        console("Command failed. Error = '{0}'. Error id = {1}", commandResult.error.message, commandResult.error.id);

    else

        console("Command succeeded");

}

 

An easier way to print the result of the call is, for example:

console(commandResult)

 

How to start and stop a BACnet driver object

var object = new BrowserObject("System1.ManagementView:ManagementView.ManagementSystem.Servers.Server.Drivers.GmsBacnetDriver_1");

var result = executeCommand(object, 32);

var result = executeCommand(object, 33);

//32 is the Alias ID "Start"

//33 is the Alias ID "Stop"

 

Note that the command is used and defined by alias ("Start"=32 and "Stop"=33). The first call will start the BACnet driver, while the second call will stop the driver.

 

How to start a backup operation on the server

var result = executeCommand("System1.ManagementView:ManagementView.ManagementSystem.Servers.Server", 26);

//26 is the Alias ID "Backup" for the command BackupExecute

or

var result = executePropertyCommand("System1.ManagementView:ManagementView.ManagementSystem.Servers.Server", "Backup.Status", "Start");

 

The call results in starting the project backup. Note that the command BackupExecute is used and defined by alias (26). Such command has also “Name” which means that the same result can be obtained by calling the commanding the Backup.Status property of the Main Server or using the Start command.

 

How to command an object with Validation profile = Enabled

The following example shows how to start the backup on the Main Server with Validation profile = Enabled.

var result = executeCommand("System1.ManagementView:ManagementView.ManagementSystem.Servers.Server", 26, null, "my comment");