Duffbert's Random Musings

Document Number:  1084493

Problem
Below is a listing of the common error messages reported when using @DbLookup and @DbColumn in formulas.  These errors come from a number of sources, ranging from incorrect syntax to a value not being found.  The order is roughly that in which the errors would occur, were you to commit more than one mistake in writing your formula.  You may capture any of these errors with the @IsError function.

Content
1.        Unknown @Function.  You will get this error message if you attempt to save a formula with an incorrectly spelled function, (e.g., @DbLooku [the 'p' at the end is missing]).

2.        Insufficient Arguments for @Function.  This message appears when the formula executes, if the @Db function is part of an another @Function, such as an @Prompt, and you have not included all of the parameters required by the other @Function.

3.        @If Must Have an Odd Number of Arguments.  Same as #2, but specifically for @If.

4.        Insufficient Arguments for Database Function.  Same as #2, but specifically for the @Db function itself.

5.        The necessary external database driver cannot be located.  'Notes' is misspelled in the class argument or the specified datalens driver cannot be found.  For example, @DbLookup("Nortes"; etc ... )

6.        The database was not found, please select servers to search.  If the Server Name was left out of the formula, you will get this error message.

7.        Server not responding.  The Server is either not responding or it is incorrectly specified in the formula.  To test: Manually try to open the server. If it can be opened, the name is probably specified incorrectly.

8.        ERROR: You are not authorized to perform that operation.  This error will occur if a Background Macro attempts to perform an @Db function against a non-local database (not on the same server).

9.        File Does Not Exist.  The @Db Function refers to a database which does not exist.  This often occurs because the formula has semicolons and colons in the wrong places.  For example, @DbLookup("Notes" ; "NoCache" ; etc ... ) is referring to a database called 'NoCache.nsf' which most probably is not what was intended!  Another common reason for this is directory paths.  If the database is found outside of the Notes Data Directory, you must specify the location.  For example, "C:\\Directory\\SubDirectory\\Filename.nsf" (note the double-backslashes).  

Instead of typing in the Server and Database names, you may use the replica id, which totally negates the problem of not knowing exactly where the database is physically located!  In that case, perform a Design Synopsis on the Lookup Database, only checking ON Replication Information, and then copy the Replica ID from there into your formula.  Be sure to enclose the ID in quotes, if you use this method.  Also, be sure to include a colon between the first 8 characters and the last 8 characters of the ID.

If you use this second method, and you have multiple icons of the same Replica Database on your desktop, you will receive the message, "Warning: Multiple Copies of this Database with the same Replica ID encountered in workspace" on the status bar at the bottom of your screen.  As long as your replica copies are up to date, this is not a problem.

10.        A View of That Name Cannot Be Found in the Specified Database.  Same as #8, except that the View name is incorrect.  This is often due to the switched semicolons and colons, as above.  Other common reasons for this error include:

*  forgetting to use double backslashes when referring to a Cascading View
*  referring to a Private View (@Db Functions cannot use Private Views, because they are stored in the Desktop.dsk file, not in the database file (.nsf))
*  not  including underscores (used for hotkeys) in your formula
*  enclosing view name in parentheses, in cases in which the view is not hidden

This error can also occur if the view being accessed by the @DbLookup or @DbColumn has a Read Access list on it, and the user is not a member of the Read Access list.  The Application Developer's Reference states on page 17-33 that "@DbColumn is not subject to the Read Access list on a view; so long as it has Reader access to the target database, it can retrieve data from all shared views". This is incorrect and has been reported to Lotus Quality Engineering.

11.        Entry Not Found in Index.  If the @Db Function refers to a key which is nonexistent, doesn't match any values in the Lookup View, or if the Lookup View is not sorted on the first column, you will get this error message.  Often, this is due to a blank or null key value.  This error will also occur in background agents when the key document exists but the document contains a Reader Names field which does not contain the Replica ID of the database performing the lookup.

You can capture the error produced when no data is found using the @IsError function.  For example:

temp := @DbLookup("":"NoCache";"":"";"view";"key";2);
@If(@IsError(temp);"Error message";temp)

This formula sets the value of the DbLookup to a temporary variable, temp, and then checks for an error (using @IsError).  If the function produces an error, the text "Error message" is put into the field.  If the function does not produce an error, the lookup value (contained in temp) is returned.

12.  The data types of two matching results are incompatible. If an @DbColumn is being performed on an integer column, and there is a document in the view with a null integer field -- a blank field -- you will get this error message.

13.        What if there is no error message and no value returned?  It is possible that you are asking for the data to be returned to an invalid location.  For instance, your formula may be in a button, or a macro, which says, FIELD Subbject := @DbLookup(etc ... )  Presumably, you do not have a field on your Form called, Subbject; therefore, you will not see the returned results.


Error Message (if any):

Unknown @Function; Insufficient Arguments for @Function; @If Must Have an Odd Number of Arguments; Insufficient Arguments for Database Function; The necessary external database driver cannot be located; The database was not found, please select servers to search; Server not responding; File Does Not Exist; A View of That Name Cannot Be Found in the Specified Database; Entry Not Found in Index; The data types of two matching results are incompatible;

ERROR: You are not authorized to perform that operation

Supporting Information:

Note:        Although this document was originaly written for Notes 3.x versions, these errors occur in other versions, such as 4.x and 5.x.  Another error message that occurs is "Too many arguments for database function".  This will occur if you supply an @DbColumn with too many parameters, for instance, by including a key parameter which is used by @DbLookup but not @DbColumn.

In addition, the error "Incorrect datatype for database function" will occur if you have placed quotes around the column number in a formula.