Now, when we get the first child document, in the statement:

Notes uses the parameter (maindoc) as a positioning value to denote which document to get the child of. However, it doesn't appear to use the document's UNID or NoteID, but instead, some internal handle to the document's position in the view. So when the ParentView value of the document is not the "defaultView" that we use for the GetChild statement, the pointer or position value passed as the document handle doesn't mean anything, and Notes passes back the 4151 error, the document is not in the view. And of course, when the agent is started from the default view, it then works fine.

While we're talking about views in LotusScript, let me mention a couple of other tips.

This first one I got from a session at Lotusphere a year or two back. It's always said that you should give views an alias name so that should you decide that the name seen by end-users needs to be changed, any programmatic access won't be disrupted if the code always uses the alias name.

But when Notes is searching for a view to satisfy with a NotesDatabase.GetView operation, it actually searches the list of views in the database alphabetically, from top to bottom, case sensitive, using the view's main name. If there is no match, it traverses the main names again, case-insensitively. Only then does it check the alias name list, first case sensitively, then case-insensitive. So if you do the right thing and use a view alias name, but get the case wrong, Notes will search the list of view four times to find it.

The corollary of that is that for maximum performance, you should always search for a view by its main name, and be sure that you get the case right in the GetView operation. I'd suggest that this is a good reason for leaving views seen by end users to be seen only by end users, and don't give them an alias at all, so then they don't get searched by a GetView looking at aliases.

For views used programmatically, make them hidden from the end-users by using a name in parentheses, and then be sure to spell the name in the correct case.

The other tip is to do with programmatic use of sort-on-the-fly views. If these views are used programmatically on the server, all will be fine. But when used on a client, the view will appear to the code to be sorted in the order that the end-user last sorted the view, which means that operations such as GetDocumentByKey will deliver strange results, and the order in which documents are delivered to the code might also be not quite as expected.

Steve Niles is Senior Editor for ZATZ Publishing. He is also an independent filmmaker and freelance writer. For more information, visit http://www.sn-films.com.