AWAITANY function

AWAITANY(Promises, OnSuccess?, OnFailure?) AWAITANY(Promises; OnSuccess?; OnFailure?)

Promises

{ Promise }

The promises.

OnSuccess

(optional)

A formula fragment that is run when the first promise succeeds. The result returned by this promise is available under the name Result and the position of this promise in the promises array is available under the name Index.

OnFailure

(optional)

A formula fragment that is run if all promises fail. The errors returned by the promises are available as an array under the name Errors. Refer to the documentation for the action functions returning the promises to learn what information is available on individual errors. Use INDEX to retrieve them.

If all promises fail, 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

Promise

A promise, which succeeds when the first of the given promises succeeds and fails if all of the given promises fail. If the promise succeeds, the returned value is the result of the promise that succeeded. If the promise fails, the returned value is an array of all the errors returned by the promises.

Waits for the first of multiple promises to succeed before running an action. AWAITANY({ EMAILREPORT({ App }, "user1@example.com"), EMAILREPORT({ Result }, "user2@example.com") }, BANNER("First report sent"))AWAITANY({ EMAILREPORT({ App }; "user1@example.com"); EMAILREPORT({ Result }; "user2@example.com") }; BANNER("First report sent")) sends two reports and shows the banner First report sent when confirmation is received that either of the two reports has been sent successfully.

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

AWAITANY and other similar functions are used to take action when a promise succeeds or fails.

Taking action when the first of many promises succeeds

AWAITANY runs the formula fragment given as its second parameter as soon as a promise given to it succeeds. The result returned by this promise is available under the name Result and the position of this promise in the promises array is available under the name Index.

Let's look at the example formula again:

AWAITANY({ EMAILREPORT({ App }, "user1@example.com"), EMAILREPORT({ Result }, "user2@example.com") }, BANNER("First report sent"))AWAITANY({ EMAILREPORT({ App }; "user1@example.com"); EMAILREPORT({ Result }; "user2@example.com") }; BANNER("First report sent"))

The two promises given to AWAITANY are returned from EMAILREPORT, which sends two reports. The promise returned from EMAILREPORT succeeds when it receives confirmation that a report has been successfully sent.

While sending the report bound for user1@example.com is initiated before the one bound for user2@example.com, there is no telling which report will be successfully sent first. AWAITANY picks the first promise to succeed and forwards its result, and its position in the promises array, to its second parameter.

Handling errors

The formula fragment given as the third parameter to AWAITANY is only run if all promises fail. If that is the case, the errors returned by the promises are available as an array under the name Errors.

This is different from how AWAITRACE works. Both functions perform identically when handling promises that succeed, but handle errors differently. AWAITRACE does not wait for all promises to fail before running the formula fragment given as its third parameter, it invokes it immediately once the first promise to return a result has failed. AWAITANY, on the other hand, waits for all promises to fail before invoking the formula fragment given as its third parameter.

Examples

AWAITANY({ EMAILREPORT({ App }, "user1@example.com"), EMAILREPORT({ Result }, "user2@example.com") }, BANNER("First report sent"))AWAITANY({ EMAILREPORT({ App }; "user1@example.com"); EMAILREPORT({ Result }; "user2@example.com") }; BANNER("First report sent"))

Sends two reports and shows the banner First report sent when the first report to make it through has been sent.

AWAITANY({ EMAILREPORT({ App }, "user1@example.com"), EMAILREPORT({ Result }, "user2@example.com") }, OnFailure: BANNER("Sending all reports failed"))AWAITANY({ EMAILREPORT({ App }; "user1@example.com"); EMAILREPORT({ Result }; "user2@example.com") }; OnFailure: BANNER("Sending all reports failed"))

Sends two reports and shows the banner Sending all reports failed if both reports could not be sent.