Chapter 4-4

Server Add-In Tasks





This chapter describes custom tasks (server add-ins) that you can create for the IBM Domino Server. A server add-in is an executable program that runs alongside the other tasks that make up the IBM Domino Server software and performs whatever C API operations you want.

Since server add-in tasks are loaded by Domino, the names of the executable files must follow the conventions described in the "Platform Specifics" chapter for your platform.

This chapter presents an overview of server add-ins, explains how to start and run them, and discusses some of the C API functions that are specific to server add-ins.

For complete coding details, see the sample programs ADDIN and ADD_RES in the server subdirectory.


Uses for Add-In Tasks

It is possible to write an add-in that starts, performs one operation, and exits. However, the main use for add-ins is to perform some operation periodically.

For instance, suppose you want to read a non-Domino database every hour and update a Domino database when the former changes. You can do this with an add-in task as follows:
  1. Write an add-in task that contains all the C API code needed to read the non-Domino database and update the Domino database.
  2. In the add-in, put control code that causes the task to execute once per hour.
  3. Do not load the add-in task under ServerTasks or manually via the Server Console
  4. Start server (without the server add-in)
  5. Run debugger for the server add-in as you would a NotesMain program.

The add-in runs until the server is shut down. Every hour, the add-in task scans the non-Domino database and checks for updates to it. When the non-Domino database changes, the add-in task writes the changes to the Domino database.

To use a different time interval between executions of the task, modify the timing control code to specify any schedule, such as once each night at 2:00 AM or once every 5 seconds. You can also write add-ins to execute more than one job, each with its own schedule.


Starting an Add-In Task

You can start add-in tasks two ways: automatically when the server software is started or manually, by a user at the server console. The first method is easier for production tasks, while the second method is most convenient for testing an add-in.

The instructions below ask you to stop the IBM Notes client software while you run the IBM Domino Server software if the client is on the same machine as the server. This is not strictly required. The reason we ask you to stop the Notes client software while you run the Domino server software is for ease of reading the Domino server log file. If the Notes client software and the Domino server software are running at the same time, the last entry to the log file might not be written promptly. This can make it difficult to check the results of your add-in task.


Starting an Add-In Automatically

To start an add-in automatically, follow these steps:
  1. Make sure the IBM Domino Server software is installed on the current machine and the Domino data directory contains a log file (log.nsf). You can use your existing log file or create a new one from the Log template.
  2. Copy the executable file for the add-in task to the Domino software directory.
  3. Make a backup copy of notes.ini, then open notes.ini for editing and search for the line that begins "ServerTasks=". This is a comma-delimited list of server tasks that start automatically each time the server starts.
  4. Add the name of the add-in task to this list, omitting the leading platform specifier character and the file extension. (Platform specifier characters are described in the "Platform Specifics" chapter for your platform. UNIX add-ins do not contain leading platform specifier characters.
  5. Save and close notes.ini.
  6. If the Notes workstation software is running on the same machine, exit from it.
  7. Start the IBM Domino Server software.
  8. (Optional) To confirm that the add-in task is running, type "SHOW TASKS" at the server console. This displays a list of all server tasks that are running and the status of each task.
Starting an Add-In Manually

To start an add-in task manually from the server console, follow these steps:
  1. Make sure your Domino data directory contains a log file (log.nsf). You can use your existing log file or create a new one from the Log template.
  2. If the Notes workstation software is running on the same machine, exit from it.
  3. Start the IBM Domino Server software. Wait until all server tasks have started - about 30 seconds.
  4. Press ENTER to get the server console prompt, >.
  5. Load the add-in task by typing

    load <taskname>

    If the add-in executable is not in a directory in the search path, be sure to specify the full path name of the add-in task. You may omit the leading platform specifier character. (Platform specifier characters are described in the "Platform Specifics" chapter for your platform. UNIX add-ins do not contain leading platform specifier characters.
  6. (Optional) To confirm that the add-in task is running, type "show tasks" at the server console.


Stopping an Add-In

To stop an add-in task, type "tell <taskname>quit" at the IBM Domino Server console. Checking the Operation of an Add-In
  1. Watch the server console for several minutes. You should see messages from the add-in task as it executes various parts of its code.
  2. Occasionally, type "show tasks" at the server console to display a list of all the server tasks, including the add-in, and the current status of each add-in. At different times you should see that the status of the add-in task has changed.
  3. Type "quit" to stop the server software. Wait for all the server tasks to stop. You should see a termination message from the add-in task.
  4. Start the Notes workstation software.
  5. If you have not already done so, add the server's log (log.nsf) database to your workspace. The database is found in the Domino data directory.
  6. Open the server log database.
  7. Choose the view Miscellaneous Events. The last entry in this view should show the start and stop times of the server session that you just ran.
  8. Open the last log entry. You should see all the messages that were displayed on the server console.
  9. Exit from this database.


Server Add-In Function Calls

The following C API functions are specific to custom server tasks. Refer to the Reference for details. These functions only work properly in the context of a server add-in and may not work correctly outside that context.


AddInMain

AddInMain is the standard entry point for IBM Domino Server add-in tasks. AddInMain functions as a "wrapper," in that the server initializes the Domino run-time system and certain per-task data before calling AddInMain. It also creates a default status line for the add-in task. After AddInMain returns, the IBM Domino Server performs shutdown tasks and frees the per-task data. This means the add-in code itself needs no Domino initialization or termination code.

You do not have to use AddInMain as the entry point for your IBM Domino Server add-in tasks. A C API program that uses main or NotesMain as the entry point may run as a IBM Domino Server add-in task and use the IBM Domino Server C API add-in functions as long as it creates a IBM Domino Server status line after the Domino run-time system is initalized. Use the function AddInCreateStatusLine to create the status line. Alternatively, if you need to call functions that require a default status line, such as AddInSetStatus or AddInSetStatusText, call AddInQueryDefaults, AddInCreateStatusLine, and AddInSetDefaults. You must also call AddInDeleteStatusLine before termination to deallocate the status line. A program that uses main as the entry point must call NotesInitExtended to initialize the Domino run-time system explicitly before calling any other C API function. It must also call NotesTerm to terminate the Domino run-time system.


AddInIdle

The function AddInIdle yields control of the processor to the server task and receives control back when the server decides the add-in may proceed. A TRUE value is returned from the function call when it is time to shut down the add-in task.

Use calls to AddInIdle as the add-in task main looping condition, as many of the other add-in functions depend on AddInIdle being called regularly. This also allows the add-in task to respond to the server console commands "quit" or "tell <taskname> quit". The main loop should not require more than one to five seconds to complete, to satisfy timing conditions for the IBM Domino Server; operations that require more than five seconds should use AddInShouldTerminate to check every five seconds for termination.

If the add-in task is running on a non-preemptive operating system such as Windows and its looping condition is compute-bound, it should use the function OSPreemptOccasionally. This causes the add-in to give up control of the processor so that other tasks can run.


AddInShouldTerminate

The function AddInShouldTerminate also returns TRUE when it is time to shut down the add-in task. This function is useful for checking for IBM Domino Server console commands such as "quit" or "tell <taskname> quit" while an add-in task is performing an operation that takes more than five seconds.


AddInSecondsHaveElapsed, AddInMinutesHaveElapsed

Use the functions AddInSecondsHaveElapsed and AddInMinutesHaveElapsed to schedule tasks. To schedule a task to execute every 30 minutes, one would call AddInMinutesHaveElapsed(30), and when this call returned TRUE, execute the task.


AddInSetStatus, AddInSetStatusText, AddInSetStatusLine

AddInSetStatus and AddInSetStatusText sets the status string of the add-in task default status line. The current status is represented by either a resource ID to a status string or a string. AddInSetStatus uses a resource string ID, while AddInSetStatusText uses a string. In either case, this string, along with the name of the add-in task, appears in the task list when the user types "show tasks" at the server console.

AddInSetStatusLine sets the status string in a specified status line.


AddInLogMsg, AddInLogMessage, AddInLogMessageText

Use these functions to log non-error events to the Domino Log. AddInLogMsg and AddInLogMessage require a resource string ID. AddInLogMessageText uses the actual string. AddInLogMessage and AddInLogMessageText provide more flexible formatting capabilities than AddInLogMsg.


Checking Server Status

Developers of server add-ins are responsible for checking the server status every 5 seconds to see if it is time to quit for every add-in. Using a single add-in task to do the checking and passing that info along to other processes is not sufficient as some process aren't responding to requests to dump memory or to terminate.


Resource String IDs

Resource strings are supported in Windows environments. The C API provides a set of add-in functions that use resource string ID codes. For each function that requires a resource string ID, there is a corresponding function that accepts a string instead.

For details on how to use resource string IDs, refer to the sample program ADD_RES.


Debugging a Server Add-In

Follow these steps to debug a server add-in task:
  1. Build the add-in with debugger switches turned on. For details, see the "Platform Specifics" chapter for your platform in this User Guide.
  2. Run the server. This ensures that log file messages are correctly logged.
  3. On the same machine as the server, but in a separate window or session, set up your debugger with your add-in task.
  4. Set a breakpoint at AddInMain. Source code is not viewable until AddInMain is entered.
  5. Start your add-in under the debugger.
----------------------------------------------------------------------------------------------------------