Appendix C   Administering Event Notification Service in iPlanet Messaging Server


This appendix describes what you need to do to enable the iPlanet Event Notification Service Publisher (ENS Publisher) and administer iPlanet Event Notification Service (ENS) in iPlanet Messaging Server.

This chapter/appendix contains these sections:

• Loading the ENS Publisher in iPlanet Messaging Server

• Running Sample Event Notification Service Programs

• Administering Event Notification Service

For more information on ENS and ENS APIs, see the iPlanet Messaging and Collaboration Event Service Notification Manual at the iPlanet Calendar Server and Messaging Server Documentation web page.

Loading the ENS Publisher in iPlanet Messaging Server

---

The Event Notification Service (ENS) is iPlanet's underlying publish-and-subscribe service. ENS acts as a dispatcher used by iPlanet applications as a central point of collection for certain types of events that are of interest to them. Events are changes to the value of one or more properties of a resource. Any application that wants to know when these types of events occur registers with ENS, which identifies events in order and matches notifications with subscriptions.

ENS and iBiff (the ENS publisher for iPlanet Messaging Server) are bundled starting with iPlanet Messaging Server. By default ENS is enabled, however, iBIFF is not loaded. (See "To Load the ENS Publisher on iPlanet Messaging Server."

In order to subscribe to notifications in iPlanet Messaging Server, you need to load the libibiff file on the iPlanet Messaging Server host then stop and restart the messaging server.

To Load the ENS Publisher on iPlanet Messaging Server

Perform the following steps from the command line. In these steps, the location of the iPlanet Messaging Server installation directory is server_root, and the iPlanet Messaging Server user is mailsrv. Typical values for these variables are /usr/iplanet/server5, and mailsrv, respectively.

1. As mailsrv, run the configutil utility to load the libibiff file.

   cd server_root/msg-instance

   ./configutil -o "local.store.notifyplugin" -v "server_root/bin/msg/lib/libibiff"

2. As root, stop then restart the messaging server.

   cd server_root/msg-instance

   ./stop-msg

   ./start-msg

3. You are now ready to receive notifications through ENS. See "Running Sample Event Notification Service Programs" for more information.

Running Sample Event Notification Service Programs

---

iPlanet Messaging Server contains sample programs to help you learn how to receive notifications. These sample programs are located in the server_root/bin/msg/enssdk/examples directory.

To Run the Sample ENS Programs

1. Change to the server_root/bin/msg/enssdk/examples directory.

2. Using a C compiler, compile the apub and asub examples using the Makefile.sample file. Set your library search path to include the server_root/bin/msg/lib directory.

3. Once the programs have been compiled, you can run them as follows in separate windows:

   apub localhost 7997

   asub localhost 7997

   Whatever is typed in the apub window should appear on the asub window. Also, if you use the default settings, all iBiff notifications should appear in the asub window.

4. To receive notifications published by iBiff, write a program similar to asub.c

   For more information on the sample programs, and writing your own programs for ENS, see the iPlanet Event Notification Service for Messaging and Collaboration Manual.

   
   

   ---

   Note	Once you set your library search path to include the server_root/bin/msg/lib directory, you can no longer stop and start the directory server. The workaround is to remove the entry from the library search path.

   ---

   
   

Administering Event Notification Service

---

Administering ENS consists of starting and stopping the service, and changing the configuration parameters to control the behavior of the iBiff publisher for ENS.

Starting and Stopping ENS

You use the start-msg ens and stop-message ens commands to start and stop the ENS server. You must be root to run these commands.

To Start and Stop ENS

• To start ENS:

  server_root/msg-instance/start-msg ens

• To stop ENS:

  server_root/msg-instance/stop-msg ens

iPlanet Event Notification Service Configuration Parameters

Several configuration parameters control the behavior of iBiff. Use the configutil utility program to set these parameters.

Table C-1    iBiff Configuration Parameters  

Parameter	Description
local.store.notifyplugin.maxHeaderSize	Specifies the maximum size (in bytes) of the header that will be transmitted with the notification. The default is 8192 bytes.
local.store.notifyplugin.maxBodySize	Specifies the maximum size (in bytes) of the body that will be transmitted with the notification. The default is 100 bytes.
local.store.notifyplugin.eventType.enable	Specifies if the given event type will generate a notification. See the iPlanet Messaging Server for Messaging and Collaboration Manual for the various eventTypes such as ReadMsg, NewMsg, and so on. The legal values are 1 (to enable) and 0 (to disable). The default value is 1; that is, setting local.store.notifyplugin.ReadMsg.enable to 0 will disable ReadMsg notifications.
local.store.notifyplugin.ensHost	Specifies the hostname of the ENS server. The default is 127.0.0.1.
local.store.notifyplugin.ensPort	Specifies the TCP port of the ENS server. The default is 7997.
local.store.notifyplugin.ensEventKey	Specifies the event key to use for ENS notifications. The default is enp://127.0.0.1/store. The hostname portion of the event key is not used to determine the ENS host. It is simply a unique identifier used by ENS. This key is what the subscriber should subscribe to in order to be notified of events matching this key.