#
#   COMPONENT_NAME: somx
#
#   ORIGINS: 27
#
#
#    25H7912  (C)  COPYRIGHT International Business Machines Corp. 1996
#   All Rights Reserved
#   Licensed Materials - Property of IBM
#   US Government Users Restricted Rights - Use, duplication or
#   disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
#
# @(#) 1.5 src/somples.nt/somd/cpp/event/readme.txt, somples.somd, som3.0, s309651d 12/19/96 17:51:05 [12/23/96 08:42:17]  

/*
 *
 * 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.txt file
       in %SOMBASE%\samples.

This directory contains the DSOM\CPP "Event Handler" sample.  The Event Handler
interface definitions are in eventch.idl and eventcom.idl.  The Event Handler
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 polls 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
===================

BEFORE making the sample, the DSOM daemon must be running (enter "start somdd"
to start it in the background) and the Name Service must have been configured 
using som_cfg, as described in the readme.txt file in %SOMBASE%/samples.  
This is because the makefile for the sample registers the servers and classes 
in the Name Service.

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

To erase all non-source files from the current directory, type "nmake -f vac.mak clean".

To build the example program, type "nmake -f vac.mak".

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    -- builds the persistent Event Channel server

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

   consumer    -- 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
==================

To try out the sample, you must first start the DSOM daemon, "somdd" from
this directory. If the daemon is already running you must first kill it and
then restart it from this directory.

To start the daemon in the background, enter:

   start somdd
and wait for it to issue the "DSOM - Ready" message.

To run the sample, you'll need three command entry windows.  Start two new
command entry windows in addition to the one you built the sample from,
and then follow the directions below. 

In the first window, run the event server program eventsvr:

   eventsvr cellServer2

From the second window start the client program eventcli:

   eventcli

From the third window start the Consumer program:

   consumer

Now, from the window running the Consumer program, press return (Enter) to
have the consumer process begin polling. It should immediately discover
a new cell value of 10. It will then prompt again to poll. Press return
to begin polling. Because the cell value has not yet been changed you will
continuously see the message "Event Channel yet to be notified".

Go to the window running the client program and press return in response to
the prompt "Increment cell value by 1?". The process will increment the
value of the cell, post the event and repeat the prompt. Note that the
consumer process has been notified of the update to the cell and has
displayed the new value of the cell.

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

To terminate the sample programs, first quit out of eventcli and consumer by
typing 'q' or 'Q'. Then, terminate eventsvr by typing <ctrl-c> in the window
in which it is running and finally kill somdd.


Cleaning up the sample 
====================== 

BEFORE cleaning up the sample, the DSOM daemon "somdd" must be running.
This is because the makefile for the sample deregisters the servers and 
classes in the Name Service. 
 
Terminate all the instances of somdsvr.  This is because the servers will have 
the som.ir and dlls locked so they can't be erased.  To clean up the sample, 
enter "nmake clean".  This will delete all non-source files and deregister itself 
from the Name Service and Implementation Repository. 
 
The daemon "somdd" will restart the naming server to deregister the sample. 
