EventManager Service User's Guide

Version 3.1.2

Last updated: April 12, 2006


Table of Contents

Overview

Installation and Configuration

Request Syntax

  • REGISTER
  • UNREGISTER
  • LIST
  • VERSION
  • HELP
  • Service Logging

    Registration GUI

    Appendix A: Licenses and Acknowledgements


    Overview

    The EventManager service allows you to register with the Event service in order to execute STAF Commands. When an Event is generated, the Event Service (which normally sends messages to machines registered for specified events) will execute a STAF Command via the EventManager.

    Note that EventManager registration information is persistent data. This means that if you register with the EventManager service, if you shutdown STAF and restart it (even if you reboot the machine), the prior registration information will still be active. When STAF starts, it reads in the previous EventManager registration information, and again registers each STAF command with the Event service.


    Installation and Configuration

    1. Install Java 1.3 or later.

    2. Install STAF Version 3.1.0 or later by following the installation instructions in the STAF documentation.

    3. If you want to use an Event service that is already registered on this or another machine, proceed to the next step. Otherwise, install and configure the Event service to be used by the EventManager service on this machine or another machine, following the instructions in the Event Service User's Guide.

      Note: The version of the Event service must be 3.1.0 or later.

    4. Install the EventManager service by downloading the EventManagerV312.zip/tar file from Get STAF Services into a local directory (e.g. C:/STAF/services or /usr/local/staf/services) and extract it.

    5. Configure the EventManager service by adding the following statement to your STAF configuration file:
      SERVICE <Name> LIBRARY JSTAF EXECUTE <EventManager Jar File Name>
                     [OPTION <Name[=Value]>]... 
                     [PARMS <"> [EVENTSERVICEMACHINE <EventServiceMachine>] 
                                [EVENTSERVICENAME <EventServiceName>]
                            <">]
      

      where:

      Notes:

      1. If the Event service machine is NOT the same as the EventManager service machine, then you must specify the EVENTSERVICEMACHINE parameter.

      2. If "Event" is NOT the name used when registering the Event service, then you must specify the EVENTSERVICENAME parameter.

      3. If the Event service machine is the same as the EventManager service machine, then the configuration statement for the Event service must be specified in the STAF configuration file BEFORE the EventManager service configuration statement.

      Examples:

      service EventManager LIBRARY JSTAF EXECUTE c:/staf/services/STAFEventManager.jar

      service EventManager LIBRARY JSTAF EXECUTE /usr/local/staf/services/STAFEventManager.jar

      service EventManager LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/services/eventmanager/STAFEventManager.jar \
                           PARMS "EVENTSERVICEMACHINE machA.austin.ibm.com"

      service EventManager LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/services/eventmanager/STAFEventManager.jar \
                           PARMS "EVENTSERVICEMACHINE machA.austin.ibm.com EVENTSERVICENAME Event2"


    Request Syntax

    The Event Manager service provides the following requests:

    REGISTER

    REGISTER registers a STAF command to be executed when the specified event is generated.

    Syntax

    REGISTER   [DESCRIPTION <description>]
               MACHINE <machine> | PYTHONMACHINE <machine>
               SERVICE <service> | PYTHONSERVICE <service>
               REQUEST <request> | PYTHONREQUEST <request>
               TYPE <eventType> [SUBTYPE <eventSubType>]
               [PREPARE <script>]

    DESCRIPTION specifies a description of the registration. It is for informational purposes only.

    MACHINE specifies the name of the machine where the command will be executed.  This option will resolve STAF variables.  When the specified Event Type/Subtype is generated, the value of MACHINE will not be evaluated as a python string.

    PYTHONMACHINE specifies the name of the machine where the command will be executed.  This option will not resolve STAF variables.  When the specified Event Type/Subtype is generated, the value of PYTHONMACHINE will be evaluated as a python string.

    SERVICE specifies the name of the service to be executed.  This option will resolve STAF variables.  When the specified Event Type/Subtype is generated, the value of SERVICE will not be evaluated as a python string.

    PYTHONSERVICE specifies the name of the service to be executed.  This option will not resolve STAF variables.  When the specified Event Type/Subtype is generated, the value of PYTHONSERVICE will be evaluated as a python string.

    REQUEST specifies the request to be executed.  This option will resolve STAF variables.  When the specified Event Type/Subtype is generated, the value of REQUEST will not be evaluated as a python string. This option will handle private data.

    PYTHONREQUEST specifies the request to be executed.  This option will not resolve STAF variables.  When the specified Event Type/Subtype is generated, the value of PYTPHONREQUEST will be evaluated as a python string. This option will handle private data.

    TYPE specifies the Event Type for which this command will be registered. TYPE is not case sensitive. This option will resolve STAF variables.

    SUBTYPE specifies the Event SubType for which this command will be registered. SUBTYPE is not case sensitive. This option will resolve STAF variables.  If SUBTYPE is not specified, the request will be executed when any Event with the specified TYPE is generated.

    PREPARE specifies Python code which will be executed when the registered event is generated.  This code will be executed prior to the PYTHONMACHINE, PYTHONSERVICE, and PYTHONREQUEST options being evaluated as python strings. This option will not resolve STAF variables.  If the Python code sets the variable STAFEventManagerSubmit to any string other than 'true', then the request will not be submitted.

    Security

    This request requires at least trust level 5.

    Results

    Upon successful return, the result buffer contains the EventManager ID.

    Event Generation

    When an event is generated with a matching type/subtype, the following Python variables will be available when the PREPARE, PYTHONMACHINE, PYTHONSERVICE, and PYTHONREQUEST options are evaluated as python strings:

    In addition, each PROPERTY option name=value pair for the generated event will be set as Python variables.

    Also, a Python dictionary named "eventinfo" will contain all of the above name/value pairs.

    Examples

    UNREGISTER

    UNREGISTER unregisters a STAF command with the Event service.

    Syntax

    UNREGISTER ID <registrationID>

    ID specifies the EventManager ID which is to be unregistered.

    Security

    This request requires at least trust level 4.

    LIST

    LIST lists information about the commands registered with the EventManager service or the operational settings for the EventManager service.

    Syntax

    LIST <[MACHINE <machine>] [TYPE <eventType>] [LONG]> | SETTINGS

    MACHINE specifies the machine for which EventManager requests should be listed.

    TYPE specifies the Type for which EventManager requests should be listed.

    LONG indicates to list more detailed information about each EventManager request.

    SETTINGS indicates to list the operational settings for the EventManager service. The operational settings include the name of the Event service machine and the name of the Event service that the EventManager service registers with. The Event service machine/name can be specified using the EVENTSERIVCEMACHINE and EVENTSERVICENAME parameters when registering the EventManager service.

    Security

    This request requires at least trust level 2.

    Results

    Upon successful return:

    Examples

    VERSION

    VERSION displays the version level of the EventManager service or the version level of Jython packaged with the EventManager service.

    Syntax

    VERSION [JYTHON]

    VERSION specifies to display the version level of the EventManager service or the version level of Jython packaged with the EventManager service.

    JYTHON specifies to display the version level of Jython packaged with the EventManager service.

    Security

    This request requires at least trust level 1.

    Results

    The result buffer contains the version level of the EventManager service if option JYTHON is not specified. If option JYTHON is specified, the result buffer contains the version level of Jython packaged with the EventManager service.

    Examples

    HELP

    HELP displays the request options and how to use them.

    Syntax

    HELP

    Security

    This request requires at least trust level 1.

    Results

    The result buffer contains the Help messages for the request options for the EventManager service.

    Examples


    Service Logging

    The EventManager service maintains a machine log where it writes an entry when the following occurs:

    The logname for the EventManager service is the name under which the service is registered.

    Here is an example of what an EventManager service log on machine client1.austin.ibm.com (with the EventManager service's registered name begin em) could look like shown via a request from the command line in the table format:

    C:\>STAF local LOG QUERY MACHINE client1.austin.ibm.com LOGNAME em
    Response
    --------
    Date-Time Level Message
    --------- ----- -----------------------------------------------------------------
    20041210- Info  Register ID=1 originMachine=tcp://client1.austin.ibm.com@6500 mac
    16:35:32        hine=tcp://client1.austin.ibm.com@6500 pythonMachine=false servic
                    e=event pythonService=false request=version pythonRequest=false p
                    repare= type=a subtype=b
    20041210- Info  Register ID=2 originMachine=tcp://client1.austin.ibm.com@6500 mac
    16:35:50        hine=tcp://client1.austin.ibm.com@6500 pythonMachine=false servic
                    e=event pythonService=false request=blah pythonRequest=false prep
                    are=x = 'hello' type=a subtype=b
    20041210- Info  Submitted request #112 ID=2 type=a subtype=b prepare=x = 'hello' 
    16:36:38        eventservice=STAF/SERVICE/Event/ eventid=295764 generatingmachine
                    =tcp://client1.austin.ibm.com@6500 generatingprocess=STAF/Client 
                    generatinghandle=22 eventtimestamp=20040201-16:36:37 properties={
                    }machine=tcp://client1.austin.ibm.com@6500 service=event request=
                    blah
    20041210- Info  Submitted request #116 ID=1 type=a subtype=b prepare= eventservic
    16:36:38        e=STAF/SERVICE/Event/ eventid=295764 generatingmachine=tcp://clie
                    nt1.austin.ibm.com@6500 generatingprocess=STAF/Client generatingh
                    andle=22 eventtimestamp=20040201-16:36:37 properties={} machine=t
                    cp://clieint1.austin.ibm.com@6500 service=event request=version
    20041210- Error Request #112: RC=7, Result=blah, Request submitted: machine=tcp:/
    16:36:38        /client1.austin.ibm.com@6500 service=event request=blah 
    20041210- Info  Request #116: RC=0, Result=1.3.0, Request submitted: machine=tcp:
    16:36:38        //client1.austin.ibm.com@6500 service=event request=version
    20041210- Info  Submitted request #138 ID=2 type=a subtype=b prepare=x = 'hello' 
    16:37:35        eventservice=STAF/SERVICE/Event/ eventid=295765 generatingmachine
                    =tcp://client1.austin.ibm.com@6500 generatingprocess=STAF/Client 
                    generatinghandle=25 eventtimestamp=20040201-16:37:35 properties={
                    middle=michael, last=bender, first=david} machine=tcp://client1.a
                    ustin.ibm.com service=event request=blah
    20041210- Info  Submitted request #142 ID=1 type=a subtype=b prepare= eventservic
    16:37:35        e=STAF/SERVICE/Event/ eventid=295765 generatingmachine=tcp://clie
                    nt1.austin.ibm.com@6500 generatingprocess=STAF/Client generatingh
                    andle=25 eventtimestamp=20040201-16:37:35 properties={middle=mich
                    ael, last=bender, first=david} machine=tcp://client1.austin.ibm.c
                    om service=event request=version
    20041210- Error Request #138: RC=7, Result=blah, Request submitted: machine=tcp:/
    16:37:35        /client1.austin.ibm.com@6500 service=event request=blah
    20041210- Info  Request #142: RC=0, Result=1.3.0, Request submitted: machine=tcp:
    16:37:35        //client1.austin.ibm.com@6500 service=event request=version
    20041210- Info  Unregister ID=1
    16:38:01
    20041210- Info  Unregister ID=2
    16:38:03
    


    Registration GUI

    The EventManager service provides a GUI to simplify the EventManager Registration.  To use this GUI, after installing and configuring the EventManager service, from a command prompt enter the following command (note that to run this command, the STAFEventManager.jar file must be in your CLASSPATH):

        java com.ibm.staf.service.eventmanager.EventManagerRegister

    A GUI will be displayed which allows you to enter the EventManager Registration options.

    EventManager Registrationn

    The "EventManager Service Machine" default is the local machine. The "EventManager Service Name" default is "EventManager".

    Fill in the required values for "Target Machine", "Target Service", and "Target Request". Optionally, you may specify Python code in the "Prepare Script" field.

    Fill in the "Event Type" and "Event Subtype".

    This example shows the options you would specify to set up EventManager to send an email (via the STAF Email service) when an event is generated. It also shows how you can reference the PROPERTY values that were specified when the event was generated (it uses them in the Prepare script).


    Appendix A: Licenses and Acknowledgements

    Jython

    Jython is an implementation of the high-level, dynamic, object-oriented language Python written in 100% Pure Java, and seamlessly integrated with the Java platform. It thus allows you to run Python on any Java platform.

    Acknowledgement

    This product includes software developed by the Jython Developers (http://www.jython.org/).

    Licence

    Jython Software License
    =======================
    
    Copyright (c) 2000, Jython Developers
    All rights reserved.
    
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
    
     - Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.
    
     - Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in
       the documentation and/or other materials provided with the distribution.
    
     - Neither the name of the Jython Developers nor the names of
       its contributors may be used to endorse or promote products
       derived from this software without specific prior written permission.
    
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR
    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
    OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.