Working with Lists

Arguably one of the most important and powerful aspects of Domino development is the capability to work with lists. A list is similar to an array in other languages; in fact, in LotusScript, you handle lists using arrays. Both fields and variables can contain lists of numbers , time-dates, text, or names . A field that contains a list is called a multivalue field. To create a field that accepts multiple values, you set the Allow Multiple Values property on the Field Info tab of the Field properties box.

When you use @DbColumn() or @DbLookup() , Domino returns a list of values. You can perform math on lists, replace specific elements in lists, retrieve specific elements from lists, combine lists, and more. Better yet, you can do so much more easily when compared to array processing in LotusScript. A number of @Functions and operators are devoted to list processing. Table 12.12 lists the @Functions you are likely to use.

Table 12.12. List Processing in Domino

@Function	Returns
@Contains()	True if the value is in the list.
@Elements()	The number of list elements.
@Explode()	Creates a list from a text string or date range.
@Implode()	Creates a text string from a list.
@IsMember()	True if the value is a member of the list.
@IsNotMember()	True if the value is not a member of the list.
@Member()	The position of a member in a list.
@Replace()	Replaces elements of a list.
@ReplaceSubString()	Replaces string values with new values.
@Subset()	Extracts values from a list. A positive number extracts from left to right, and a negative number extracts from right to left
@Sum()	The sum of all the elements of a numeric list.
@Trim()	Removes empty elements from a list.
@Unique()	A list of unique values.

A number of useful list operators also exist. The most important operator is the list concatenation operator, which is the colon ( : ). This operator enables you to build lists out of constants or variables, as well as fields containing single and multiple values. The only stipulation is that lists must contain like elements. In other words, you cannot mix a time-date value with a text value ”you must convert it to a text value first. The following example creates a list of text elements:

jcTextList := "Chapter 1" : "Chapter 2" : "Chapter 3" : "Chapter 4"

Math can also be performed on lists; the operators you can use include the following: + , - , * , / , > , < , >= , <= , = , and != . Used alone, these operators act in what is called pair-wise or parallel fashion. For example, you can use the following to add two text lists together with the + operator:

jcTextList1 := "Chapter 1" : "Chapter 1" ; 
jcTextList2 := "1" : "2" ;
jcTextList1 + jcTextList2

Doing so yields the following result:

"Chapter 11"; "Chapter 12"

Adding the asterisk to the list operators causes the elements to be permuted ”all elements are combined with each other. In the previous example, change the last line to the following:

jcTextList1 *+ jcTextList2

The result is the following:

"Chapter 11"; "Chapter 12"; "Chapter 11"; "Chapter 12"

The following code fragment uses list processing to build several multivalue fields:

REM "Write the doc history"; 
jcApproval := "Approved";
jcAreaMgr := @Name([Abbreviate]; @UserName);
jdAreaMgr := @Text(@Now; "S2");
jcDocHistory := "Request " + jcApproval + " by " + jcAreaMgr +
 " on " + jdAreaMgr ;
jcSignHistory := jcApproval + " by " + jcAreaMgr + " on " +
 @Text(@Today) ;
@SetField("cAreaSign" ;@Trim(cAreaSign : jcSignHistory));

REM "Populate cDocHistory if it is blank";
jcFullName := cFirstName + " " + cInitial + " " + cLastName;
@If(cDocHistory = ""; @SetField("cDocHistory"; "Request " +
 @If(cAccess = "Delete User"; "to "; "for ") + cAccess +
 " for " + lcFullName + " created on " + jdAreaMgr + " by " +
 jcAreaMgr);
 "") ;

REM "Now add this event to the doc history";
@SetField("cDocHistory" ; cDocHistory : jcDocHistory);

REM "Voting History";
@SetField("cVote"; @Trim(cVote : jcApproval));
@SetField("cVoter"; @Trim(cVoter : @Name([Abbreviate];@UserName)));
@SetField("dVote"; @If(dVote = ""; @Now; dVote : @Now));

REM "Clear the user name from the Approver list";
jcApproverList := @Trim(@Replace(cApproverList ; cVoter; ""));
@SetField("cApproverList"; jcApproverList)

This code is from an agent that signs a document. Multiple signers are stored in a multivalue field, cApproverList. When each signer approves the document, his name is removed from the Approvers field and several fields are modified, tracking the history of this event.

For example, a string is built and added to the field cAreaSign. It is concatenated using the concatenation operator ( : ) and is added as the last element in the field cAreaSign. Similarly, document history is stored in the field cDocHistory. Voting history is stored in several fields, cVote, cVoter, and dVote.

To remove the approver from the cApproverList field, @Replace replaces the name of the approver in the field with a null string, and @Trim removes the null string from the list. The resulting list, without the approver's name, is then stored back in the cApproverList field.

As you can see, Domino has extensive support for list processing. It is well worth your time to learn how to work with lists.