/****************************************************************************
 * @(#)25  1.3  src/examples/ems/readme, examples.src, os2dce21.dss, 960602a.1 5/12/96 06:36:29
 *
 * COMPONENT_NAME:  examples.src
 *
 * FILE NAME: readme
 *
 * DESCRIPTION: Steps for setting-up and executing the EMS sample application
 *
 * FUNCTIONS: n/a
 *
 * ORIGINS: 27
 *
 * (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.0  EMS SAMPLE APPLICATION
---------------------------

  This section contains a brief overview of some of the Event Management Service
  (EMS) concepts as well as an overview of the functionality provided in the
  sample consumer and sample supplier code.   An attempt has been made to fully
  comment the sample c-source as well.

  EMS is an event channel.  An Event channel enables communication from the
  event supplier to an event consumer.  This is first stage filtering.
  Refer to the EMS ENABLING section for additional information.  Event suppliers
  send events to EMS (if the first stage filtering is enabled) and EMS forwards
  those events to interested event consumers.  The second stage filtering is
  used to determine which event consumers are "interested".

  The sample consumer is setup to receive events from EMS.  The sample supplier
  is setup to serve as an event supplier.  The sample supplier that is provided
  will issue messages of all severity types.  It uses the sup.sams file to
  define the messages that are issued.  It sends events to EMS using calls to
  dce_svc_printf DCE application programming interface (API).

  Events get to the sample consumer because it has setup the appropriate
  registration information, event filtering information, and has successfully
  started listening for events.  The registration and event filtering information
  provided is the second level of filtering alluded to earlier.  Each event
  consumer is responsible setting up this level of information.  An event
  consumer is not a simple client.  It has to be implemented as a server to
  take care of these steps.  The steps are:

   1) call the ems_consumer_start API

      This API names this instance of the EMS consumer being setup.

      Event consumer names do not have to be unique.  The EMS ems_consumer_start
      API creates an UUID which makes the comsumer name identification unique.
      The sample code makes the name unique to make it easier to deal with.
      This sample consumer appends the process ID (converted to ASCII) to the
      consumer name string.  Its name is "sampleConsumerxxx", where "xxx" is the
      process ID.

      This API is called once during consumer initialization.  It has the
      following appearance in the sample consumer code:

      ems_consumer_start
        (consumer_name,         /* name given to this instance of the consumer */
         0,                     /* start flags - should be zeros               */
         &status);              /* address of status - returned from API       */

   2) call the ems_consumer_handler_register API

      This API registers the consumer's event handler with EMS.  This event
      handler will be passed the events that survive the event filtering
      that is defined by the consumer code.

      The event handler is yours to invent.  The sample consumer does nothing
      but display the event format attribute text.  The resulting message
      appears as "SEVERITY: message %d from %s!", where SEVERITY is the
      severity (eg, FATAL, etc), %d is a number, and %s is the hostname that
      sent the message.  The sample consumer has code that will resolve the
      replacement text from the SVC event data.

      This API is called once during consumer initialization.  It has the
      following appearance in the sample consumer code:

      ems_consumer_handler_register
        (log_event,             /* name of function that will process event    */
         &status);              /* address of status - returned from API       */

   3) call the ems_consumer_register API

      This API registers the consumer with a host's EMS daemon (EMSD).

      This API is called once during consumer initialization for each EMSD
      that is being registered.  It has the following appearance in the sample
      consumer code:

      ems_consumer_register
        (&netname,              /* address of network name just defined        */
         NULL,                  /* requires an ems_add_filter_to_group later   */
         &emsHandle1,           /* address of handle - Handle set by API       */
         &status);              /* address of status - returned from API       */

      Note that this must be done for each of the EMSD's that are to be
      monitored by the consumer.  The sample consumer has been setup to
      allow up to two hardcoded hosts names.

      In addition to registering with the EMSD, the following additional
      steps are needed for each EMSD registration:

      a) call the ems_filter_add API

         This API identifies a "named" set of one or more filter expressions.
         The filter name is used to represent the list of filter expressions.
         An example of one filter expression might appear "logically" as
         "severity = fatal".  All of the associated filter expressions must
         be "true" for the filter to be "true".

         The sample consumer defines 2 filters for each EMSD registered with:

           1) component_name = sup AND severity less than or equal to ERROR

           2) component_name = sup

         However, the first filter is used to filter events from the first host
         while the second filter is used with the second host.

         The "sup" component is an SVC component defined in the sup.sams file.

         The sample code checks to see if the filter already exists.  If it
         does, then the ems_filter_add is not performed.  The API appears as
         follows in the sample consumer:

         ems_filter_add
           (emsHandle1,         /* handle returned by registration             */
            compSup,            /* name of filter group for filter expressions */
            ems_c_svc_type,     /* filter event type                           */
            expList1,           /* list of filter expressions                  */
            &status);           /* address of status - returned from API       */

         Please refer to the sample code for more details on how the list of
         filter expressions are setup.

      b) call the ems_add_filter_to_group API

         This API is used to group a set of one or more filters defined through
         the ems_filter_add API.  All of the filters in a filter group must be
         true for the event to survive the filtering process.   Only one filter
         has to be true when multiple groups have been defined.

         The API appears as follows in the sample consumer:

         ems_add_filter_to_group
           (emsHandle1,         /* handle returned by registration             */
            fnList,             /* list of filter names                        */
            &status);           /* address of status - returned from API       */

         Please refer to the sample code for more details on how the list of
         filter names are setup.

   4) call the rpc_server_listen API

      Finally, this API places the consumer into listen mode.  It is called
      specifying the maximum number of calls it can execute concurrently.

         rpc_server_listen( 8, &status );

      Since RPCs can be executed concurrently, the consumer writer is
      responsibile for making sure that the event handler routine is thread
      safe.  If a consumer allows concurrent calls, its remote procedures are
      responsible for concurrency control. If executing a set of remote
      procedures concurrently requires concurrency control and a consumer
      lacks this control, the consumer must allow only one call at a time.
      This number is set through this API.

      Listen mode continues until the consumer is stopped.  Note that this
      sample consumer has been supplied with code to reauthenticate itself
      so that its permissions should not expire for as long as it is running.
      This, however, requires additional setup.  Please refer to the SAMPLE
      CONSUMER section for additional information on this.


2.0  DCE CONFIGURATION
----------------------


  EMS Server needs to be running in the cell.


3.0  BUILD SETUP
----------------

  Before you build the EMS example, you must define the EMS Server hostnames.
  This example allows up to two EMS Servers to be running per one consumer.
  The variables "host1" and "host2" define the EMS Server hostnames.
  Please define "host1" and "host2" to be the hostname(s) of your  EMS
  Server(s). The define "PFLAGS" also needs to be modified to indicate if
  one or two EMS Servers will be used in this example. The variables "host1",
  "host2" and "PFLAGS" are defined in files DCE_dirs, DCE_dirs.wat and
  Cflags_ems.bor. These files DCE_dirs, DCE_dirs.wat and Cflags_ems.bor
  are located in the main examples root directory.

  To build the ems example, please read the main examples readme located in
  the examples main directory. The commands "One.cmd" or "All.cmd" can
  be used to build the ems example.


4.0  EMS SAMPLE SETUP
---------------------

  4.1 EMS SETUP
  -------------

  At some point you must enable EMS to receive events.  This is referred to as
  first level filtering.  At this level, you can control which message severities
  get sent to EMS for forwarding on to interested event consumers.  This is done
  by setting up the local environment either from a command file or by entering
  the information at the command line with the following information:

     set SVC_FATAL=EMS:-;STDERR:-;
     set SVC_ERROR=EMS:-;STDERR:-;
     set SVC_WARNING=EMS:-;STDERR:-;
     set SVC_NOTICE=EMS:-;STDERR:-;
     set SVC_NOTICE_VERBOSE=EMS:-;STDERR:-;


  You can also add this information to the file,
  "opt\dcelocal\var\svc\routing", instead:


     FATAL:EMS:-;STDERR:-;
     ERROR:EMS:-;STDERR:-;
     WARNING:EMS:-;STDERR:-;
     NOTICE:EMS:-;STDERR:-;
     NOTICE_VERBOSE:EMS:-;STDERR:-;


  The reference above says to EMS that all svc message types will be sent to
  EMS and STDERR.  You can modify this if you wish.   Minimally, you must enable
  EMS for the svc type you want to monitor for.

  This level of filtering is first stage event filtering.  The second stage
  event filtering is done by the event consumer.


  4.2  SAMPLE SETUP
  -----------------

  The sample consumer expects to find a "consumer" principal and a "consumer"
  account.  The account is in the "ems-consumer" group, part of the "none"
  organization, and has a password which you will define. The consumer
  also expects to use the default keytab file.

  The sample supplier requires a "supplier" principal and a "supplier"
  account.  The account is in the "ems-supplier" group, part of the "none"
  organization, and has a password which you will define.

  These principals, accounts and keytab files need to be created. You
  may use rgy_edit or dcecp to do this setup. We have also provided
  the rgy_edit steps as follows:

 1) dcelogin to the local cell: dcelogin princial-name password

    For example, "dcelogin cell_admin -dce-"

 2) enter "rgy_edit"

 3) enter "do principal"

 4) enter "add" to create the consumer principal and follow the prompts.

 5) enter "add" to create the supplier principal and follow the prompts.

 6) enter "do account"

 7) enter "add" to create the consumer account and follow the prompts taking
    defaults where necessary.  The account ID will be "consumer".  The group
    is "ems-consumer".  The organization is "none".  Supply a password.

 8) enter "add" to create the consumer account and follow the prompts taking
    defaults where necessary.  The account ID will be "supplier".  The group
    is "ems-supplier".  The organization is "none".  Supply a password.

 9) enter "ktlist" and notice what's there.

10) enter "ktadd -p consumer -pw password-you-supplied".

11) enter "ktadd -p consumer -pw password-you-supplied -r".

12) enter "ktlist" and notice what's there.   There should be 2 new entries
    that were just added.  These entries and code in the sample consumer
    enable the consumer to reauthenticate itself before its permissions expire.

13) exit rgy_edit


5.0  RUNNING THE EMS EXAMPLES
-----------------------------

 The SAMPLE CONSUMER and SAMPLE SUPPLIER each need to be started in
 their own window session.


  5.1  SAMPLE CONSUMER
  --------------------

    a. This sample consumer also has code associated with it to make it a long
       running consumer.  It also does its own dcelogin.
       Start the sample consumer from an OS/2 command line prompt by entering:


       "consumer"


     Wait for the "Start listening for events" message before starting
     the SAMPLE SUPPLIER.


  5.2  SAMPLE SUPPLIER
  --------------------

    a. Go to another window and dcelogin as supplier


        "dcelogin supplier password"


     b. Make sure the SVC messaging is setup:


        set SVC_FATAL=EMS:-;STDERR:-;
        set SVC_ERROR=EMS:-;STDERR:-;
        set SVC_WARNING=EMS:-;STDERR:-;
        set SVC_NOTICE=EMS:-;STDERR:-;
        set SVC_NOTICE_VERBOSE=EMS:-;STDERR:-;


      c. Start the EMS SUPPLIER, by typing:


       "supplier"    or  "supplier -n  X"  when X is a number of sets



The previous example sends out a FATAL, ERROR, WARNING, NOTICE_VERBOSE, and
a NOTICE messages.   The "-n" argument allows you to indicate the number sets
that you wish to enter.   There is no suggested maximum limit.  Use "Ctrl-C"
to abort the supplier should the need arise.


------------------------------------------------------------------------------
