by David DeJean

Level: Beginner Works with: Designer 4.6 Updated: 01-Jul-98

The icon for NotesPeek says it all: This is X-ray vision into Notes databases. It's a tool that gets Notes developers a lot closer to the raw data inside NSF files by presenting a graphical representation of the Notes API containment hierarchy.

It's a tool that's freely available to Notes developers, a gift from a master of Notes development. Ned Batchelder, the project leader for Domino Designer and a recent guest in the Developer Spotlight, says he developed NotesPeek because he needed it himself, and maintains it as a hobby.

It may be a hobby, but there's certainly nothing casual about NotesPeek. It is distributed via Notes.net so you can download it and run it yourself. What you'll get is a stand-alone executable program that works through the Notes API. It runs some of the Notes DLL's and reads the current NOTES.INI file. It can reveal the structure and contents of any Notes database on any server that the user has access to.

NotesPeek isn't for everybody. It is not an alternative to the Notes client, for instance -- the typical user would find trying to read their mail in NotesPeek a frustrating experience. But if you're a developer or administrator, you'll find that NotesPeek can help you answer all kinds of questions about the databases you're working on -- from relatively easy questions like "What is the actual content of the Body field in this document?" to tough questions like "What are the object IDs of all the deleted documents in this database?"

Batchelder started out as an API developer at Lotus, and NotesPeek started out as a tool for API developers. He developed the first version of NotesPeek in early 1995, he says. "I started passing it around at Lotus and adding things people needed. Its growth has always been driven by needs. That first version didn't display ACL information, for example, then we had an ACL problem and I added those features to it."

A graphical representation of the NSF file
The user interface of NotesPeek combines a graphical tree structure patterned on the directory tree of Windows 95 with the three-pane interface of Notes. The lower, left-hand Tree Pane shows hierarchical view of servers, databases, database objects of all sorts -- forms, views, documents -- clear down to data in individual fields. The right-hand Info Pane shows the properties and values of individual objects.

The upper, left-hand Context Pane shows a simplified version of the complete hierarchical path from the current object back to the beginning point of the current "peek" -- sort of a virtual bread crumb trail through the NSF forest. "That was experimental," says Batchelder rather ruefully. "I use it because I know how it works, but some people have reported it as a bug."

The following screen shows the three-pane interface of NotesPeek displaying a document. The right pane shows the attributes of the selected document. The lower left pane shows a hierarchical view of the NSF file. The upper left pane shows the location of the current object in the hierarchy -- in this case, it's one of 53 documents in a small, simple database.



The current version of NotesPeek, Release 1.4, is current with the Notes 4.6 API. The program is written in C++, and the thoroughness of its implementation is indicated by the number of icons it contains -- NotesPeek includes some 160 icons to represent the many types of objects and collections in a Notes database, including 10 different kinds of deletion stubs.

NotesPeek's graphical representation of the Notes API containment hierarchy assigns an icon to each object or collection of objects in the hierarchy, as this screen shows:



"NotesPeek should be authoritative rather than pretty," says Batchelder, but the variety of objects and icons give a NotesPeek representation of a Notes database a graphical richness all its own. There are other tools for looking into NSF files. The Notes client itself, of course, displays the data in a Notes database, but only one record at a time, and only as permitted by the form or view in use.

What Batchelder was after when he developed NotesPeek was a way to see the data in an NSF file in a very simple way. "The Notes client often adds layers of interpretation -- it hides stuff, formats stuff," he says. "The value of NotesPeek is that it lets you see things directly. The NSF file is a complex data store. It's difficult to figure out what your program is doing if you can't see the data it's reading. NotesPeek lets you see things directly. I can check the real value of the forms field and ACL values. I can dig around and see what all the info really is in there."

The Properties box and the Design Synopsis function provide some of the same access to information about the database and its contents that NotesPeek does, but neither is as flexible or as complete as NotesPeek.

The Properties box will display information about many kinds of database objects, but NotesPeek provides a structure for displaying -- and for understanding -- a Notes NSF file as a whole that the Properties box deals with only in fragments.

The Design Synopsis can go to the other extreme, displaying what can seem like an overwhelming amount of information about the design elements of a database. But the Design Synopsis lacks the ability to expand and collapse sections in a graphical interface that gives NotesPeek the ability to focus quickly on the data the user wants to see. (For more information on Design Synopsis, see the article "Design Synopsis: Creating database blueprints.")

Another advantage of the graphical interface of NotesPeek is that it can open multiple windows. "The Notes client is very modal," says Batchelder. "There's no way to see the ACL from two databases at once, for instance. With NotesPeek, you can display two ACLs side-by-side, or the same field in a document in two different versions of a database, if you're troubleshooting a replication problem."

The containment hierarchy
The structure that NotesPeek applies to the contents of NSF files is provided by the Notes API containment hierarchy, a logical representation of the content of a Notes database. (NotesPeek displays almost the entire content of a database. The things it omits are elements like Profile documents, which aren't accessible through the Notes API -- but access to Profile documents will come with Release 5, says Batchelder.) This all-inclusive access runs counter to the basic philosophy of Notes, which is based on selective display controlled through views and forms. It is helpful for API programmers who need to check the output of their code against the contents of the NSF files their applications are operating on. And it is a good way to get a sense of what makes up a Notes database.

The containment hierarchy subdivides an NSF file into five sections: Database information, Access Control List, Design Elements, Documents, and Deletion Stubs. NotesPeek displays these five sections along with other data elements, such as a list of recently "peeked" notes within the current database, or sets of selected items -- in the screen below, for example, all documents in which the BizCity field contains "New York."




What's next for NotesPeek?
Batchelder says he maintains NotesPeek as a hobby in his spare time -- and likes it that way. "I work in groups because that's the way to get big software projects done, but I like NotesPeek because it's a small project where I can do what I want. Also, it gives me contact with people around the world. I get a lot of e-mail from people in places like Turkey, asking for help with their database problems."

What he adds to his program depends mostly on new builds of Notes. Release 1.5 will have a Find feature, he says. You'll be able to enter a string and search the tree pane for all the occurrences of that string. And when might Release 1.5 appear? Batchelder isn't committing himself to a date. Right now his day job building the Domino Designer for Release 5.0 is his first priority. He'll have less time to work on NotesPeek, as well as less time for the other activity that has kept him in the public eye, his regular participation in the Domino and Notes developer forums in the Iris Cafe.

There are, he says, two things that won't appear any time soon. "People ask all the time for a NotesPoke application, because the other thing people want is to not only have access to the data, but to be able to change it. That's obviously a much larger undertaking, so I don't know if it will ever get done." And the other thing? "Data recovery. I get a lot of e-mail from people looking for help with recovering lost or deleted data. Unfortunately, it just isn't possible with a tool like NotesPeek."