Event Service User's Guide

Version 3.1.2

Last updated: September 19, 2008


Table of Contents

Overview

Installation and Configuration

Request Syntax

  • REGISTER
  • ACKNOWLEDGE
  • GENERATE
  • UNREGISTER
  • LIST
  • QUERY
  • RESET
  • VERSION
  • HELP
  • Error Code Reference


    Overview

    The EVENT service is an external STAF service. The purpose of the EVENT service is to provide an interface to allow process communication based on events occuring. For instance, a process registers with the EVENT service that it is interested in builds completing. A different process tell the EVENT service when a build has completed. The EVENT service then notifies all processes that have registered interest in the build completing that the build has completed.

    Communication is done by using the STAF QUEUE service. The EVENT service notifies a process that an event has occurred by queueing a message with queue type "STAF/Service/Event" with the content of the message being a <Map> defined as follows:

    Definition for message map for a "STAF/Service/Event" type queued message
    Description: This map represents information about a generated event.
    Key Name Type Format / Value
    eventServiceName <String>
    eventID <String>
    machine <String>
    handleName <String>
    handle <String>
    timestamp <String> <YYYYMMDD-HH:MM:SS>
    type <String>
    subtype <String>
    propertyMap <Map>
    Notes:
    1. Keys "machine", "handleName", and "handle" represent the machine, handle name, and handle number of the process who generated the event.
    2. The value for "propertyMap" will contain a map representing the specified properties. If no PROPERTY options were specified on the generate request, the map will be empty. Otherwise, for each PROPERTY <Name>=[<Value>] specified, the property map will contain an entry with key set to <Name> and it's value set to <Value> (or <None> if no <Value> is specified).

    Here's an example of a queued message with type "STAF/Service/Event" generated by the STAX service for use by the STAX Monitor:

    STAF local QUEUE GET WAIT
    
    {
      Priority   : 5,
      Date-Time  : 20041019-21:52:45
      Machine    : lucas
      Handle Name: STAF/SERVICE/Event
      Handle     : 8
      User       : none://anonymous
      Type       : STAF/Service/Event
      Message    : {
        eventID         : 5686
        eventServiceName: Event
        handle          : 36
        handleName      : STAX/Job/1
        machine         : lucas.austin.ibm.com
        propertyMap     : {
          elapsed-time: 00:00:34
          laststatus  : pass
          message     : 
          name        : TestSTAF.Win2000.local.DEVICE_C++
          num-starts  : 68
          status      : update
          status-fail : 0
          status-pass : 68
        }
        subtype         : TestcaseStatus
        timestamp       : 20041019-21:52:45
        type            : STAX/lucas/1
      }
    }
    


    Installation and Configuration

    1. Install Java 1.2 or later.

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

    3. Install the Event V3.1.2 service:

      Download the EventV312.zip/tar file from Get STAF Services into a local directory (e.g. C:/STAF/services or /usr/local/staf/services) and extract it.

    4. Configure the Event service:

      Add the following statement to your staf.cfg file:

      SERVICE <Service Name> LIBRARY JSTAF EXECUTE <Service Jar File Name>
                     [PARMS "MAXATTEMPTS <Max Attempts> ACKNOWLEDGETIMEOUT <Timeout>"]

      where:

    In most cases, the way that you would use this service is that you would designate a system as the EVENT Server. That system would have STAF installed, plus the EVENT service with the SERVICE configuration statement in the configuration file that is shown above. Assuming that the machine name for the Event server is EventServer, an example of the command line interface to generate an event would be:

       STAF EventServer EVENT GENERATE TYPE MyEvent SUBTYPE SubtypeA


    Request Syntax

    The Event service provides the following requests:

    REGISTER

    REGISTER tells the EVENT service that the requesting process is interested in a particular event. If a process needs to be notified about multiple types of events, it can use multiple invocations of the REGISTER command.

    Syntax

    REGISTER TYPE <Type> [SUBTYPE <Subtype>]...
             [ACKNOWLEDGETIMEOUT <Timeout>] [MAXATTEMPTS <Number>]
             [PRIORITY <Number>] [PRIORITYDELTA <Number>]
             [BYNAME | BYHANDLE]

    TYPE specifies the type of event. This can be any string, but must match the TYPE value specified on the GENERATE request in order to be notified for this event. Note that this match is case insensitive. This option will resolve variables.

    SUBTYPE is used to further qualify this event. Any number of SUBTYPE options may be specified. One of the <value>'s specified for a SUBTYPE must match the (unique) SUBTYPE value specified on the GENERATE request in order to be notified for this event. Note that this match is case insensitive. If no SUBTYPEs were specified on the REGISTER command, the process will be notified for all SUBTYPEs of a given event TYPE. This option will resolve variables.

    ACKNOWLEDGETIMEOUT specifies the length of time in milliseconds between notification attempts. If not specified, the default timeout specified when configuring the Event service is used. This option will resolve variables.

    MAXATTEMPTS specifies the maximum number of times that the EVENT Service should notify this process that the event has occurred. If not specified, the default maximum attempts specified when configuring the Event service is used. This option will resolve variables.

    PRIORITY specifies the priority of the event notification. The default is 5. This option will resolve variables.

    PRIORITYDELTA specifies a number that will be used to decrement the priority for this process after the process is notified of the event. The default is 1. This option will resolve variables.

    BYNAME indicates that the process should be registered by handle name.

    BYHANDLE indicates that the process should be registered by handle number rather than handle name. If the BYHANDLE option is not selected, registration will be by handle name.

    Security

    This command requires trust level 3.

    Results

    Upon successful return, the result buffer will be empty.

    Examples:

    ACKNOWLEDGE

    ACKNOWLEDGE is used to tell the EVENT Service that an event has been received.

    Syntax

    ACKNOWLEDGE EVENTID <Event ID>
                [FORCE [MACHINE <Machine>] [HANDLE <Handle> | NAME <Name>]]

    EVENTID specifies the Event ID that was part of the message queued to the process when the process was notified that the event occurred.

    FORCE allows one process to acknowledge an event for a different process.

    MACHINE is used with FORCE to force acknowledgement for a process running on MACHINE <Machine>.

    HANDLE is used with FORCE to force acknowledgement for a process with HANDLE <Handle>.

    NAME is used with FORCE to force acknowledgment for a process with handle NAME <Name>.

    Security

    This command requires trust level 3 unless the FORCE option is specified which requires trust level 4.

    Results

    Upon successful return, the result buffer will contain the Event ID.

    Examples

    GENERATE

    Generate notifies the Event Service that an event has occurred.

    Syntax

    GENERATE TYPE <Type> SUBTYPE <Subtype> [PROPERTY <Name>[=<Value>]]...

    TYPE specifies the type of event. This can be any string, but must match the TYPE value specified on the REGISTER request in order to be notified for this event. Note that this match is case insensitive. This option resolves variables.

    SUBTYPE is used to further qualify this event. This can be any string, but must match the SUBTYPE value specified on the REGISTER command in order to be notified for this event. Note that this match is case insensitive. This option resolves variables.

    PROPERTY is used to pass information to further qualify the event. The format is <Name>[=<Value>]. This option does not resolve variables. This option will handle private data in the <Value> specified for a property.

    Security

    This command requires trust level 4.

    Results

    Upon successful return, the result buffer will contain the Event ID of the generating event.

    Examples

    UNREGISTER

    UNREGISTER tells the Event Service to no longer notify this process about events of specified TYPE and SUBTYPE for which this process was previously registered.

    Syntax

    UNREGISTER TYPE <Type> [SUBTYPE <Subtype>]...
               [FORCE [MACHINE <Machine>] [HANDLE <Handle> | NAME <Name>]]

    TYPE specifies the type of event. This can be any value, but must match the TYPE value specified on the REGISTER request. Note that this match is case insensitive. This option resolves variables.

    SUBTYPE is used to further qualify this event. This can be any value, but must match the SUBTYPE value specified on the REGISTER request in order to unregister the process for that SUBTYPE. Note that this match is case insensitive. This option resolves variables.

    FORCE allows one process to unregister a different process from the submitting process.

    MACHINE is used with FORCE to force unregistration of a process running on MACHINE <Machine>.

    HANDLE is used with FORCE to force unregistration of a process with HANDLE <Handle>.

    NAME is used with FORCE to force unregistration of a process with handle NAME <Name>.

    Security

    This command requires trust level 3, unless the FORCE option is specified which requires trust level 4.

    Results

    Upon successful return, the result buffer will be empty.

    Examples

    LIST

    LIST returns a list of types, subtypes, registrations, event ids, or service operational settings depending on the options selected.

    Syntax

    LIST TYPES [LONG]
    LIST SUBTYPES TYPE <Type>
    LIST REGISTRATIONS [TYPE <Type> [SUBTYPE <Subtype>]] [LONG]
    LIST EVENTIDS [LONG]
    LIST SETTINGS
    

    TYPES specifies to list the event types that are registered.

    SUBTYPES specifies to list the event subtypes that are registered for the specified event type.

    REGISTRATIONS specifies to list the processes that are registered for events as follows:

    TYPE specifies the type of event. This can be any value, but must match the TYPE value specified on the REGISTER request. Note that this match is case insensitive. This option resolves variables.

    SUBTYPE is used to further qualify this event. This can be any value, but must match the SUBTYPE value specified on the REGISTER request. Note that this match is case insensitive. This option resolves variables.

    EVENTIDS specifies to list information about all Event IDs.

    LONG specifies to list additional information about the type, registrations, or event IDs.

    SETTINGS is specified, the operational settings for the Event service are listed. The operational settings include the default values for maximum attempts, acknowledge timeout, priority, and priority delta.

    Security

    This command requires trust level 2.

    Results

    Upon successful return,

    Examples

    For the following examples, assume that there are only  2 processes registered, both for TYPE build (SpanishJavaTest and EnglishJavaTest). SpanishJavaTest is registered only for SUBTYPE Sp.  EnglishJavaTest is not registered for any  specific SUBTYPE's. Both processes are runing on machine client2.austin.ibm.com. All option values are the default REGISTRATION values.

    QUERY

    QUERY returns information about the specified event ID including its event type, subtype, and properties, who generated the event, and the pending notifications for this event. A pending notification is one where a registered process was been notified but has not yet acknowledged the event ID. Only event IDs with one or more pending notifications can be queried.

    Syntax

    QUERY EVENTID <Event ID> [LONG]

    EVENTID specifies the event ID to query.

    LONG specifies to provide more information about the pending notifications for the specified event ID instead of just the number of pending notifications.

    Security

    This command requires trust level 2.

    Results

    Upon successful return:

    Examples

    For the following examples, assume that there are 2 processes (SpanishFVTTest and SpanishSVTTest) registered for events with TYPE build and SUBTYPE Sp. Process SpanishFVTTest is running on machine client2.austin.ibm.com and process SpanishSVTTest is running on machine client3.austin.ibm.com. All option values are the default registration values.

    RESET

    RESET clears all information about the registered and/or generated events.

    Syntax

    RESET  <REG | GEN> FORCE

    REG indicates that all information about the currently registered events is to be cleared.

    GEN indicates that all information about the currently generated events is to be cleared.

    FORCE is a confirmation that you want the specified information to be cleared.

    Security

    This command requires trust level 4.

    Results

    On a successful reset, the result buffer will be empty.

    Examples

    VERSION

    VERSION displays the Event Service version.

    Syntax

    VERSION

    Security

    This request requires at least trust level 1.

    Results

    The result is the version number of the Event 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 Event service.

    Examples


    Error Code Reference

    In addition to the common STAF return codes (see Appendix A, "API Return Codes" in the STAF User's Guide for additional information), the following Event Service return codes are defined):
     
    Error Code Meaning Comment
    4001 No Acknowledgement Pending Event Service has already received an acknowledgement for this event from the acknowledgeing process
    4002 No such event ID An acknowledgement was received but no event with the submitted Event ID has been generated.
    4003 Not Registered for Type A process tried to unregister for an event Type that it was not currently registered for.
    4004 Not Registered for Subtype A process tried to unregister for an event Subype that it was not currently registered for.
    4005 No clients registered No clients were registered for the event.