Beginner LotusScript for Notes Domino 6
Intermediate LotusScript for Notes Domino 6
Advanced LotusScript for Notes Domino 6
Notes Domino 6 LotusScript Package


Using the Evaluate Function to call @functions

LotusScript has a function, Evaluate, which allows @functions to be executed right in the LotusScript code. This is very useful when an @function can quickly do what 20 lines of LotusScript would require or when there is no native LotusScript equivalent, like @NameLookup.

Syntax

Evaluate Method The syntax of the Evaluate function is: Syntax variant = notesSession.Evaluate( formula$, doc ) Parameters notesSession - is the Notes Session object.  Note that the Evaluate method can be called without specifying the notesSession  object. formula$ - is a String and contains the formula.  Required. doc - is a NotesDocument which is the formula context. Cannot be null. Return value variant - The result of the evaluation. A scalar result is returned.

The first parameter is required. This is a string that will evaluate to a @function at runtime. The example below (which is a form action) uses the @namelookup function to return the OfficePhoneNumber field for Howard D Greenberg in the first Domino Directory. The string "mformula" contains the @function to call. This string is delimited by the vertical bars. This allows the use of the quotes within the string. (Click here for more information on string delimiters.) The last line contains the Evaluate function. Notice that the Evaluate method is called without specifying the notesSession object. This returns the results to the "results" field on the current document.

Sub Click(Source As Button)
   Dim ws As New NotesUIWorkspace
   Dim uidoc As NotesUIDocument
   Set uidoc = ws.CurrentDocument
   Dim doc As NotesDocument
   Set doc = uidoc.Document
   Dim mformula As String
   Dim username As String
   mformula = |@NameLookup([NoUpdate];"Howard D Greenberg/TLCC";"OfficePhoneNumber")|
   doc.results = Evaluate(mformula)
End Sub

Tip

@NameLookup This tip uses the @NameLookup in the example code. This @function searches for each specified user name across all Domino Directories and returns a list of single text values for each specified user name. It has no equivalent in native LotusScript. The syntax of the @NameLookup is: @NameLookup( [ lookupType ] ; username; itemtoreturn )

Tip

Evaluate Function Returns a Variant A key point to remember when using the Evaluate function is that it returns a variant. Variants can hold any LotusScript data type. The data type of the variant will be based on the type of data the @function will return. In the case of @NameLookup, a text list is returned. Text lists are treated as arrays in LotusScript so the Evaluate function above will return a String array.

The string containing the @function can be build on the fly. The example below uses the contents from the "username" field on the document to build the @function at the time the action is clicked.

Sub Click(Source As Button)
   Dim ws As New NotesUIWorkspace
   Dim uidoc As NotesUIDocument
   Set uidoc = ws.CurrentDocument
   Dim doc As NotesDocument
   Set doc = uidoc.Document
   Dim mformula As String
   Dim username As String
   username = doc.username(0)
   mformula = |@NameLookup([NoUpdate];"| + username + |";"OfficePhoneNumber")|
   doc.results = Evaluate(mformula)
End Sub

Notice how the string is built. A key point to note are the quotes around the user's name. When the evaluate function executes the string should contain (if the username field contained "John Smith"):

@NameLookup([NoUpdate];"John Smith";"OfficePhoneNumber")

The beginning and ending quotes have to be added in the string or else it won't work.

Finally, we can associate the @function with a document. This allows the @function to have a "context" or in other words, to know where it is executing. It does not have to be the current document and can be any document that is in a Notes database. This is done by supplying a NotesDocument object as the second parameter. The example above can be changed to associate the @function with the document as follows:

Sub Click(Source As Button)
   Dim ws As New NotesUIWorkspace
   Dim uidoc As NotesUIDocument
   Set uidoc = ws.CurrentDocument
   Dim doc As NotesDocument
   Set doc = uidoc.Document
   Dim mformula As String
   mformula = |@NameLookup([NoUpdate];username;"OfficePhoneNumber")|
   doc.results = Evaluate(mformula, doc)
End Sub


The string, mformula, contains the name of the field that has the value of the user we want to lookup. We do not want to use quotes in this case since username is a field and not a constant value like our first example. A document has to be supplied in the Evaluate function to associate the field, username, with a document. This is done by supplying the second parameter to the Evaluate function.

Tip

Evaluate Function Also Works With Java Java programmers can also use the Evaluate function. This is in the Session class and has the following syntax: public java.util.Vector evaluate(String formula)    throws NotesException public java.util.Vector evaluate(String formula, Document doc)    throws NotesException