Configuring Message Handlers

Message Handler Overview, Message Server Overview, Message Server Configuration


When an Enterprise message server starts, it attempts to start and connect to each message handler, specified in its configuration file. The configuration file is created through the Configurations Dialog.

Note that on Windows 95, message handlers require the DCOM for 95 add-in component. This component can be downloaded from Microsoft's web site.

Configuration elements (view configuration dialog)


The name of a message handler is used for three purposes; a registry key is created with that name to store state information about the message handler such as the last message it processed, the name is used to identify the message handler in notification messages, and the name is passed to the OnInitalize method.


A note placeholder. This information is stored in the workspace but is not transmitted to the message server.

Object ID

This is the ProgID or CLSID identifying the registered COM server to be loaded. The simplest way to specify a server is through the ProgID (e.g. MyObj.MyObj.1). If the Object ID data string begins with a brace ({) it will be interpreted directly as a CLSID; otherwise it will be treated as a ProgID. This is the only value required to instantiate a message handler.

Init String

This string will be passed directly to the OnInitialize method, allowing message handlers to receive configurable parameters. If a large number of parameters are needed, pass the name of an INI file or registry key where the message handler can retrieve the necessary information.


The message server maintains a marker in the registry to indicate the last log message successfully passed to the message handler. The cookie takes the form of a GUID. Unlike connections, when a message handler is first created, it normally does not get all the messages in the message server cache. The first time a message handler is run, the cookie will be set to indicate the last log message in the cache. From that point on any new messages will be routed to the message handler and the cookie maintained automatically. This behavior can be overridden at the time a configuration is uploaded. The configuration can specify whether the message handler should start at the beginning of the cache, the end of the cache, or where it last left off (in the case of re-configuration). If a configuration is uploaded more than once to the same server, the cookie should usually be set to "current" to avoid losing or repeating messages.

Message keys

A message handler will only receive those messages for which it has the proper security identifiers.


Messages presented to a message handler can be pre-filtered in the same manner as messages downloaded to message viewers.

Retry schedule

A retry schedule can be assigned to each message handler. If the message handler fails to load or an error is encountered after a message handler is loaded, the message server will try to load it again after a configurable interval. This is useful for message handlers accessed through DCOM on a remote machine. If the network is down or the machine must be rebooted, the connection to the message handler will be re-established automatically. See the topic Configuring Retry Schedules for more information.