AWAITRACE function

Waits for the first of multiple promises to return a response before running an action. AWAITRACE({ EMAILREPORT({ App }, "user1@example.com"), EMAILREPORT({ Result }, "user2@example.com") }, BANNER("First report sent"))AWAITRACE({ 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 AWAITRACE 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.

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

Taking action when the first of many promises succeeds

AWAITRACE waits for a promise to return a result, and runs the formula fragment given as its second parameter if the promise has succeeded. It runs the formula fragment given as its third parameter if the promise has failed.

The second parameter, if invoked, has access to the result returned by the promise under the name Result and the position of this promise in the promises array under the name Index.

Let's look at the example formula again:

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

The two promises given to AWAITRACE 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. AWAITRACE 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 AWAITRACE is run if the first promise to return a result has failed. The error returned by the promise is available under the name Error and the position of this promise in the promises array is available under the name Index.

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

Examples

AWAITRACE({ EMAILREPORT({ App }, "user1@example.com"), EMAILREPORT({ Result }, "user2@example.com") }, BANNER("First report sent"))AWAITRACE({ 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.

AWAITRACE({ EMAILREPORT({ App }, "user1@example.com"), EMAILREPORT({ Result }, "user2@example.com") }, BANNER("The first result was a success"), BANNER("The first result was a failure"))AWAITRACE({ EMAILREPORT({ App }; "user1@example.com"); EMAILREPORT({ Result }; "user2@example.com") }; BANNER("The first result was a success"); BANNER("The first result was a failure"))

Sends two reports and shows the banner The first result was a success if the first result was that of a report being sent successfully, and the banner The first result was a failure if the first result was that of a report not being sent successfully.