The August 2013 Blog
send me a comment

Domino Designer JVM Settings: A Little Deeper (Friday, Aug 30)
[ permalink ] [ e-mail me ] [ ]

Every user of Domino Designer in Eclipse (aka DDE, aka Domino Designer 8.5+) probably already knows how to adjust their JVM settings to give DDE more memory. Andrew Pollack did a nice writeup on it way back in 2008, and there's now an IBM technote on the subject.

But, like most things, it's good to delve a little deeper into the topic so you can really understand what's going on. Here are the IBM suggested settings and what they mean:

vmarg.Xmx=-Xmx1024mMaximum Java heap size (memory used by the JVM) is 1024MB. The lowercase "m" at the end is quite important; don't leave it off or make it capital.
vmarg.Xms=-Xms512mInitial (and minimum) Java heap size is 512MB.
vmarg.Xmca=-Xmca512kBlock size used for increasing memory allocation is 512kB (note that this value is in kilobytes, not megabytes)

The technote includes some helpful additional information:

So that's good stuff right there. Maybe all you need to know. If you want to see some screenshots to back up the instructions in the technote, the TLCC page on this subject is a handy reference. If you want a bit more detail, please keep reading below.

First, 1024m is a very good setting for the max heap, even if you have tons of RAM installed on your machine. This is because the Lotus Notes client on Windows (at least as of version 9.0) still uses a 32-bit JVM. You might be running Windows 7 64-bit with 8GB of RAM, but you've still got a 32-bit JVM. According to the IBM Java documentation, the maximum amount of memory available to a 32-bit JVM is 1.8GB. However, some people have problems setting the memory too much higher than 1024m -- it supposedly has something to do with contiguous memory allocation, but I really don't understand the details -- so 1024m is a safe value. If you have less than 2GB of RAM on your workstation (and I'm really sorry if you do), don't go higher than 50% of installed RAM.

Second, you should set the minimum heap size to be smaller than the maximum heap size (as recommended). There are plenty of web sites that will tell you (especially for Java servers) to set the minimum and maximum to the same value for efficiency. Unfortunately, for a client application like Lotus Notes this can potentially be less efficient. Not only can setting the values equal prevent effective garbage collection, it can also cause heap fragmentation. This document on IBM JVM heap sizing has a very nice explanation.

Third, these JVM settings are normally placed in the jvm.properties file in the Notes framework directory. If you install a FixPack or a new version of the Notes client, your custom JVM settings might get overwritten. Some (many? all?) FixPacks and upgrades reset the jvm.properties file. Every time you upgrade or patch your client, you should re-check the jvm.properties file and reset it if necessary.

Fourth, you can also put these settings in the rcpinstall.properties file. This file is in your data\workspace\.config directory, which has the unique advantage of being editable even if your Windows setup has the Notes program directory locked down. It also overrides any values in the jvm.properties file. Keep in mind that this file might also get overwritten when you upgrade your Notes client -- or if you delete your workspace directory.

I personally prefer to put the values in the rcpinstall.properties file, especially because this has priority over the jvm.properties file so I have much more confidence that the settings will be used. If you're curious about what the final values used by your Notes client are, you can go to the menu option Help - About IBM Notes and click the "Configuration Details" button, then scroll down to the -Xmx setting.

Or, as mentioned in the technote, you can open Domino Designer and use the "Show heap status" preference. A couple things about that preference though: (1) it only works for me if I unset and reset it after I restart Notes, and (2) you need to hover over it to see the actual max heap size, which is labelled as the "Mark" size on my Notes 9 client. The "max" size listed in the heap status bar is usually less than the max heap size.