Treating multiple fields with the same name

Probably every developer read the description of RemoveItem method of the NotesDocument object in Domino Designer Help with a little confusion:

If more than one item has itemName$, all items with this name are deleted.

In the document properties, one can see that each instance of a field with the same name has a unique Dup Item ID, starting from 0. However, there are no documented methods to programmatically use that information. Any time the item's value is invoked, it is taken from the instance with the lowest Dup Item ID, even if you try to use the Values or Text property of the NotesItem class.

The obvious idea of simply looking through all the items in the document and collecting values for repeated names in an array just won't work, since all you get is the same value (that of the zero Dup Item ID item) repeated several times. This is a clear indication that Notes/Domino is NOT an object-oriented system. The only method that discriminates between item instances is Remove of NotesItem class. Below, see an example of how the multiple Received fields can be combined in a single field, to be displayed on the memo form. Just replace the standard QueryOpen script on the Memo form (as well as Reply, etc.) with the script below, and you'll get all the Received fields combined in a single multi-valued field (the complete message trace) that can easily be shown on the form (e.g., for debug).

If you use the code below, do not forget to open the mailbox database properties and check the box "Do not mark modified documents as unread" in the design pane.

Sub Queryopen(Source As 
Notesuidocument, Mode As Integer, 
Isnewdoc As Variant, Continue As Variant) 
        Set cMemoObject = 
New UIMemoDocument 
        Call cMemoObject.Init
(Source,Isnewdoc) 
        
        Set doc = Source.Document 
        If doc Is Nothing Then Exit Sub 
        Set db = doc.ParentDatabase 
        '--- if the current user cannot 
edit documents, do nothing 
        '--- (this is necessary since 
the right to read mail can be delegated) 
        If db.CurrentaccessLevel<4 
Then Exit Sub 
        s = "" 
        Do 
                f = False 
                its = doc.Items 
                Forall i In its 
                        '--- if the item name is 
"Received", prepend its value to the 
accumulator string 
                        If i.Name="Received" Then 
                                '--- the following 
check is necessary to properly
 treat newly created documents 
                                If i.Text<>"" Then 
                                        x =
 Evaluate
({@Implode(Received; @Char(10))}, doc) 
                                        If s="" Then s = x(0) 
Else s = x(0)+Chr(10)+s 
                                        '--- after the item with 
DupItemID=0 is removed, the values of 
DupItemID for remaining items 
                                        '--- are decremented  
by 1 and the item with DupItemID formerly 
equal to 1 becomes active 
                                        i.Remove 
                                        f = True 
                                        Goto Skip 
                                End If 
                        End If 
                End Forall                 
Skip: 
        Loop Until Not f 
        
        If s<>"" Then 
                doc.Received = s 
                ' the formula in Evaluate converts 
the field into a text list, with a little 
formatting for readability 
                doc.Received = Evaluate({
@ReplaceSubstring(@Explode(Received; 
@Char(10)); "          ":@Char(9); " ")}, doc) 
                doc.Save True, False 
        End If 
        
End Sub

Do you have comments on this tip? Let us know.