The SharedDataDirectory environment variable, and some impacts to Notes on Windows Users
Bill Malchisky June 23 2010 05:00:00 AM
From a metaphysical standpoint, it's fascinating to me how one small change can have such a broad reaching impact. This is particularly true with networked applications in the IT space. Complicating matters further, they can be some of the more complicated troubleshooting exercises to undertake. So many variables...at what point does one just surrender and steamroll the process? It happens to everyone at some point---putting oneself at odds with the ardent problem solver within---and it has in my career. One such example is discussed here. Due to an interesting issue, and fix provided, my Notes on Windows client is quite tranquil today--as three issues were removed. The problem finds itself within the notes.ini file. One variable there, has a significant impact under certain circumstances.Three issues discovered and the fix in issue one also resolves the other two items:
(1) Upgrade to latest new release and unable to use Notes.
(2) Keeps one from finding local templates for Design Refresh/Replace operations
(3) Unable to upgrade certain local DBs designs--including mail
Through the prose below, my goal is to save you some time in supporting desktop issues, or amongst your group of peers.
First problem: Upgrade to latest new release and unable to use Notes. Start Notes and receive the error below. It then halts execution. I verified the existence of the bookmark.ntf file I then deleted the bookmark.ntf file and performed a Repair. The repair process inserted the proper bookmark.ntf file and had the same date-stamp as before. Re-launched Notes and received the same error:
Sometimes the problem dumps a secondary dialog box, with Eclipse and JVM entries as seen here:
Working with Lotus, SPR #: KKIL86NHRU entitled Customer loses bookmark.nsf due to bookmark.nsf upgrade failureis now live.
Simple work-around is to rename the bookmark.nsf and let Notes recreate it upon a Notes restart. However, you lose all your bookmarks, and if you have the admin client, you will lose all your domain bookmarks as well. So, not a permanent solution. If things are working well, you can just replace design on the renamed bookmark file, shutdown Notes, rename it back to bookmark.nsf, then launch Notes. Should work.
If that doesn't work for you, you can also try a Notes installation repair. That has worked for a few people.
But, neither option did work for this scenario. I moved the setup to a Notes on Linux machine and things worked. So what's different about the Windows machine? (There's a novel right there.) Tried several other steps and even let Lotus analyze the file for a bit. All things seemed normal for them. After more testing, they performed an internal template file upgrade of some sort, sent that template file back to me to which I applied and things worked. For a year. Then it happened again. What changed? A new release--8.5.2 beta. All of the other upgraded fix packs, and beta coded did not upgrade the bookmark.ntf file, till just before the new point release code. Making troubleshooting more taxing.
Long-story short, the cause proved to be the notes.ini file showing SharedDataDirectory=c:\notes\data\shared but upon scanning the data directory, that directory doesn't exist. See box below:
In this scenario, why does that variable exist? A common way people can see this error is that they are setup as a shared/multi-user Notes installation, and then either switch hardware and use a new Notes install that was setup differently (e.g. switching from a desktop to a laptop) and used a single install-based Notes build or the end user installs Notes on their own.
Know that since the Admin/Designer install build lacks a multi-user installation option, having a user configured with the stand-alone Notes only install, then gets upgraded later with new Notes version via a build or process utilizing the Notes only client from the Admin/Designer install will switch the user back to single mode, but not comment-out the SharedDataDirectory notes.ini token.
For this scenario, I tested the installation of this machine in a single user mode. Then upgraded the hardware and utilized the previous notes data directory. The data directory there was configured in a multi-user installation, then upgraded to single-user install to allow for the installation of both the Designer and Admin client. So, this can be a common scenario depicted and should be able to assist desktop response teams accordingly.
As we all know, when you are a power user or fixing the machine for one---particularly with third-party tools added to your Notes client [e.g. NoteMan or Ytria] and have little time---you just move the data directory and reinstall Notes. A reasonable approach, as it can save a lot of time over re-installing all of the applications again--especially ones that add new menu or toolbar icons.
Logic behind the scenes. The client discovers that your bookmark.nsf needs to be upgraded but looks for bookmark.ntf in the wrong location. When the setup process can not find the requested target in the shared directory, it doesn't bother looking in the root data directory for it--because it's being told to search elsewhere. Thus, it causes bookmark.nsf to avoid upgrading during major release updates
Solution is simple. Either comment-out or remove the SharedDataDirectory line if you are running the Admin, Designer, or converted to a single user installation from multi-user on Windows.
Note: on Linux and Mac, all installations are multi-user, so this issue goes away in those scenarios automatically.
Enhancement Request pending: I have notified Lotus and they are reviewing this for an enhancement request. Basic premise equates:
If the Notes install detects an existing notes.ini file, to see if that INI parameter exists and either reset it if the current install type is different (things we don't have to be concerned with on Linux and Mac), change the variable, or prompt the user to ask whether they want to change.
I'll post the response here as a future blog entry.
---===---
For new admins, placing a semicolon in the first column of a given row effectively comments the respective line--regardless of platform. {I know 99% will know this, but I did get asked recently at a client, thus the italicized introductory clause.}
Nota Bene: I would also like to thank Keith Kimball of Lotus Development for his insightful perspective, whilst we collaborated on a solution for the first issue.
Second Issue: Keeps one from finding local templates for Design Refresh/Replace operations. This is a more subtle issue and one that stumped me for a while till I fixed the first, then the light-bulb appeared, as they were connected.
Symptoms are few and frustrating:
(1) Only able to access templates on a Domino server
(2) Local server design [replace, refresh] box displays zero templates {first image}
(3) Clicking on the Show Advanced Templates displays all templates (both advanced and non advanced) {second image}
Cause is that that offending variable is telling Notes to look in a different place for the templates, but there aren't any in the shared data directory (which doesn't even exist). But, when clicking on advanced templates, those can be located in multiple places, so the search scope is expanded to include the root of the data directory tree. Now, you can see all of the templates. But, the problem is that even selecting the target template, the user is prohibited from clicking the Replace button.
The image below shows that template files on the server--which is expected and can serve as a work-around to upgrade reliably non-mail DBs.
If you do not see the first issue in this blog post, seeing the above symptoms for the second issue can be a chore. Further complicating matters is when a power user has Windows inside a virtual machine--the variables can be a bit more interesting, and introduces a few more troubleshooting steps. Also if clients use a LAN-based data directory, that may cause some issues similar to this, and obscure the true cause. Also, if you are using a network-based data directory at your site, do you dislike you users that much? Never seen that work well, and the user community just ends up blaming Notes for the instability--quite needlessly.
Assisting the Help Desks. The problem here will materialize when the user calls with a different problem, and that resolution requires a design replace. That procedure will fail and then introduce a tangential fix path. When seeing this error and working with the user and receiving at some point suggest the local disk NSF maintenance operations on the affected NSF: fixup, updall, compact. If they try again they will observe the maintenance tasks did not provide a full fix.
Pulling a new replica can provide a short-term fix and give the appearance that the problem has been resolved, till the next upgrade or support operation requiring a design [refresh, replace]. Most Help Desk techs will not go back and see if the user can perform a template operation once they resolve the original problem--particularly as the original problem is what irked the user and is the matter needing resolution. Since the user can now work, and the immediate issue is addressed, there is no need to delay them further; many users won't tolerate the increased time either. Know that I am not stating Help Desk should go back and review this either--for clarity.
The goal here is to resolve the error prompting the call (most cases), not the side effects occurring outside of the DB. So, in the end, the issue lies dormant for a while, until the next support issue requiring a fix. Power users, pilot users, admins, and devs may see this more frequently. It's very subtle and doesn't happen very often.
Third Issue: Keeps mail files from upgrading properly with new major release. Upgrade seems to complete fully, but upon looking at the design elements, some elements are missing. User sees most functionality working as they use the application, but intermittent errors occur that create concern and cause Help Desk calls
Successive design replace operations either with same template or switching to an unrelated design then back to the intended version fail to resolve the problem.
When I tested this, beyond having my bookmarks file unreadable by the latest 8.5.2 release code and the templates issues cited, my mail file template upgrade failed.
Know that I am also beta testing eProductivity's GTD mail template for Notes. Occasionally I would receive issues that well, other people did not see. In fact, their latest gold code candidate did not install well for me. When I fixed the SharedDataDirectory line in my notes.ini file, their program installed correctly and is working quite well.
So, the existence of a multi-user install INI reference can affect third-party Notes applications as well. Both myself and the ICA team are pleased that their program is working properly, and that such a simple resolution removed a lot of concern.
- Comments [0]
