@Return (Formula Language)

Immediately stops the execution of a formula and returns the specified value. This is useful when you only want the remainder of the formula to be executed only if certain conditions are True.

Syntax

@Return( value )

Parameters

value

The value you want returned. You can specify another @function such as @Error, or a text string such as "Formula stopped," or a Boolean value (True or False). If you don't want anything returned, use the null string ("").

Return value

result

Returns value.

Usage

@Return is most useful in field formulas, agents that run formulas, and toolbar buttons. Generally, you use it with @If to determine whether to perform @Return or to perform one or more other statements.

@Return should not be used in column formulas.

Examples

  1. This formula displays a dialog box offering the user a Yes/No choice. If the user selects Yes, the next document in the view is opened; if the user selects No, the formula stops and nothing more happens.
    @If(@Prompt([YesNo];"Continue?";"Do you want to continue reading your mail?");@Command([NavNext]);@Return(""))
  2. This formula tests whether an environment variable called OrderNumber has been stored in the user's NOTES.INI or Notes® Preferences file. If there is no such variable stored, @SetEnvironment is used to initialize it to zero. If a value has already been stored, @Return is used to return it and stop the formula from executing.
    @If(@Environment(OrderNumber)="";@SetEnvironment("OrderNumber";
"0");@Return(@Environment("OrderNumber")))
  3. The following code, when added to a field that displays the result of a database lookup, returns a customized error message if an error is encountered during that lookup. The temporary variable, "lookup," retrieves the job title (located in column 3 of the "People" view) of the person listed in the first sorted column of the "People" view. If an error is encountered during the lookup, the field displays the specified error message in a dialog box and "1" displays in the field, indicating that there was an error encountered. 
    lookup := @DbLookup("" : "" ; "serverName" : "fileDirectory\\databaseName.nsf"; "People" ; "Jackie Brown"; 3);
@If(@IsError(lookup); @Return(@Prompt([OK];"Error";"Error locating the requested job title. Aborting lookup")); lookup)