Other Time-related Functions

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

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 a System.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 terminates with Activity Status = Idle as soon as the sleep time elapses.
• If the script timeout is longer than the sleep time, the script terminates as soon as the sleep time elapses.
• If the script timeout shorter than the sleep time, the script terminates (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 terminates. 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

Result

• The return value of the setTimeout method is the TimeoutObject 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 terminates with the following error: callback is not defined.
• Invalid delay (for example, negative number)
• The script terminates 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

Error Handling

Errors can occur in case:

• The clearTimeout method is called without passing a valid timeout object.
• The script terminates 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

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 terminates with the following error: callback is not defined.
• Invalid interval (for example, negative number)
• The script terminates 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

Error Handling

Errors can occur in case:

• The clearInterval method is called without passing a valid interval object.
• The script terminates 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 terminates.

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