The Evaluate statement in LotusScript is often overlooked, but it can be very powerful. Take, for example, the case of trying to find the unique elements in an array. On our web site we have described a script-only function to remove the duplicate elements from an array. This function has 5 Dim statements, then 10 actual statements plus the return of the array. That's 16 lines of code, but using Evaluate could actually perform the same function in 3 lines! The key to using Evaluate is having a Notes document that can be used temporarily to perform the function.

Let's assume that you have a NotesDocument variable called doc. It could be a document you're creating, or it could be a document in a view that you're processing, or some other document. It doesn't matter. What you want to do is put a temporary field on the document, use it to compute the unique entries in the array, and then remove the field. As an example, let's say you have a variable called "myArray", defined as a Variant, that holds an array of strings. You want to find out the unique strings in that array. Here is some code:

Call doc.replaceItemValue("TemporaryItem", myArray)
myArray = Evaluate("@Unique(TemporaryItem)", doc)
Call doc.removeItem("TemporaryItem")

The variable "myArray" now contains all the unique values in the array. The trick is that the formula language can often do in one line what it takes multiple lines of LotusScript to do.

But what if I don't have a document?

If you don't have a document, then it may just be a matter of adding a line or two of code to get a document, depending on what variables you already have in your script. For example, if you have a database variable, then you can create a document in the database that will never be saved. To do that, you will use the "CreateDocument" method in the NotesDatabase class to create your document. The document is created in memory only and not written to disk unless you call the "Save" method on the document (which you won't want to do in this case).

If you aren't processing through a database in your agent, then it's probably not worth the effort opening up a database, creating a document, and using the formula language. Getting a handle to a database is an expensive call in LotusScript (it's slightly slower than other calls), so saving a couple lines of code is probably not better than using the LotusScript function. But if you already have a database or a document, you should consider using the Evaluate statement when it can save you lines of code.