R5 Application Development 1 for Notes and Domino
R5 Application Development 2 for Notes and Domino
R5 Application Development 3 for Notes and Domino


Error Checking During Lookups

It is good practice to always check for any possible errors when using @dbcolumn or @dblookup. Take for example the following two fields:

PartName displays a dialog list of all available parts and then Price uses the following formula to lookup the price:

key := PartName;
sPath := @LeftBack(@LowerCase(@Subset(@DbName; - 1)); "5ad3wrkb.nsf" ) ;
database := sPath + "badpart.nsf" ;
@DbLookup( "Notes" : "NoCache" ; "" : database ; "PartsLookupView" ; key ; 2 );

Whenever a @DbColumn or @DbLookup call fails for any reason, it returns a numeric error code that the Notes Client uses to display an appropriate error message. If your formula later uses the returned lookup value to set a field value, Notes sets the field to the error message. If your formula uses the lookup value in subsequent statements, your code won't work properly.

To avoid field errors or problems in your code, it is a good practice to always check for errors when you perform a lookup operation. The Notes Formula Language provides two @functions that enable you to trap an error that occurs during a lookup operation and to gracefully handle the situation. These functions are:

• @IsError
• @Return

@IsError

The @IsError function determines whether the value you pass to it is an error code. This process is often called trapping an error. @IsError has the following syntax:

@IsError( value )

@Return

The @Return function immediately stops the execution of a formula. This function takes any value you want to pass to it. You can find many uses for this function:

• To set a field value when used in a field formula
  
  

  @Return("The field value")

  
  
• To halt formula execution without doing anything
  
  

  @Return("")

  
  
• To stop the formula execution and display a helpful message to the user
  
  

  @Return(@Prompt([OK]; "Lookup error"; "Problem with price lookup.  Contact support and report the problem."))

Combining @IsError and @Return to Handle Errors

You can combine these two functions to add error handling capabilities to your code. The following code fragment shows the technique. Line 1 tests to make sure a partname has been selected before doing the lookup using the partname value as the lookup key. The @return function will stop processing of the formula if the partname is blank and return a null value ("") to the Price field. Lines 3 and 4 access the current database to determine its location and then use that information to specify the location of the Parts database. Line 5 performs the lookup and assigns the result of the lookup to the returnedvalue temporary variable. Line 6 checks the returned lookup value for an error and prompts the user with an understandable message if @IsError returns True. The Price field is set to a null value using @setfield. Use of the @do function allows both the @prompt and the @setfield function to be combined into one statement that works in the @if function.

1.	@if(partname = ""; @return(""); "");
2.	key := PartName;
3.	sPath := @LeftBack(@LowerCase(@Subset(@DbName; - 1)); "5ad3wrkb.nsf" ) ;
4.	database := sPath + "badpart.nsf" ;
5.	returnedvalue := @DbLookup( "Notes" : "NoCache" ; "" : database ; "PartsLookupView" ; key ; 2 );
6.	@if(@iserror(returnedvalue);       @do(         @prompt([OK];"Error";"Error in lookup, please contact support.");         @setfield("Price"; ""));   returnedvalue);