Friday, December 1, 2000

Coding Domino server tasks in C


By Ian Cherrill

You have to admit it, there's a certain disdain low-level programmers have for the rest of us. One time I worked for a small software company in England as a Lotus Notes consultant, helping them design a Domino version of their product. The C programming team matched the stereotype--unwashed and uncommunicative. Their working day consisted of linked lists, pointers to structures, and state machines. They didn't think much of those of us who designed groupware systems. To them, it wasn't proper programming.

Programming in C doesn't have to be like that. If you make your living as a programmer, there's no reason to think writing a C program that works on a Domino server is too difficult. And once you get a C program written, you'll be amazed at the raw speed at which it runs. @formulas and Java were never like this. And there are certain things you can only do in C or C++. One of these is create your own server addin tasks that can be loaded from the Domino console.

In this first article in a series, I'll show you how to create the basic server task in a programmer-friendly interface--none of that command line stuff--and debug it just like you would step through a LotusScript agent. In the next article I'll take you through the source code for a real addin program called ACLHelp, and I'll also talk a little about porting it to LINUX. But let's not get ahead of ourselves.

The sample programs in the toolkit Lotus supplies are all set up to compile from a command line. If you're writing a server task, there's no guidance on how to debug it. When I first started writing server task applications, it was a case of trying to debug them from print statements, but this isn't a good method for more complex problems. Visual C++ has a good interactive debugger, and it's possible to change the code of the sample program to allow its use. There's a whole section on this below, after I've taken you through the installation and compilation of the basic sample "server addin" program.

Software requirements and installation

The tools you'll need to write a server "add-in" program are as follows:

  • Windows (95, 98, NT or 2000);
  • Lotus Domino server;
  • Microsoft Visual C++ 6.0 compiler (professional edition is enough);
  • Lotus C API Toolkit (free download from

The version of API toolkit must be lower than the version running on your server. Don't use the R5.03 toolkit if your server is running R4.67. However, the R4.62 toolkit will work to produce programs that function fine with R5.05, you just won't be able to use all the new R5 features in your program, such as transaction logging.