Inserting Variable Values into LotusScript/Java Evaluate Statement Added by ~Sean Chutootexgon on January 26, 2010 | Version 1
|
|
The Evaluate statement in LotusScript provides a way to execute formula code. This is useful for carrying out operations (such as @DbLookup) for which there is no corresponding simple built-in LotusScript function.
Most of what you need to know is in the article Simplifying your LotusScript with the Evaluate statement. Please read that.
The information in the article is a little dated; some of the things one used to do with Evaluate, can now be done just as easily with newer built-in array handling functions in LotusScript. However, the basic principles have not changed. A few added notes:
- One point not directly addressed in the article is the frequent misunderstanding among beginning developers, who think they can refer to a LotusScript or Java variable by just using its name in the formula. E.g. Evaluate({@DbLookup(""; ""; "MyView"; key; 2)}, doc) where key is a LotusScript variable (Dim key As String). This does not work. If key is a field in doc instead of just a LotusScript variable, this expression does work. But if there's no item named key in the document doc, the formula treats key as an empty string -- exactly the same as if you used this formula in any other context. The article shows two ways to get a variable value into your formula expression.
- In Java, use the evaluate method of the lotus.domino.Session class. The only difference is the syntax of the Java language; especially, the rules for escaping special characters, such as quotes. Inside the string you must use \" where you mean " and \\ where you mean \ . Don't forget that \ is a special character in formulas, also. Where you want to use \ in a string in a formula, you change it to \\, then to express that string in Java, you must again double each backslash, so where you want a single \ you must actually use \\\\. To do a lookup in the view Items\by ID you might write:
Vector v = session.evaluate("@DbLookup(\"\"; \"\"; \"Items\\\\by ID\"; OrderItemID; 2)", doc);
- If you use concatenation to create a formula string, you're writing code in one language that's generating code in another language. This is always tricky to do correctly, so extra-careful debugging will help assure success. Pay special attention to quote characters which may need to be "escaped" (including in your variable data!) and also any other special characters that can't be used in string literals, such as newlines.
- If you may have special characters in your variable data and don't want to be bothered writing a special routine to convert it to a proper string literal, using the doc argument to Evaluate will let you refer to the value by its fieldname in the document instead of encoding a syntactically valid literal. The linked article shows how to do this with a newly created, unsaved document, but if you read the value from a document in the first place, you might consider passing that document to Evaluate instead.
- The LotusScript debugger's Variables pane displays string values with double-quotes "escaped" -- doubled. Formulas often contain many quotes, so If your variable contains a formula you're about to evaluate, the debugger output may be confusing. It might be easier to use the Messagebox statement to check its value.
|