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 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 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,
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 |
timeout | Integer | 0 | Optional | Maximum time (expressed in milliseconds) allowed for the specified 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 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 If true, at least one property must satisfy |
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 propertyisSatisfied
= true and the propertyobjects
that contains the collection of BrowserObjects that unblocked thewaitUntil
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 |
| It is possible to pass the parameter
It is not meaningful to pass the parameter | 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, | ||
| 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
It is not meaningful to pass the parameter | 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, | ||
| 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
It is not meaningful to pass the parameter |
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, | ||
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” OR - prop2 of obj1 is equal to “universe.” | ||
| If
If
The OR logic applies among the conditions on the same property.
It is possible to pass the parameter
In all the cases, if | 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, | ||
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, | ||
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. OR - prop1 of obj2 is equal to 10 OR 11. | ||
| 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
If The OR logic applies among the conditions on the same property.
It is possible to pass the parameter
In all the cases, if | 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. OR - prop2 of obj1 AND prop2 of obj2 to be greater than or equal to 50. If the timeout expires, | ||
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.