Use the wait object to wait for a particular session or screen state. For example, you can wait until the cursor is found at a particular location or text is present at a certain location before continuing with the macro execution.
Wait functions are often used in conjunction with asynchronous functions such as connect() and sendKeys().
NOTE:All functions take timeouts as an optional parameter and have a default time out value of 10 seconds (10000ms).
Important: All wait functions require the ‘yield’ keyword in front of them. This allows the macro to block execution until the conditions of the wait function are met.
[parameter] denotes an optional parameter.
Table 5-36 Waiting for the host
|
METHODS |
|
|---|---|
|
setDefaultTimeout(timeout) |
Sets the default timeout value for all functions. Parameters {Number} default timeout to use for all wait functions in milliseconds. Returns None Throws {RangeError} If the specified timeout is less than zero. |
|
forConnect([timeout]) |
Waits for a connect request to complete. Parameters {Number} in milliseconds. Returns {Promise} Fulfilled if the session is already connected or when connection occurs. Rejected if the wait times out. |
|
forDisconnect([timeout]) |
Waits for a disconnect request to complete. Parameters {Number} timeout in milliseconds. Returns {Promise}Fulfilled if the session is already disconnected or when it finally disconnects. Rejected if the wait times out. |
|
forFixedTime([timeout]) |
Waits unconditionally for fixed time. Time is in milliseconds (ms) Parameters {Number} timeout in milliseconds. Returns {Promise}Fulfilled after time elapses |
|
forScreenChange([timeout]) |
Waits for the host screen to change. This function returns when a screen update is detected. It makes no guarantees about the number of subsequent updates that may arrive before the screen is complete. Waiting repeatedly until the screen contents match some known stopping criteria is advisable. Parameters {Number} timeout in milliseconds. Returns {Promise} Resolved if the screen change. Rejected if the wait times out. |
|
forCursor(position, [timeout]) |
Waits for the cursor to arrive at the specified position. Parameters {Position} The position specifying the row and column, {Number} timeout in milliseconds Returns {Promise}Fulfilled if the cursor is already located or when it is finally located. Rejected if the wait times out. |
|
forText(text, position, [timeout]) |
Wait for text located at a specific position on the screen Parameters {String} text to expect {Position} position specifying the row and column {Number}timeout in milliseconds Returns {Promise} Fulfilled if the text is already at the specified position or whenever it is located. Rejected if the wait times out. Throws {rangeError} if the position is not valid. |
|
forHostPrompt(text, column,[timeout]) |
Waits for a command prompt located at a particular column on the screen. Parameters {String} text prompt to expect {Number} column where cursor is expected {Number} timeout in milliseconds. Returns {Promise} Fulfilled if the conditions are already met or when the conditions are finally met. Rejected if the wait times out. Throws {rangeError} if the column is out of range. |
|
forHostSettle([settleTime],[timeout]) |
NOTE:wait.forHostSettle should only be used when other more targeted wait functions are insufficient. Monitors incoming screen data and resolves settleTime ms after the last update and the keyboard is unlocked. This function is useful when data arrives in multiple packets and you want to be sure the whole screen has been received before carrying on. Parameters {Number} time to wait after the last update to make sure more data doesn’t arrive unexpectedly. The default is 200 milliseconds. {Number} timeout in milliseconds. Returns {Promise} Fulfilled when the settle time has elapsed after receipt of the last screen update and the keyboard is unlocked. |