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.
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 | - | 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 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.
Result
- The
executeCommand
andexecuteCommandNoScaling
functions return theCommandResult
object with theerror
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 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 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");