Last updated: September 19, 2008
Installation and Configuration
Error Code Reference
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:
|
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 } }
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.
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:
Examples:
SERVICE Event LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/services/event/STAFEvent.jar
SERVICE Event LIBRARY JSTAF EXECUTE C:/STAF/services/event/STAFEvent.jar
SERVICE Event LIBRARY JSTAF EXECUTE /usr/local/staf/services/event/STAFEvent.jar
SERVICE Event LIBRARY JSTAF EXECUTE C:/STAF/services/event/STAFEvent.jar \
PARMS "MAXATTEMPTS 2 ACKNOWLEDGETIMEOUT 80000"
Or, you can dynamically add the EVENT service using the SERVICE service's ADD SERVICE request.
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
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.
This command requires trust level 3.
Upon successful return, the result buffer will be empty.
REGISTER TYPE build
REGISTER TYPE build SUBTYPE Windows
REGISTER TYPE build SUBTYPE Linux SUBTYPE AIX SUBTYPE HP-UX
REGISTER TYPE build BYHANDLE
REGISTER TYPE build MAXATTEMPTS 2 ACKNOWLEDGETIMEOUT 30000
REGISTER TYPE build SUBTYPE En SUBTYPE Sp MAXATTEMPTS 3 BYHANDLE
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>.
This command requires trust level 3 unless the FORCE option is specified which requires trust level 4.
Upon successful return, the result buffer will contain the Event ID.
ACKNOWLEDGE EVENTID 25
ACKNOWLEDGE EVENTID 25 FORCE MACHINE machineA NAME YourProcess
ACKNOWLEDGE EVENTID 25 FORCE MACHINE machineA HANDLE 7
ACKNOWLEDGE EVENTID 25 FORCE NAME YourProcess
or
ACKNOWLEDGE EVENTID 25 FORCE MACHINE local NAME YourProcess
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.
This command requires trust level 4.
Upon successful return, the result buffer will contain the Event ID of the generating event.
GENERATE TYPE build SUBTYPE Sp
GENERATE TYPE build SUBTYPE Sp PROPERTY Version=2.1.0 PROPERTY "Status=Passed BVT" PROPERTY Save
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>.
This command requires trust level 3, unless the FORCE option is specified which requires trust level 4.
Upon successful return, the result buffer will be empty.
UNREGISTER TYPE build
UNREGISTER TYPE build FORCE MACHINE machineA NAME YourProcess
UNREGISTER TYPE build SUBTYPE sp SUBTYPE fr FORCE MACHINE machineA HANDLE 7
UNREGISTER TYPE build FORCE NAME YourProcess
or
UNREGISTER TYPE build FORCE MACHINE local NAME YourProcess
LIST returns a list of types, subtypes, registrations, event ids, or service operational settings depending on the options selected.
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.
This command requires trust level 2.
Upon successful return,
Definition of map class STAF/Service/Event/Type | |||
---|---|---|---|
Description: This map class represents an event type and its subtypes. | |||
Key Name | Display Name | Type | Format / Value |
type | Type | <String> | |
subtypeList | Subtypes | <List> of <String> |
Definition of map class STAF/Service/Event/ListRegistrations | |||
---|---|---|---|
Description: This map class represents a registration for an event. | |||
Key Name | Display Name | Type | Format / Value |
type | Type | <String> | |
subtype | Subtype | <String> | <None> | |
machine | Machine | <String> | |
notifyBy | Notify By | <String> | 'Name' | 'Handle' |
notifiee | Notifiee | <String> | |
Notes:
|
Definition of map class STAF/Service/Event/ListRegistrationsLong | |||
---|---|---|---|
Description: This map class represents a registration for an event, with detailed information. | |||
Key Name | Display Name | Type | Format / Value |
type | Type | <String> | |
subtype | Subtype | <String> | <None> | |
machine | Machine | <String> | |
notifyBy | Notify By | <String> | 'Name' | 'Handle' |
notifiee | Notifiee | <String> | |
attempts | Max Attempts
(Att) | <String> | |
timeout | Timeout | <String> | |
priority | Priority
(P) | <String> | |
priorityDelta | Priority Delta
(D) | <String> | |
Notes:
|
Definition of map class STAF/Service/Event/EventID | |||
---|---|---|---|
Description: This map class represents an event ID that has at least one pending notification. | |||
Key Name | Display Name | Type | Format / Value |
eventID | Event ID | <String> | |
type | Type | <String> | |
subtype | Subtype | <String> | |
numNotifiees | # Notifiees | <String> | |
Notes: The "# Notifiees" value is set to the number of registered processes that have been notified, but have not yet acknowledged, the event ID. There will be at least 1 notifiee. |
Definition of map class STAF/Service/Event/Settings | |||
---|---|---|---|
Description: This map class represents the operational settings for the service. | |||
Key Name | Display Name | Type | Format / Value |
maxAttempts | Maximum Attempts | <String> | |
ackTimeout | Acknowledge Timeout | <String> | |
priority | Priority | <String> | |
priorityDelta | Priority Delta | <String> |
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.
LIST TYPES
Result: If the request is submitted from the command line, the result, in the default format, would look like:
build
LIST TYPES
Result: If the request is submitted from the command line, the result, in the verbose format, would look like:
[ { Type : build Subtypes: [ sp ] } ]
LIST SUBTYPES TYPE build
Result: If the request is submitted from the command line, the result, in the default format, would look like:
Sp
LIST REGISTRATIONS
Result:
Type Subtype Machine Notify By Notifiee ----- ------- ---------------------- --------- --------------- build Sp client2.austin.ibm.com Name SpanishJavaTest build <None> client2.austin.ibm.com Name EnglishJavaTest
LIST REGISTRATIONS LONG
Result: If the request is submitted from the command line, the result, in the verbose format, would look like:
[ { Type : build Subtype : Sp Machine : client2.austin.ibm.com Notify By : Name Notifiee : SpanishJavaTest Max Attempts : 1 Timeout : 60000 Priority : 5 Priority Delta: 1 } { Type : build Subtype : <None> Machine : client2.austin.ibm.com Notify By : Name Notifiee : EnglishJavaTest Max Attempts : 1 Timeout : 60000 Priority : 5 Priority Delta: 1 } ]
LIST REGISTRATIONS TYPE build
Result: If the request is submitted from the command line, the result, in the table format, would look like:
Type Subtype Machine Notify By Notifiee ----- ------- ---------------------- --------- --------------- build Sp client2.austin.ibm.com Name SpanishJavaTest build <None> client2.austin.ibm.com Name EnglishJavaTest
LIST REGISTRATIONS TYPE build SUBTYPE Sp LONG
Result: If the request is submitted from the command line, the result, in the verbose format, would look like:
[ { Type : build Subtype : Sp Machine : client2.austin.ibm.com Notify By : Name Notifiee : SpanishJavaTest Max Attempts : 1 Timeout : 60000 Priority : 5 Priority Delta: 1 } ]
List in the short format:
LIST EVENTIDS
Result: If the request is submitted from the command line, the result, in the table format, would look like:
Event ID Type Subtype # Notifiees -------- ----- ------- ----------- 310 build Sp 2 311 build En 1
List in the long format:
LIST EVENTIDS LONG
Result: If the request is submitted from the command line, the result, in the verbose format, would look like:
[ { Event ID : 310 Type : build Subtype : Sp Properties : { Status : Passed BVT Version: 2.1.0 } Generated By : { Machine : client2.austin.ibm.com Handle Name: STAF/Client Handle : 30 } Pending Notifications': [ { Machine : client2.austin.ibm.com Notify By : Name Notifiee : SpanishJavaTest Attempts Remaining: 0 Timeout : 60000 Priority : 4 Priority Delta : 1 } { Machine : client2.austin.ibm.com Notify By : Name Notifiee : EnglishJavaTest Attempts Remaining: 0 Timeout : 60000 Priority : 4 Priority Delta : 1 } ] } { Event ID : 311 Type : build Subtype : En Properties : { Status : Failed BVT Version: 2.1.0 } Generated By : { Machine : client2.austin.ibm.com Handle Name: STAF/Client Handle : 30 } Pending Notifications: [ { Machine : client2.austin.ibm.com Notify By : Name Notifiee : EnglishJavaTest Attempts Remaining: 0 Timeout : 60000 Priority : 4 Priority Delta : 1 } ] } ]
LIST SETTINGS
Result: If the request is submitted from the command line, the result could look like:
Maximum Attempts : 1 Acknowledgement Timeout: 60000 Priority : 5 Priority Delta : 1
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.
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.
This command requires trust level 2.
Upon successful return:
Definition of map class STAF/Service/Event/QueryEventID | |||
---|---|---|---|
Description: This map class represents an event ID that has at least one pending notification. | |||
Key Name | Display Name | Type | Format / Value |
eventID | Event ID | <String> | |
type | Type | <String> | |
subtype | Subtype | <String> | |
propertyMap | Properties | <Map> | Private data will be masked. |
generatedBy | Generated By | <Map:STAF/Service/Event/Generator> | |
numNotifiees | # Notifiees | <String> | |
Notes:
|
Definition of map class STAF/Service/Event/Generator | |||
---|---|---|---|
Description: This map class represents who generated the event ID. | |||
Key Name | Display Name | Type | Format / Value |
machine | Machine | <String> | |
handleName | Handle Name | <String> | |
handle | Handle | <String> | |
Notes:
|
Definition of map class STAF/Service/Event/EventIDLong | |||
---|---|---|---|
Description: This map class represents an event ID that has at least one pending notification and provided more detailed information about the event ID. | |||
Key Name | Display Name | Type | Format / Value |
eventID | Event ID | <String> | |
type | Type | <String> | |
subtype | Subtype | <String> | |
propertyMap | Properties | <Map> | Private data will be masked. |
generatedBy | Generated By | <Map:STAF/Service/Event/Generator> | |
notificationList | Pending Notifications | <List> of <Map:STAF/Service/Event/PendingNotification> | |
Notes:
|
Definition of map class STAF/Service/Event/PendingNotification | |||
---|---|---|---|
Description: This map class represents a pending notification for the event ID. | |||
Key Name | Display Name | Type | Format / Value |
machine | Machine | <String> | |
notifyBy | Notify By | <String> | 'Name' | 'Handle' |
notifiee | Notifiee | <String> | |
attempts | Attempts Remaining | <String> | |
timeout | Timeout | <String> | |
priority | Priority | <String> | |
priorityDelta | Priority Delta | <String> | |
Notes:
|
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.
QUERY EVENTID 310
Result: If the request is submitted from the command line, the result, in the verbose format, would look like:
( Event ID : 310 Type : build Subtype : Sp Properties : { Status : Passed BVT Version: 2.1.0 } Generated By: { Machine : client1.austin.ibm.com Handle Name: STAF/Client Handle : 25 } # Notifiees : 2 }
QUERY EVENTID 310 LONG
Result: If the request is submitted from the command line, the result, in the verbose format, would look like:
{ Event ID : 310 Type : build Subtype : Sp Properties : { Status : Passed BVT Version: 2.1.0 } Generated By : { Machine : client1.austin.ibm.com Handle Name: STAF/Client Handle : 25 } Pending Notifications: [ { Machine : client2.austin.ibm.com Notify By : Name Notifiee : SpanishFVTTest Attempts Remaining: 0 Timeout : 60000 Priority : 4 Priority Delta : 1 } { Machine : client3.austin.ibm.com Notify By : Name Notifiee : SpanishSVTTest Attempts Remaining: 0 Timeout : 60000 Priority : 4 Priority Delta : 1 } ] }
RESET clears all information about the registered and/or generated events.
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.
This command requires trust level 4.
On a successful reset, the result buffer will be empty.
RESET REG FORCE
RESET GEN FORCE
STAF server1.company.com EVENT VERSION
Output:
3.1.2
STAF local EVENT HELP
Output:
EVENT Service Help REGISTER TYPE <Type> [SUBTYPE <Subtype>]... [ACKNOWLEDGETIMEOUT <Timeout>] [MAXATTEMPTS <Number>] PRIORITY <Number>] [PRIORITYDELTA <Number>] [BYNAME | BYHANDLE] UNREGISTER TYPE <Type> [SUBTYPE <Subtype>]... [FORCE [MACHINE <Machine>] [HANDLE <Handle> | NAME <Name>]] ACKNOWLEDGE EVENTID <Event ID> [FORCE [MACHINE <Machine>] [HANDLE <Handle> | NAME <Name>]] GENERATE TYPE <Type> SUBTYPE <Subtype> [PROPERTY <Name>[=<Value>]]... LIST TYPES [LONG] LIST SUBTYPES TYPE <Type> LIST REGISTRATIONS [TYPE <Type> [SUBTYPE <Subtype>]] [LONG] LIST EVENTIDS [LONG] LIST SETTINGS QUERY EVENTID <Event ID> [LONG] RESET <REG | GEN> FORCE VERSION HELP
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. |