VIEW MEMBER FEEDACK TO THIS TIP
Multi-value fields are one of the core features of Lotus Notes and Domino. Creating these fields on a form is simple within Domino Designer. Once a field is defined as multi-value, it is easy for users to add a value to the field -- just type a comma or semicolon, and then enter the new value. But performing the same operation within Lotuscript is tricky, especially if the field is not text type. This tip shows you how to do just that.
If the field in question is text, adding to it from Lotuscript is straightforward, using a method that is designed specifically for this task. Consider this code:
The LotusScript code snippet assumes that you have already initialized the NotesDocument object named ThisDoc. The code then checks to see if the designated field exists. If it does, it calls the method NotesItem.AppendToTextList, to add a new name to the end of the field. If the field does not exist, the code creates it with an initial value, using NotesDocument.ReplaceItemValue.
The LotusScript code for text fields is so simple that it is not worth writing a technical tip about. But suppose you want to do the same thing for a time-date or number field? This should be easy, with methods called NotesItem.AppendToTimeField and AppendToNumberField. Unfortunately, these methods do not exist.
Here is the same code snippet, but modified to handle time-date fields:
Adding to a time-date multi-value field must account for several situations. First, the field may not exist, just as with text fields. Next, the field may exist, but contain something other than a time-date value. This is actually quite common, since Lotus Notes has an annoying habit of initializing time-date and number fields to the null string before you enter a real value.
If you try to append a new value to a time-date field that contains a null string, you will have a lot of problems, since the existing value is not ...
To continue reading for free, register below or login
To read more you must become a member of SearchDomino.com
a valid time-date. And we need code for the normal case, an existing field with legal values in it.
The LotusScript code sample above assumes that the time variable NewTime is initialized with a valid time, perhaps with the statement NewTime=Now.
The central part of the code is the Forall loop, which reads each value in the existing field and adds it to an array. Because we don't know the number of values in the field, we must Redim the array for each new value, being careful to use the Preserve option (so values already in the array are not lost). After we have built an array with the current field contents, we then add the new value to the end of the array. (With another Redim, of course.)
Finally, we use NotesDocument.ReplaceItemValue to rewrite the whole field with the updated contents. This method will set the datatype of the field correctly, based on the type of array being used.
The end of the snippet shows two Else clauses that handle the other cases: field does not exist, and field exists with wrong datatype. In both cases, the field is replaced with the single new time-date value.
Handling multi-value number fields is identical to time-date fields, except that the two variables named New* are changed to Long datatype. The field that holds the existing values (Old*List) can remain a Variant, since a Variant can hold a list of numbers retrieved from a field.
About the author: Chuck Connell is president of CHC-3 Consulting, which helps organizations with all aspects of Lotus Notes and Domino.
MEMBER FEEDBACK TO THIS TIP
I have done this with a bit more efficiency. Do you remember the doc.getitemvalue method? It is a more efficient way of retrieving the array than using a forall loop.
—Ronald V.
******************************************
I have a very slight variation to this tip. I use Ubound to check for the upperbound value. Now, you only have to use Redim once. I would also likely use ReplaceItemValue instead of the abbreviated syntax.
—Bryan P.
******************************************
You can replace the following code:
With this code:
—Yuthana S.
******************************************
Unless I'm mistaken, I believe Chuck forgot to set the value of "newtime" before adding it to the array. As a result, this will probably fail.
—Andrew P.
Do you have comments on this tip? Let us know.
Related information from SearchDomino.com:
Expert Advice: Using a multi-value field in DECS
Looking for a value in a multi-valued text field
LotusScript Learning Guide
FAQ: LotusScript
LotusScript Reference Center
Please let others know how useful this tip is via the rating scale below. Do you have a useful Lotus Notes, Domino, Workplace or WebSphere tip or code snippet to share? Submit it to our tip contest and you could win a prize.
