/*
 *
 * DISCLAIMER OF WARRANTIES.
 * The following [enclosed] code is sample code created by IBM
 * Corporation. This sample code is not part of any standard or IBM
 * product and is provided to you solely for the purpose of assisting
 * you in the development of your applications.  The code is provided
 * "AS IS". IBM MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT
 * NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 * FOR A PARTICULAR PURPOSE, REGARDING THE FUNCTION OR PERFORMANCE OF
 * THIS CODE.  IBM shall not be liable for any damages arising out of
 * your use of the sample code, even if they have been advised of the
 * possibility of such damages.
 *
 * DISTRIBUTION.
 * This sample code can be freely distributed, copied, altered, and
 * incorporated into other software, provided that it bears the above
 * Copyright notice and DISCLAIMER intact.
 */

NOTE:  Before attempting to build this sample, please read the readme file
       in %SOMBASE%\samples\somd\cpp.

This directory contains the DSOM/C "Event Services" sample.  The Event Service
interface definitions are in eventch.idl and eventcom.idl.  The Event Service
sample program is based on the Consumer-Supplier paradigm for events.  The
Supplier generates events and pushes them onto an Event Channel.  The Consumer
polls the Event Channel and when an appropriate event appears, it is
processed.

In this sample, the Supplier updates the value of a spreadsheet cell and puts
the updated value in the Event Channel. The Consumer, which is polling the
Event Channel for a change in the cell value, pulls the new value from the
Event Channel and displays it.

The Consumer, in this example, picks up only the last update to the cell
value.  If the Supplier makes several cell updates between two Consumer
polling cycles only the latest value of the cell is passed on to the Consumer.


BUILDING THE SAMPLE
===================

The Makefile in this directory has been set up to build the example
Event Service program.

To build the sample:

 - Microsoft users enter "nmake -f makefile.msc".

To clean up the directory and implementation repository after running
the samples:

 - Microsoft users enter "nmake -f makefile.msc clean".

You can also make specific pieces of the example programs.  The following
targets have been defined in the Makefile:

   event.lib       -- builds the DLL (dynamic link library) and the compile-time
		      "import library" for the example.

   eventsvr.exe    -- builds the persistent Event Channel server

   eventcli.exe    -- builds the client program which acts as a Supplier 
		      for events

   consumer.exe    -- builds the Consumer part of the example.

   som.ir          -- builds the Interface Repository for the examples,
		      in a local file called "som.ir".  The Interface
		      Repository is a database containing all the interface
		      definitions for the classes in the library.

   somdimpl        -- builds the Implementation Repository for the examples,
		      at a location determined by the environment variable
		      SOMDDIR.  The Implementation Repository is a
		      database containing a description of a server
		      ("cellServer2") which will load the event.dll, and
		      will hold instances of the Cell and all Event Service
		      interface instances.

RUNNING THE SAMPLE
==================

The DSOM daemon, "somdd", must be started from this
directory before executing the sample.  (See the README in
%SOMBASE%\samples\somd for information on running somdd.)
If the daemon is currently running, you must first kill it and
restart it from this directory.

Start the event server program eventsvr, by executing "eventsvr cellServer2".

Start the client program "eventcli".

Start the Consumer program "consumer".

When the cell value is incremented from the "eventcli" program,
eventcli will post the event to the consumer.  When the consumer
polls the event channel for a notification, the value will be
updated in the consumer's window.  If the consumer polls the event
channel but no notification has been sent (if the cell value has not
been incremented by eventcli), then the consumer will wait until a
notification is sent (when the value is incremented).

You can continue to go back and forth between eventcli and consumer to
experiment with the sample.

To terminate the sample, terminate both consumer and eventcli, then
terminate eventsvr and finally somdd.


To run the event sample across two different machines, the following
differences apply:

1.  The Implementation Repository must be updated with the hostname
    of the server machine.
2.  The somdd daemon must be started on the server machine prior to
    running the sample.
3.  The server program should be started on the server machine only
    (by executing "eventsvr cellServer2").
4.  After the server program has displayed the message 
    "Event Server going into the execute_request_loop",
    copy files "event.rep" and "cell.rep" from the server machine
    to the client machine (in the directory in which the client 
    programs will be run) before starting the "eventcli" and 
    "consumer" client programs.
5.  Run "eventcli" and "consumer" on the client machine only.
