[xpost] Running stand-alone java programs that read and write Notes/Domino databases

[This post was originally posted to my IBM internal blog]

Most code which interfaces with Notes/Domino databases will run in the context of a running client or server e.g. a notes agent which runs on a schedule or in response to an event. However, there are times when you might want to run a stand-alone programs that will read and write Notes/Domino databases.

Bob Balaban (who wrote the definitive book on the Notes Java API) recommends that programmers should write agents in such a way that they can be run either as a stand-alone program or as a Notes agent because of the fact that it is so much easier to debug a Java program than to debug a Notes/Domino agent (he calls this the two headed beast). However, it is also often handy to distribute a program which modifies a Notes database in the form of a stand alone program e.g. I recently had to  write a program which tweaked the settings of a Sametime Community server - since many Sametime administrators don't even realize that they have a Domino server underneath I thought it would be easier to distribute the code in the form of a stand-alone program rather than as an agent and asking administrators to go through the complexity of installing and enabling a Notes agent.

One of the things that is complex about running a piece of Notes/Domino code is that you need a lot of context e.g what Notes ID etc. If you are running java agent on a machine which has Notes installed upon it then the environment variables will be already set up for you, but if your machine does not have Notes installed it can be tricky to figure out all of the paths and environmental variables that are needed. In particular I have often wasted a lot of time trying to get Java programs to run on Linux Domino servers.

What many people don't realize is that Domino Linux servers come with a very handy startup script in /opt/ibm/lotus/notes/latest/linux. that can do all of the hard work for you. To use this program you should invoke your program with the script, like:

/opt/ibm/lotus/notes/latest/linux/startup /LOCATION/MYTOOL

where LOCATION is the path to your tool and MYTOOL is the name of your tool. Then your tool will get invoked with all of the necessary environmental variables defined properly.

This startup script  is really handy, I am not sure why it is not more widely documented.