waitUntil Function

The waitUntil method allows waiting until certain properties have specific values before proceeding with the execution of a script.

It is possible to wait until the value of one or multiple properties of one or multiple system objects satisfy the given reference values or conditions.

Syntax

var result = waitUntil(<objectReferences>, <properties>, <referenceValuesOrConditions>, <timeout>,

<singleCondition>)

Parameters Usage

Parameter	Type	Default	Use	Annotation
objectReferences	String BrowserObject Point String Array BrowserObject Array Point Array	-	Mandatory	CNS full path (reference to system objects).
properties	String String Array	-	Mandatory	Names of the properties whose values are to monitor. A property can be specified multiple times so to allow the definition of multiple reference values or conditions for the same property.
referenceValuesorConditions	Value Value Array JSON String JSON String Array	-	Mandatory	For each property defined in the `<properties>` parameter it is possible to specify the corresponding reference values or conditions to match. See below for the types and operators supported. If a simple value is specified, the corresponding property must be equal to that value. If the conditions is specified with a JSON string (for example, `{"<" : -3})`, it is possible to use different operators for the comparison. The execution will continue when the properties get the values or satisfy the conditions defined in this set with good quality. Note that the number of items must match the number of properties defined in the `<properties>` parameter.
timeout	Integer	0	Optional	Maximum time (expressed in milliseconds) allowed for the specified `<properties>` to match the given reference values, or to satisfy the specified conditions. The script continues its execution as soon as - The reference values or conditions are satisfied. - The timeout expires, even if the conditions are not satisfied. By checking the property `isSatisfied` of the returned object, it is possible to determine whether the timeout has expired. If the timeout value is 0, not defined, or null, the script is blocked until the reference values or conditions are satisfied.
singleCondition	Boolean	False	Optional	Whether the execution will continue when at least one system object matches the specified conditions. In case of one system object only, this option can be ignored. Other admissible values: 1/0, or "true"/"false" (no case-sensitive). If false, not defined, or null, all the `<properties>` must satisfy the corresponding `<referenceValuesOrConditions>`. If true, at least one property must satisfy `<reference valuesOrConditions>`.

Supported Data types and Operators

DataType

Allowed Operators

SInt32

UInt32

Bit32

Double

String

DateTime

Bool

SInt32Array

UInt32Array

Bit32Array

DoubleArray

StringArray

TimeStampArray

BoolArray

Result

If the reference values or conditions match, the waitUntil method returns the WaitUntilResult object with the property isSatisfied = true and the property objects that contains the collection of BrowserObjects that unblocked the waitUntil call.
If any errors occur, the waitUntil method returns the WaitUntilResult object with the error property that indicates the reason why the operation failed.

Scenarios that can be implemented

Scenario

The script waits until…

Annotation

Examples

one property of…
one individual object matches…
one specific value or condition.

It is possible to pass the parameter <timeout> to stop waiting when the timeout expires.

It is not meaningful to pass the parameter <singleCondition> because there is only one system object involved.

waitUntil(“obj1”, “prop1”, 3)

The script continues its execution when prop1 of obj1 has value equal to 3.

waitUntil(“obj1”, “prop1”, {">" : 3})

The script continues its execution when prop1 of obj1 has value greater than 3.

var result = waitUntil(“obj1”, “prop1”, {"!=" : 0}, 30000)

The script waits at the most 30 seconds for prop1 of obj1 to have a value different from 0. If the timeout expires, result.isSatisfied is false.

one property of…
one individual object matches…
a specific value or condition in a given set of values or conditions.

It is possible to specify the same property multiple times so to allow the definition of multiple reference values or conditions to match.

The OR logic applies among the conditions on the same property.

It is possible to pass the parameter <timeout> to stop waiting when the timeout expires.

It is not meaningful to pass the parameter <singleCondition> because there is only one system object involved.

waitUntil(“obj1”, [“prop1”, “prop1”], [3, 4])

The script continues its execution when prop1 of obj1 has value equal to 3 OR equal to 4.

var result = waitUntil(“obj1”, [“prop1”, “prop1”], [{"<" : -3}, {">" : 10}], 60000)

The script waits at the most 1 minute for prop1 of obj1 to have a value less than -3 OR greater than 10. If the timeout expires, result.isSatisfied is false.

different properties of…
one individual object match…
one or multiple specific values or conditions.

For each different property it is necessary to specify the corresponding value or condition to match.

The AND logic applies among properties of the same object.

It is possible to pass the parameter <timeout> to stop waiting when the timeout expires.

It is not meaningful to pass the parameter <singleCondition> because there is only one system object involved.

waitUntil(“obj1”, [“prop1”, “prop2”], [“hello”, “world”])

The script continues its execution when prop1 of obj1 is equal to “hello” AND prop2 of obj1 is equal to “world”.

var result = waitUntil(“obj1”, [“prop1”, “prop2”], [{"==" : “hello”}, {"!=" : “world”}], 60000)

The script waits at the most 1 minute for prop1 of obj1 to have value equal to “hello” and prop2 of obj1 to have value different from “world”. If the timeout expires, result.isSatisfied is false.

waitUntil(“obj1”, [“prop1”, “prop2”, “prop2”], [“hello”, “world”, “universe”])

The script continues the execution when prop1 of obj1 is equal to “hello”

AND

- prop2 of obj1 is equal to “world”

- prop2 of obj1 is equal to “universe.”

one property of…
different objects matches…
one or multiple specific values or conditions.

If <singleCondition> is false, the AND logic applies among the same properties of different objects.

If <singleCondition> is true, the OR logic applies among the same properties of different objects, since it is enough to have a single condition satisfied.

The OR logic applies among the conditions on the same property.

It is possible to pass the parameter <timeout> to stop waiting when the timeout expires.

In all the cases, if result.isSatisfied is true, result.objects contains the collection of BrowserObjects that unblocked the waitUntil call.

var result = waitUntil([“obj1”, “obj2”], “prop1”, 11)

The script continues the execution if both prop1 of obj1 AND prop1 of obj2 are equal to 11.

var result = waitUntil([“obj1”, “obj2”], “prop1”, 11, 0, true)

The script continues the execution if prop1 of obj1 OR prop1 of obj2 is equal to 11.

var result = waitUntil([“obj1”, “obj2”], “prop1”, {">" : 9}, 30000)

The script waits at the most 30 seconds for both prop1 of obj1 AND prop1 of obj2 to be greater than 9. If the timeout expires, result.isSatisfied is false.

var result = waitUntil([“obj1”, “obj2”], “prop1”, {"!=" : “”}, 30000, true)

The script waits at the most 30 seconds for prop1 of obj1 OR prop1 of obj2 to be different than empty string. If the timeout expires, result.isSatisfied is false.

var result = waitUntil([“obj1”, “obj2”], [“prop1”, “prop1”], [10, 20])

The script continues the execution if:

- prop1 of obj1 is equal to 10 OR 11.

AND

- prop1 of obj2 is equal to 10 OR 11.

var result = waitUntil([“obj1”, “obj2”], [“prop1”, “prop1”], [10, 20], 0, true)

The script continues the execution if:

- prop1 of obj1 is equal to 10 OR 11.

- prop1 of obj2 is equal to 10 OR 11.

different properties of…
different objects match…
one or multiple specific values or conditions.

For each different property it is necessary to specify the corresponding value or condition to match.

The AND logic applies among properties of the same object.

If <singleCondition> is false, the AND logic applies among the same properties of different objects.

If <singleCondition> is true, the OR logic applies among the same properties of different objects, since it is enough to have a single condition satisfied.

The OR logic applies among the conditions on the same property.

It is possible to pass the parameter <timeout> to stop waiting when the timeout expires.

In all the cases, if result.isSatisfied is true, result.objects contains the collection of BrowserObjects that unblocked the waitUntil call.

var result = waitUntil([“obj1”, “obj2”], [“prop1”, “prop2”], [3.5, 4.5])

The script continues the execution if:

- prop1 of obj1 AND prop1 of obj2 are equal to 3.5.

AND

- prop2 of obj1 AND prop2 of obj2 are equal to 4.5.

var result = waitUntil([“obj1”, “obj2”], [“prop1”, “prop2”], [{"==" : 15}, {">=" : 50}], 30000, true)

The script waits at the most 30 seconds for:

- prop1 of obj1 AND prop1 of obj2 to be equal to 15.

- prop2 of obj1 AND prop2 of obj2 to be greater than or equal to 50.

If the timeout expires, result.isSatisfied is false.

var result = waitUntil([“obj1”, “obj2”], [“prop1”, “prop1”, “prop2”], [{"==" : 20}, {"==" : 30}, {"!=" : “”}])

The script continues the execution if:

- prop1 of obj1 AND prop1 of obj2 are equal to 20 OR 30.

AND

- prop2 of obj1 AND prop2 of obj2 are different from empty string.

Error Handling

When an error occurs, the script continues its execution and the waitUntil result contains an error indicating the reason why the waitUntil failed.

Errors occurs in case:

The parameter <objectReferences> contains:

Duplicated objects and/or duplicated names
Null, empty, or invalid designation
Invalid object type

The parameter <properties> contains:

Null or empty name
A property that does not exist for the specified objects
An invalid object type

The parameter <referenceValuesOrConditions> contains:

At least one null value
A number of elements that does not match the number of reference values or conditions.
Values whose type is not compatible with the corresponding property type. For example, a condition that specifies value 3 can be used simultaneously for properties of type GmsInt and GmsReal, while a condition with value 3.5 generates an error if applied to properties of type GmsInt.

The parameter <timeout> contains:

A negative value
An invalid object type

The parameter <singleCondition> contains:

An invalid object type

Examples of Use

How to wait until the DayNight organization mode has value “Night” (1)

var result = waitUntil("System1.ManagementView:ManagementView.SystemSettings.OrganizationModes.DayNight", "Value", 1);

console("waitUntil isSatisfied: {0}",result.isSatisfied);

When the Value property of the Day Night Organization Mode is Night (1), the script continues its execution and the output in the Console expander is waitUntil isSatisfied: true.

How to wait until the DayNight and OccupancyStatus organization modes have value 1

var obj1 = new BrowserObject("System1.ManagementView:ManagementView.SystemSettings.OrganizationModes.DayNight");

var obj2 = new BrowserObject("System1.ManagementView:ManagementView.SystemSettings.OrganizationModes.OccupancyStatus");

var result = waitUntil([obj1,obj2],"Value", 1);

console("waitUntil isSatisfied: {0}", result.isSatisfied);

When the Value property of the DayNight Organization Mode is “Night” (1) and the Value property of the OccupancyStatus Organization Mode is “Unoccupied” (1), the script continues its execution and the output in the Console expander is: waitUntil isSatisfied: true.

How to wait until one of the organization modes DayNight or OccupancyStatus has value 1 (singleValue = true)

var obj1 = new BrowserObject("System1.ManagementView:ManagementView.SystemSettings.OrganizationModes.DayNight");

var obj2 = new BrowserObject("System1.ManagementView:ManagementView.SystemSettings.OrganizationModes.OccupancyStatus");

var result = waitUntil([obj1,obj2],"Value", 1, 0, true);

console("waitUntil isSatisfied: {0}", result.isSatisfied);

When the Value property of the DayNight Organization Mode is “Night” (1) or the Value property of the OccupancyStatus Organization Mode is “Unoccupied” (1), the script continues its execution and the output in the Console expander is: waitUntil isSatisfied: true. The object that unblocked the waitUntil call is retrieved in result.objects (it can be one object only or both if they change simultaneously).

How to wait until a virtual object of type GMS_Virtual_Analog has value greater than or equal to 10

var obj = new BrowserObject("System1.ApplicationView:ApplicationView.Logics.VirtualObjects.Analog1");

var result = waitUntil(obj, "Value", {“>=” : 10}, 30000);

console("waitUntil isSatisfied: {0}", result.isSatisfied);

If the Value property of the Analog1 object gets greater than or equal to 10 within 30 seconds, the script continues its execution and the output in the Console expander is: waitUntil isSatisfied: true. If the timeout of 30 seconds expires, the output in the Console expander is: waitUntil isSatisfied: false.

How to wait until one of the children of a Virtual Objects Folder gets a value greater than 0, waiting at the most for 5 minutes (timeout specified, singleValue = true)

var objects = getChildren("System1.ApplicationView:ApplicationView.Logics.VirtualObjects.VirtualFolder").browserObjects;

var result = waitUntil(objects, "Value", { ">" : 0}, 5 * 60000, true);

console(result);

As soon as one of the child nodes of the VirtualFolder parent gets a value greater than 0 or the timeout of 5 minutes elapses, the script continues its execution and the output in the Console expander indicates whether (result.isSatisfied = true and result.objects contains the unblocking object) or not (result.isSatisfied = false) the condition is satisfied.

How to wait until different properties of the same object have a specific value

waitUntil("System1.ApplicationView:ApplicationView.Logics.Scripts.AnotherScript", ["OperationalStatus", "Status"], [0, 0]);

The script waits for AnotherScript to have its OperationalStatus = Enabled (0) and its Status = Idle (0)

How to start a script then wait until it completes its execution

var scriptObj = new BrowserObject("System1.ApplicationView:ApplicationView.Logics.Scripts.AnotherScript");

executePropertyCommand(scriptObj, "Status", "Start");

var result = waitUntil(scriptObj, "Status", 0);

The script starts AnotherScript then waits until it completes its execution. For example, Status = Idle (0).

How to wait until a script gets disabled and some text is set in its Notes property

var result = waitUntil("System1.ApplicationView:ApplicationView.Logics.Scripts.AnotherScript", ["OperationalStatus", "Notes"], [ 1, { "!=" : ""}], &= * 60000);

if (result.isSatisfied)

console("AnotherScript was disabled with a note");

The script waits, with a timeout of 1 hour, until AnotherScript is disabled (OperationalStatus = 1) and something is written in its Notes property (Notes is not the empty string).

How to wait until all the objects of type GMS_Virtual_Integer and GMS_Virtual_Analog under a specific node have value different from 0

var filter = new Filter();

filter.objectModel = ["GMS_Virtual_Integer", "GMS_Virtual_Analog"]

filter.designation = "System1.ApplicationView:ApplicationView.Logics.VirtualObjects.VirtualFolder";

var objects = searchSync(filter);

var result = waitUntil(objects, "Value", { "!=" : 0});

The script waits for all the objects of type GMS_Virtual_Integer and GMS_Virtual_Analog under the VirtualFolder parent to have their Value property different from 0.

Note that the Value property of GMS_Virtual_Integer objects is of type GmsInt, while the Value property of GMS_Virtual_Analog objects is of type GmsReal. It is possible to apply the same condition ({ "!=" : 0}) to them because the value 0 is compatible with both GmsInt and GmsReal.

How to wait until with multiple conditions on the same property

var result = waitUntil("System1.ApplicationView:ApplicationView.Logics.VirtualObjects.Analog", ["Value", "Value"], [{"<" : 10}, {">" : 20}]);

The script waits until the property Value of the Analog object gets a value less than 10 or greater than 20.