Saturday, November 1, 2003

Tools for working with Notes Doclinks

PROGRAMMING POWER

By Mick Moignard

Recently I have been writing a whole bunch of documentation for a Notes project, and naturally, I've been writing it all in a Notes database. I don't need to tell you all that Notes is such a good vehicle for doing this, enabling me to keep one Notes document for each individual concept, and so letting me to work on one small piece at a time, rather than a great monolith of a word document. I can easily reference and edit other parts of the whole by going back to the view and finding another document. This all means that I have, in effect, multiple simultaneous insertion points in the documentation, and I'm still in control.

And of course the documentation has doclinks all over it -- each document has references in it to lots of others, nearly all of which are in the same database. Which has led to a some problems: documents get deleted, or maybe copied, and the doclinks don't work properly. It has also been a bit of a pain when inserting doclinks having to keep going back the view to locate the pointed-at document to make a link from. So I added a couple of quick tools to make my life a bit easier.

The Doclink Checker.

This tool is an agent in the database. It enables me to select one or more documents, and have all the doclinks in these documents checked. If they are valid -- they work -- then for all the links to the same database, the doclink comment is updated. More importantly, broken links, those where the pointed-at document can't be found, are highlighted, and then I can easily fix them. Links to other databases are not noted, but are not checked to see if they work.

Here's the code; line numbered for reference. And yes, this stuff has been tested!

01 Sub Initialize
02      'find and check doclinks in the Body field of selected documents
03      Dim session As New NotesSession
04      Dim db As NotesDatabase
05      Dim dc As NotesDocumentCollection
06      Dim doc As NotesDocument
07      Dim lookupdoc As notesdocument
08
09      Dim rti As NotesRichTextItem
10      Dim rtnav As NotesRichTextNavigator
11      Dim rtlink As NotesRichTextDocLink
12      Dim rtrange As NotesRichTextRange
13      If session.notesbuildversion < 190 Then
14              Messagebox "This agent requires a Notes 6 or above client to run"
15              Exit Sub
16      End If
17
18      Set db = session.CurrentDatabase
19      Set dc = db.UnprocessedDocuments
20      Set doc = dc.GetFirstDocument
21
22      On Error 4091 Resume Next 'error 4091 means that no document with the given UNID exists...
23
24      Do While Not (doc Is Nothing)
25              extlinks = False 'used to mark that there are external links in the doc, we don't check them
26              Set rti = doc.GetFirstItem("Body")
27              Set rtnav = rti.createNavigator
28              If Not (rtnav Is Nothing) Then
29                      If rtnav.findFirstElement(RTELEM_TYPE_DOCLINK) Then 'this document has doclinks
30                              Do
31                                      Set rtlink = rtnav.GetElement
32                                      If db.ReplicaID = rtlink.DBReplicaID Then 'link is in this database
33                                              If rtlink.DocUnID = doc.UniversalID Then 'link inside the document - an Anchor link, so leave it alone
34                                              Else
35                                                      Set lookupdoc = db.GetDocumentByUNID(rtlink.DocUnID) 'may trigger error 4091
36                                                      If lookupdoc Is Nothing Or lookupdoc.IsValid = False Then
37                                                              Messagebox "Broken link found in " & doc.chnum(0) & "." & doc.secnum(0) & " " & doc.sectiontitle(0),,"Broken Link"
38                                                              rtlink.DisplayComment = "This link is BROKEN"
39                                                      Else 'update the link with document details
40                                                              rtlink.DisplayComment = lookupdoc.chnum(0) & "." & lookupdoc.secnum(0) & " " & lookupdoc.sectiontitle(0)
41                                                      End If
42                                              End If
43                                      Else 'link is in another database
44                                              extlinks = True
45                                      End If
46                              Loop While rtnav.FindNextElement
47                      End If
48              Else
49                      Print "Cannot create RT Navigator for Body in " doc.sectiontitle(0)
50              End If
51              If extlinks = True Then
52                      Messagebox "Document " & doc.chnum(0) & "." & doc.secnum(0) & " " & doc.sectiontitle(0) & " contains unchecked Doclinks to another database",,"External Links"
53              End If
54              Call doc.save(True, False)
55              Set doc = dc.getnextdocument(doc)
56      Loop
57 End Sub1