AWAITMANY function
Promises
The promises.
OnSuccess
A formula fragment that is run when a promise succeeds. If the promise
returns a result, this result is available under the name
Result. The position of the promise that succeeded in the
Promises array is available under the name
Index.
OnFailure
A formula fragment that is run when a promise fails. An error is
available under the name Error. Refer to the documentation
for the action function returning the promise to learn what information
is available on the error. The position of the promise that failed in
the Promises array is available under the name
Index.
If a promise fails, and you don't provide this parameter, your app displays an error message to your users. Use this parameter to show your own message instead, using a function like BANNER or ALERT. You can also provide BLANK()BLANK() as this parameter, if you don't want anything to happen if the promise fails.
Returns
A promise, which succeeds when and if all the given promises succeed and fails if a single one of those promises fails. If the promise succeeds, the returned value is an array of all the results returned by the promises. If the promise fails, the returned value is the error of the first promise to fail. The returned promise behaves identically to the promise returned from AWAITALL.
Waits for multiple promises to return responses before running actions. AWAITMANY({ EMAILREPORT({ App }, "user1@example.com"), EMAILREPORT({ Result }, "user2@example.com") }, BANNER("Report " & Index & " sent"))AWAITMANY({ EMAILREPORT({ App }; "user1@example.com"); EMAILREPORT({ Result }; "user2@example.com") }; BANNER("Report " & Index & " sent")) sends two reports and shows the banner Report 1 sent when the first report has been sent and the banner Report 2 sent when the second report has been sent.
This function can only be used from an action formula. It is typically invoked from a formula associated with the OnPress property of a formula button.
The first parameter to AWAITMANY must be an array of promises. A function returning such a value promises to return a value at some point in the future, or at the very least indicate whether the operation the function started was successful. A promise either succeeds or fails, and it can only succeed or fail once.
The promise returned from PROMPT succeeds when the user has entered a value and presses a button. The value returned is the text string the user entered. The promise returned from EMAILREPORT succeeds when the report has been successfully sent — with no value returned — and fails if there is a network problem.
AWAITMANY and other similar functions are used to take action when a promise succeeds or fails.
Handling promises, one at a time
AWAITMANY enables promises to be handled, one at a time. The second parameter to this function is a formula fragment which is run in response to the given promises succeeding. Similarly, the third parameter is a formula fragument which is run in response to the given promises failing.
If there are five promises in the array and three of those promises succeed and two fail, the second parameter is invoked three times and the third parameter is invoked twice.
Let's look at the example formula again:
When a formula fragment is run, it has access to the position of the promise
which succeeded or failed in the array of promises under the name
Index. That enables the formula above to display a banner with
the report number.
As with AWAIT, the
formula fragment given as the second parameter has access to the result of
the promise under the name Result. Finally, the formula fragment
given as the third parameter has access to a value named Error
with more information on what went wrong.
Example
Sends two reports and shows the banner Report 1 sent when the first report has been sent and the banner Report 2 sent when the second report has been sent.