Run-time errors

Run-time errors occur when the formula runs. These errors can be categorized as follows:

• Unexpected -- These are development errors that your users should never see. For example, if you forget an @function parameter, the following message appears at run-time: "Insufficient arguments for @function." You should test your formula and attempt to correct all unexpected errors.
• Unreported -- These are results that are incorrect but are not reported as errors. For example, if you try to display a numeric value with @Prompt, @Prompt works but displays a blank. Again, your user should never see these errors. You should test your formula and ensure that all results are as expected.
• Expected -- These are errors that the user might cause at run-time. For example, if you prompt for the name of a database, the user might enter the name of a nonexistent database. You cannot prevent these errors, but you can anticipate and test for them in the formula and take appropriate actions.

The following @functions help you deal with run-time errors:

• @IsError(value) returns True (1) if a field, temporary variable, or expression contains an error.

• @Error generates an error.
• @Failure(message) displays a message when used in an input validation formula.
• @Success always returns the value 1.
• @Return(value) stops execution of the formula and returns a value.

Notes® generates an error for a field if the built-in validation checking fails. For example, if you specify a field as numeric and the user enters a non-numeric value, Domino® makes the value of the field an error. You can generate an error for a field by setting its value to @Error.

Notes reports errors in fields when the user attempts to save the document. For example, if a numeric field contains a non-numeric value, Domino generates the message "Cannot convert text to a number" when the user attempts to save a document.

To change the message or perform another action when an error occurs, test the field for an error with @IsError in the field validation formula. You can generate your own error message with @Failure, but only in field validation formulas.

To incorporate your own error conditions for a field, return @Error if you detect an error condition.

Outside field formulas, for example, in an agent, button, or hotspot, you can check the contents of a field and react immediately to an error condition. For example, if you check a field with a button, you can change the field value or report the error before the user attempts to save the document. In checking for errors, be aware that the built-in validation checking generates an error as soon as the user enters a value in a field, but that a translation formula using @Error does not generate an error until the user attempts to save the document.