Issues with code in R5


Release 5 brought with it some new design elements, and a new look and feel. These, as one would expect (!), in turn brought with them issues. This document summarises some of the common ones, and suggests how to deal with them.


Simple links / actions in navigator are susceptible to problems in Notes 5. For example, with navigators, it's common to link a hotspot to a view with a "simple action"-style link. Arguably (and we all like a good geeky argument!), his is bad practice, as in Notes 4.x, if the view name changed, the link would no longer work. I therefore decree that coders with any self-respect should always open views etc. using @formula thus:

@Command([ViewChange]) and @Command([OpenView])

instead of using simple links. Apart from the fact that this solves an issue in Notes 5 whereby databases either fail to open views or open them in funny ways / incorrect replicas, this is a way more maintainable way of coding dbs, as you use view aliases.


Be careful here. Users can switch windows very easily in R5. If they switch away from a navigator that contains a hotspot that creates a document, and then switch back, "focus" is often retained by the database they switched-to. As such, the hotspot can raise an error, "Invalid or nonexistent document." This is covered in Lotus Knowledgebase document #186154, which also provides a work-around.

Summary recommendation

As you gradually re-tool r4.x databases, consider removing navigators altogether, and opting for outlines embedded in pages, combined with framesets. These are more maintainable going forward, although they have their fair share of bugs also!


There are two types or URL in Notes: Domino URLs (the http://db.nsf?OpenDatabase kind of thing) and Notes URLs (notes://db.nsf/view?OpenView).

Notes URLs are not documented in Domino Designer help, but they do exist, and are being used more often. They follow the same kind of notation as Domino URLs. They provide a new flexible method of linking and performing actions within the Notes environment (i.e. they work in the client), and are compatible with the web in that they provide an excellent way of allowing users to perform operations in the Notes client, initiated by a Notes URL on the web.*

Consider, for example, most simple @Commands These allow users to create and edit documents, run agents, and so on. But they're not easy to adapt to say, edit a document in another database. Of course, you could use Lotusscript. Or you could use Notes URLs.

One use I have made for them is programmatically opening multiple databases from one "shell" database (e.g. have one "user interface" application which interacts with a number of separate underlying databases).

However, I digress. On to the issue with them:

As mentioned above, Notes URLs are constructed in a very similar way to Domino URLs, but certain URLs aren't implemented in Notes 5. We found, through trial and error, that URLs such as ?OpenDocument and ?OpenAgent didn't work well, or at all, in version 5.05. There could be others, so beware!

* - In older versions of R5, you may need a Windoze registry tweak to sort this out


OK, so setting aside the fact that — at least on the web — I hate framesets, they can be a useful addition to the R5 toolset, but there are a number of issues with them:


Using framesets, we can open elements from different databases / web sites, etc., and that's great. What you should be aware of however, is that Notes can get "confused" as to what database you're in, depending as to where your mouse has focus in a frameset. For example:

Db1 has a two-frame frameset. Frame 1 contains a page with an embedded outline in it from Db1. Frame 2 contains a view from Db2 in it.

If focus is in frame 2, and the user then clicks on an outline entry in frame 1 that calls an agent or something, an error will result. Notes is actually trying to find that agent in Db2, despite the fact that the user has clicked on an outline entry in Db1. This is similar to the "window switching" issue noted in the @Command([Compose]) section above.

Frame names & focus

Good developers name all the frames within a frameset so that they can refer to them programmatically (for example, using @SetTargetFrame and its Lotusscript equivalent, or, in certain outline entry types & view properties, the target frame option). You should be aware that on occasion, Notes "forgets" what frame you are in, resulting in odd actions.

For example, in developing an app with of nested framesets, one will find that Notes often loses reference to the current "parent" frameset, and code that tells it to open a view or whatever in a specific frame will fail. This failure could be nasty (the "grey frame of death") or could just be a bit crap, with Notes breaking out of the frameset and opening a new window instead.

A general rule of thumb for frame referencing is that speciifc names don't always work, but things like "_self", "_top" etc. do. Usually.

Just be aware of these problems — generally, the more complex something is, the more likely you're going to hit these issues. Some of these focus issues have been addressed in Notes 5.08 onwards. If you fancy playing with Notes client JavaScript (heh), you may be able to solve some issues.

Refreshing frames

This doesn't always work. Framesets get loaded, and that's it. In complex nested framesets, you'll find that if you need to refresh a frame once the frameset has loaded, you may need to explicitly open views / pages / whatever in a specific frame… which may fail due to the focus issue noted above. This can be a minefield, so be careful!

Database launch properties and specified framesets

Oooh, nasty. See the "Database launch properties" section below.

Outline entries & being "moused"

I love it when Lotus / Iris make up new terms like "moused". I think they mean "onMouseOver" ;-)

Certain outline entry types (you can have Actions, Links, Named Elements & URLs), when clicked-upon , do not retain focus, unless clicked again.

For example, you may code an outline entry that is designed to change colour upon being clicked. It would be nice if this colour was retained until the user clicks elsewhere — they can then see at a glance what view they're in, or whatever. For certain types of entries (e.g. URLs), this "focus" is not retained unless the user clicks again. For other types of entry it is. Go figure… This can cause real useability issues because:

- The outline gives no indicator of where the user is in a database (i.e. what view)
- The window title doesn't either, due to the fact that your app uses nested framesets (if you have a single frameset, you'll be OK!)
- In the end, the best solution we could find in a recent application was to code a Win32 API routine in the underlying database views that set the window title bar text. A pain, what a cludge!

Re-loading outlines

Be careful with how you code outlines. They are typically embedded in pages, and once loaded within a frameset, that's it. You cannot refresh their display very easily. For example, if a set of outline entries have a hide-when formula dependent on a Notes field / Notes environment variable changing, the outline will not automatically refresh unless you reload the whole frameset or page in which it sits. This is consistent with other Notes behaviour.


If you used these in a Notes 4.x database, test them carefully in Notes 5. Some things no longer work as expected. Supported Notes C API functions should still be OK as they're supported, but you may find that some Win32 API calls have changed from Win95 to Win2000. For example, calling the "GetOpenFilename" API function from within Lotusscript works fine in Windows 95, but fails in Windows 2000 (it doesn't in VB, just Lotusscript). I have a version of this function that now works in both Win95 and Win2000 (you can read it here), but I had to re-write the original Win32 API structures in Lotusscript. You may find this also happens in other API calls, so test them!

However, "supported" functions are those that are explicitly detailed in the Lotus Notes C API reference for a given release of Notes on a given platform. You can download appropriate reference guides and tookits from the horrendous IBM downloads site (nice one Big Blue).

When functions are released as supported in each toolkit, this means Iris / Lotus won't change the API in terms of the parameters / function names expected. If you're exposing your own unsupported function however (e.g. home-made "progress bars" in Lotusscript, replacing database designs prohgrammatically), then be prepared for the possibility of failure once you move to a different version of Notes or even the underlying operating system.

Keyword fields

When designing keyword fields in forms, you should note that there is a bug in Notes 5 whereby values may be pasted into such field, even if "Allow values not in list" is not selected. Further reading on this can be found in document #161753 - in the Lotus Notes Knowledgebase.

Background reading to this issue can also be found in these Knowledgebase documents: #169572 and #140789

NotesDocument MakeResponse method

Notes versions 5.04 through to 5.08 feature a minor bug in the NotesDocument method "MakeResponse" which can corrupt the database. This is only in certain circumstances though. See Knowledgebase document # 185468 for more information. It usually happens in extremely large (lots of documents) databases.

Database launch properties & framesets

In some Notes client crashes, Notes databases which launch into a specified frameset can "lose" their launch properties. See this document I posted on the LDD some time ago for a discussion of the issue, plus one user-initiated fix that repairs a database programmatically. A lot of blood sweat and tears went into this one!

THE END (for now)

That's all for now; do feel free to add more of the nasty stuff as you come across it as a comment against this article, preferably with work-arounds / solutions — we all know there are bugs in R5, but more to the point , how do we work with them?


  1. Hi, I read your entry about the bugs using SetTargetFrame. I am using 5.0.11. You mentioned that a fix should have been applied in 5.0.8. Please advise. ThanksRenee James#
  2. "Please advise" — on what exactly? Sorry, I'm not with Lotus / Iris, I can only talk about what I know… your comment doesn't tell me much.Ben Poole#
  3. Further to your comments I found that outlines worked "normally" ie retaining click focus and attributes etc for shared views but behaved poorly as you described for private views… Given that the alternative is 20 navigators vs potentially a single outline it is pretty disappointing on Lotus' part. Furthermore the loss of action buttons on embedding single category views in pages and framesets means that we are still stuck with private desktop based views.owen butler#

Comments on this post are now closed.


I’m a software architect / developer / general IT wrangler specialising in web, mobile web and middleware using things like node.js, Java, C#, PHP, HTML5 and more.

Best described as a simpleton, but kindly. You can read more here.