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.