Lines 13 to 16 check that we have a late enough Notes client to be able to use NotesRichTextNavigator. That was new in Notes 6, build 190.

In line 19 we get a collection of the selected documents, or just the current document if one is open. Don't use this agent on an open-for-editing document. It updates the back end document and not the NotesUIDocument. Beware that if you use it on an open-for-read document, you won't see the changes until you close and re-open. It's really designed for use from a view.

The loop between 24 and 56 processes the selected documents. In line 26, we get hold of the Body field which is where the text and doclinks are. If you are using a differently named Rich Text field in your documents, then you'll need to alter this. In the next line, we create a NotesRichTextNavigator to let us to step through the doclinks in the Rich Text, and at line 29 we find the first one and start a loop around all of them. Line 46 is where we step on to the next doclink element in the Rich Text.

There is a difference between finding an element of the relevant type, and getting the actual element content. The Find... methods move the current position around the Rich Text element, and the Get... methods get hold of the element itself, without moving the pointer. So you have to use both.

At line 31, we get the doclink with GetElement. First thing to do is see if it points to another database by comparing the replicaID field in the doclink with the replicaID of the current database. If it's in a different database, we remember that (line 44) until we've completed checking all the links in the document. If the doclink is in the same database, we then check in line 33 to see if its target is this document -- in other words it points to itself. If it is, then it is likely to be an Anchor link. Anchor links are destroyed, turned into self-pointing doclinks, if you play with the comment content, so we need to leave them untouched.

If the link points to another document, then we try to get hold of the document it points to in line 35 with NotesDocument.GetDocumentByUnid using the Doclink's point-to Unid value.

We have three possible returns from that statement:

• A valid document is returned. When that happens, the doclink comment field is updated with information taken from fields in the returned - pointed-to - document, in line 40.

• An invalid document is returned. This will happen if the doclink points to a delete stub. In other words, the pointed-at document has been deleted but not purged since the doclink was created. You need to use NotesDocument.IsValid rather that NotesDocument.IsDeleted to check this. IsValid tells you if the document was deleted when you first get it, and IsDeleted is used for a check while you have it open.

• o document is returned at all. This happens if the original document has been deleted and the doclink has been purged from the database.

The code in lines 36 to 38 deals with the latter two possibilities.