Other Time-related Functions
The following functions allow performing time-related operations. In particular, It is possible to interrupt the execution for a specific interval of time or for executing periodic callbacks.
sleep
The sleep
method allows suspending the execution of a script for a specified interval of time. No callbacks will be executed during this time.
Syntax
It is possible to temporarily suspend the script execution thread. See the following syntax:
sleep(<delay>);
Parameters Usage
Parameter | Type | Default | Use | Annotation |
delay | Integer | - | Mandatory | Interval of time (expressed in milliseconds) during which the script execution is suspended. Its value can be numeric (for example, 2000) or a string that represents a number (for example, “2000”). |
Error Handling
Errors can occur in case:
- Missing or invalid delay (for example, negative number).
- The notification will indicate missing/invalid parameters.
- Empty parameter
(<delay> = null
). - The notification will indicate that it is not possible to convert
null
into aSystem.Int32
value. - Empty string.
- The notification will indicate the input incorrect format. The same happens also in case of a string passed as parameter but it does not represent a valid numeric value.
- The delay is not defined.
- The notification will indicate that the delay not defined. Also, an exception is traced in the Log Viewer.
For each of the cases above, the error is traced in the Script Editor (Error List expander).
Examples of Use
How to stop the script execution for 3 seconds by directly passing the value
sleep(3000);
How to stop the script execution for 5 seconds by passing a variable properly valued
var timeout = 5000;
sleep(timeout);
How to stop the script execution for 5 seconds by passing a variable valued with a string that represents a number
var timeout = “5000”;
sleep(timeout);
How to execute a script that includes a sleep instruction (sleep time = 60 seconds)
//Sleep for 60 seconds (in D-CC Scripting EM code)
sleep(60000);
- If the script timeout is not set (such as, Timeout =
00:00:00 hh:mm:ss
), the script ends with Activity Status =Idle
as soon as the sleep time elapses. - If the script timeout is longer than the sleep time, the script ends as soon as the sleep time elapses.
- If the script timeout shorter than the sleep time, the script ends (Last Execution Status is
Timed out as soon as the timeout elapses
.)
How to execute a script that includes a subscription and a sleep instruction in the callback (sleep time = 60 seconds)
var result =
subscribeValues("System1.ManagementView:ManagementView.SystemSettings.OrganizationModes.DayNight",
"Value", onOrganizationModeChanged);
function onOrganizationModeChanged(object, values)
{
console("New value = {0}", values.Value.Value);
//Sleep for 60 seconds
sleep(60000);
}
- If the script timeout is not set (such as, Timeout =
00:00:00 hh:mm:ss
), the script remains in Activity Status =Running
until the user clicks the Stop command. Each callback takes at least 60 seconds to be processed. - If the script timeout is set, the script ends. Last Execution Status is
Timed out
as soon as the timeout expires. Meanwhile, the callback is invoked whenever a change of value occurs, taking at least 60 seconds to be processed. If the script timeout expires while the callback is being processed, the execution of the script is interrupted.
setTimeout
The setTimeout
method allows scheduling the execution of a one-time callback after a specific interval of time (expressed in milliseconds).
Syntax
It is possible to delay the execution of a callback. See the following syntax:
setTimeout(<callback>, <delay>, <args>);
Parameters Usage
Parameter | Type | Default | Use | Annotation |
callback | Function | - | - | Reference to the callback function that will be executed after the specified time delay. JavaScript allows providing the name of the function or directly embedding the function definition. |
delay | Integer | - | Mandatory | Time delay (in milliseconds) after which the callback will be invoked. |
args | Object | - | Optional | List of parameters that will be passed to the callback method when it is executed. |
Result
- The return value of the
setTimeout
method is theTimeoutObject
that includes the reference to the timeout. This value is necessary for interrupting the delayed execution of the callback (see clearTimeout).
Error Handling
Errors can occur in case:
- The callback is not defined.
- The script ends with the following error:
callback is not defined
. - Invalid delay (for example, negative number)
- The script ends with the following error:
Invalid input
.
Examples of Use
How to execute a callback function after a specified delay (without arguments)
In the following code sample, the function delayedExecution
is after 2 seconds while the instructions after the setTimeout
are immediately executed.
function delayedExecution() {
console("I will be executed after some time");
}
setTimeout(delayedExecution, 2000);
console("I am executed immediately");
The output in the Console expander is : "I am executed immediately"
.
How to execute an inline callback after a specified delay (without arguments)
In the following code sample, the function is directly specified in the setTimeout invocation.
setTimeout(function() { console("Hello!") }, 2000);
The output in the Console expander after at least 2 seconds from the script start is: "Hello!"
.
How to execute a function after a specified delay (with args)
In the following code sample, a list of parameters is provided to the callback that will be invoked after the specified delay.
function delayWithParam(param1) {
console("I was called with param: " + param1);
}
setTimeout(delayWithParam, 2000, "hello");
It is also possible to specify multiple parameters:
function delayWithParam(param1, param2) {
console("I was called with params: {0} {1}", param1, param2);
}
setTimeout(delayWithParam, 2000, "hello", "world");
The output in the Console expander after at least 2 seconds from the script start is: "I was called with param: hello"
(or "I was called with params: hello world"
). Note that one or multiple parameters were passed to the callback function.
How to execute a delayed function while receiving a change of values from a subscription
In the following code sample, the callbacks are executed from the subscribeValues method while waiting for the delayed execution. If the value of the object changes, the callback changeValue is executed (this is not possible with the sleep method).
setTimeout(delayedExecution, 3000);
...
function delayedExecution() {
console("delayed");
}
subscribeValues("System1.ApplicationView:ApplicationView.Logics.VirtualObjects.analog", "Value", changeValue);
...
function changeValue(object, values) {
console("Change of value");
}
The output in the Console expander after at least 3 seconds from the script start is: "
delayed"
while, at each change of the property Value
of the analog virtual object, the output is: "Change of value"
.
Note also that the callback of the delayed execution can be executed only after the specified delay (as the time when the subscription callback is called is unknown as well as how long the callback will take to complete its execution.)
clearTimeout
The clearTimeout
method allows blocking a queued delayed execution before it starts.
Syntax
It is possible to prevent a timeout from triggering. See the following syntax:
clearTimeout(<timeoutObject>)
Parameters Usage
Parameter | Type | Default | Use | Annotation |
timeoutObject | TimeoutObject | - | Mandatory | Value that is returned by the setTimeout method. |
Error Handling
Errors can occur in case:
- The
clearTimeout
method is called without passing a valid timeout object. - The script ends with the following error:
Invalid timeout object
.
Examples of Use
How to block a delayed callback execution before its execution starts
The following code sample illustrates how the delayed execution is stopped using the clearTimeout
method and passing the result of the setTimeout method invocation. The delayed method will not be executed.
function delayed() {
console("you should not see me!");
}
var timeoutObject = setTimeout(delayed, 5000);
sleep(2000);
clearTimeout(timeoutObject);
console("I have stopped the timeout object");
The output in the Console expander after at least 2 seconds from the script start is: "
"I have stopped the timeout object"
. No output in the Console expander after at least 5 seconds (the call of the clearTimeout
cancels the delayed execution of the delayed()
function).
setInterval
The setInterval
method allows scheduling the repeated execution of a callback.
Syntax
It is possible to specify repeated executions of a callback. See the following syntax:
setInterval(<callback>, <interval>, <args>)
Parameters Usage
Parameter | Type | Default | Use | Annotation |
callback | Function | - | - | Reference to the callback function that will be executed after the specified time delay. JavaScript allows providing the name of the function or directly embedding the function definition. |
interval | Integer | - | Mandatory | Interval of time (in milliseconds) between the repeated invocations. |
args | Object | - | Optional | List of parameters that will be passed to the callback method when it is executed. |
Result
- The return value of the
setInterval
method is the IntervalObject that includes the reference to the interval of time. This value is necessary for interrupting the execution of the callback function before its execution (see clearInterval below).
Error Handling
Errors can occur in case:
- The callback is not defined.
- The script ends with the following error:
callback is not defined
. - Invalid interval (for example, negative number)
- The script ends with the following error:
Invalid input
.
Examples of Use
How to execute a callback repeatedly without parameters
function repeatMe() {
console("I am repeating");
}
setInterval(repeatMe, 1000);
The output in the Console expander is : "I am repeating"
. The callback repeatMe is repeated each second during the script execution that can be stopped only manually.
clearInterval
The clearInterval
method allows stopping the invocation of a repeated execution.
Syntax
It is possible to stop an interval from triggering. See the following syntax:
clearInterval(<intervalObject>)
Parameters Usage
Parameter | Type | Default | Use | Annotation |
intervalObject | IntervalObject | - | Mandatory | Value that is returned by the setInterval method. |
Error Handling
Errors can occur in case:
- The
clearInterval
method is called without passing a valid interval object. - The script ends with the following error:
Invalid interval object
.
Examples of Use
How to execute a callback repeatedly and stop it after some iterations
In the following code sample, the execution of the callback repeatMe is repeated four times. Then the clearInteval method is called and the script ends.
var count = 1;
function repeatMe() {
console("I am repeating: " + count);
if (count == 4) {
clearInterval(intervalObject);
}
count++;
}
var intervalObject = setInterval(repeatMe, 1000);
The output in the Console expander is : “I am repeating 1",
"I am repeating 2"
, "I am repeating 3"
, and "I am repeating 4"
. Note that the script automatically ends after the four-time execution.
var count = 1;
function repeatMe(num) {
console("I am repeating: " + count);
if (count == num) {
clearInterval(intervalObject);
}
count++;
}
var intervalObject = setInterval(repeatMe, 1000, 5);
The above example is similar to previous but the execution limit is passed as parameter to the setInterval method.