Last updated: December 6, 2005
STAF/SERVICE/<EventServiceName>/;<EventID>;<GeneratingMachine>;<GeneratingProcess>; <GeneratingHandle>;<TimeStamp>;<Type>;<SubType>;[<Name>[=<Value>];]...
Download the EventV135.zip/tar file from Download Services for STAF V2 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/STAFEvent.jar
SERVICE Event LIBRARY JSTAF EXECUTE C:/STAF/services/STAFEvent.jar
SERVICE Event LIBRARY JSTAF EXECUTE /usr/local/staf/services/STAFEvent.jar
SERVICE Event LIBRARY JSTAF EXECUTE C:/STAF/services/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 process name.
BYHANDLE indicates that the process should be registered by Handle rather than Name. If the BYHANDLE option is not selected, registration will be by process name.
This command requires trust level 3.
Upon successful return, the result buffer will be empty.
Goal: Register the requesting process by name for events with type build:
REGISTER TYPE build
Goal: Register the requesting process by name for events with type build, but only for subtype Windows:
REGISTER TYPE build SUBTYPE Windows
Goal: Register the requesting process by name for events with type build, but only for subtypes Linux, AIX, and HP-UX:
REGISTER TYPE build SUBTYPE Linux SUBTYPE AIX SUBTYPE HP-UX
Goal: Register the requesting process by handle rather than by name for events with type build:
REGISTER TYPE build BYHANDLE
Goal: Register the requesting process by name for events with type build, making 2 notification attempts (rather the the default of 1 attempt) with a 30 second timeout between notification attempts:
REGISTER TYPE build MAXATTEMPTS 2 ACKNOWLEDGETIMEOUT 30000
Goal: Register the requesting process by handle for events with type build, but only for subtypes En and Sp. Make a maximum of 3 notification attempts if not acknowledgement is received:
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 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.
Goal: Notify Event Service that process "MyProcess" has successfully retrieved message for Event ID 25 from the "MyProcess" STAF queue:
ACKNOWLEDGE EVENTID 25
Goal: Acknowledge that process "YourProcess" on machine machineA has been notified for Event ID 25 from "SomeProcess":
ACKNOWLEDGE EVENTID 25 FORCE MACHINE machineA NAME YourProcess
Goal: Acknowledge that the process with handle 7 on machine machineA has been notified for Event ID 25.
ACKNOWLEDGE EVENTID 25 FORCE MACHINE machineA HANDLE 7
Goal: Acknowledge that process "YourProcess" on the local machine has been notified for Event ID 25.
ACKNOWLEDGE EVENTID 25 FORCE NAME YourProcess
OR
ACKNOWLEDGE EVENTID 25 FORCE MACHINE local NAME YourProcess
GENERATE TYPE <Event Type> SUBTYPE <Event 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 does not resolve variables.
This command requires trust level 4.
Upon successful return, the result buffer will contain the EventID of the generating event.
Goal: Notify the Event Service that an event of type "build" and subtype "Sp" has occurred:
GENERATE TYPE build SUBTYPE Sp
Goal: Notify the Event Service that an event of type "build" and subtype "Sp" with the following two properties: Version=2.1.0 and BuildStatus=Passed BVT:
GENERATE TYPE build SUBTYPE Sp PROPERTY Version=2.1.0 PROPERTY "BuildStatus=Passed BVT"
UNREGISTER TYPE <Event Type> [SUBTYPE <Event 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 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.
Goal: Unregister "MyProcess" for all events of TYPE build:
UNREGISTER TYPE build
Goal: Unregister process "YourProcess" on machine machineA for all events of TYPE build.
UNREGISTER TYPE build FORCE MACHINE machineA NAME YourProcess
Goal: Unregister the process with handle 7 on machine machineA for events of TYPE build, SUBTYPEs sp and fr only.
UNREGISTER TYPE build SUBTYPE sp SUBTYPE fr FORCE MACHINE machineA HANDLE 7
Goal: Unregister process "YourProcess" on the local machine for events of TYPE build..
UNREGISTER TYPE build FORCE NAME YourProcess
OR
UNREGISTER TYPE build FORCE MACHINE local NAME YourProcess
QUERY returns information about registered processes or about processes that have been notified about events.
QUERY [LONG] TYPE <Event Type> [SUBTYPE <Event Subtype>] |
[LONG] EVENTID <EventID>
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.
If SUBTYPE is not specified, all processes registered for events of the specified TYPE will be listed, regardless of SUBTYPE.
EVENTID specifies the event ID. If EVENTID is specified, all processes that have been notified but have not acknowledged the specified EVENTID will be listed.
The LONG option may be selected for a more readable format.
This command requires trust level 2.
If the TYPE <type> [SUBTYPE <subtype>] options are selected, upon successful return, the result buffer will contain the following semicolon-separated list for each process registered for the TYPE (and SUBTYPE):
MachineName;ProcessName;MAXATTEMPTS;ACKNOWLEDGETIMEOUT;PRIORITY;PRIORITYDELTA
where:
If the EVENTID <EventID> option is selected, upon successful return the result buffer will contain the following semicolon-separated list for each client that has been notified about EVENTID <EventID>:
RegisteredProcessMachineName;RegisteredProcessNameOrHandle;AttemptsRemaining;
ACKNOWLEDGETIMEOUT;CurrentPriority;PRIORITYDELTA;EventID;
GeneratingProcessMachineName;GeneratingProcessName;GeneratingProcessHandle;
TypeGenerated;SubtypeGenerated;[PropertyName[=PropertyValue]]...
LONG versions in more readable format are illustrated in the Examples below.
For the following examples, assume that there are only 2 processes registered for TYPE build (SpanishJavaTest and EnglishJavaTest) of which only 1 is registered for SUBTYPE Sp (SpanishJavaTest). Both processes are runing on machine machineB.ibm.com. All option values are the default REGISTRATION values.
Goal: Query all processes registered to be notified of event Type "build":
QUERY TYPE build
Result:
machineB.ibm.com;SpanishJavaTest;1;60000;5;1 machineB.ibm.com;EnglishJavaTest;1;60000;5;1Goal: Query only processes registered to be notified of event Type "build", Subtype "Sp":
QUERY TYPE build SUBTYPE Sp
Result:
machineB.ibm.com;SpanishJavaTest;1;60000;5;1
Goal: Query only processes registered to be notified of event Type "build", Subtype "Sp". Use the long format option.
QUERY LONG TYPE build SUBTYPE Sp
Result:
Machine: machineB.ibm.com Process: SpanishJavaTest Max Attempts: 1 Timeout: 60000 Priority: 5 Priority Delta: 1
Goal: Query processes that have been notified about EventID 10 (of TYPE build, SUBTYPE sp, generated from the STAF command line, generating handle 25), but which have not yet acknowledged. Property Version=2.1.0.
QUERY EVENTID 10
Result:
machineB.ibm.com;SpanishJavaTest;0;60000;4;1;10;machineB.ibm.com;STAF/Client;25;build;sp;Version=2.1.0
Goal: Query processes that have been notified about EventID 10 (of TYPE build, SUBTYPE sp, generated from the STAF command line, generating handle 25), but which have not yet acknowledged. Property Version=2.1.0. Use the LONG format option:
QUERY LONG EVENTID 10
Result:
Machine: machineB.ibm.com Process: SpanishJavaTest Max Attempts: 0 Timeout: 60000 Priority: 4 Priority Delta: 1 EventId: 10 Generating Machine: machineB.ibm.com Generating Process: STAF/Client Generating Handle: 25 Type: build SubType: Sp Property: Version=2.1.0
LIST returns a list of type, subtype, or event information, depending on the options selected.
LIST TYPES | TYPE [<Event Type>] | EVENTID <EventID> |
EVENTIDS | REGCLIENTS
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.
If SUBTYPE is not specified, all processes registered for events of the specified TYPE will be listed, regardless of SUBTYPE.
EVENTID specifies the event ID. If EVENTID is specified, all processes that have been notified but have not acknowledged the specified EVENTID will be listed.
EVENTIDS specifies to list the registered process and generating process information for all Event IDs.
REGCLIENTS specifies to list the all the registered processes along with the TYPEs and SUBTYPEs for which they are registered.
This command requires trust level 2.
LIST TYPES returns a result buffer containing a list of all TYPE;SUBTYPE;SUBTYPE... sets.
LIST TYPE returns a result buffer containing a list of all TYPEs.
LIST TYPE <Event Type> returns a result buffer containing a list of the SUBTYPEs of TYPE <type>.
LIST EVENTIDS returns a list of REGISTERed process and GENERATing process information for all EventID's where each entry in the list is of the form:
EventID;RegisteredProcessMachineName;RegisteredProcessNameOrHandle;AttemptsRemaining;
ACKNOWLEDGETIMEOUT;CurrentPriority;PRIORITYDELTA;EventID;
GeneratingProcessMachineName;GeneratingProcessName;GeneratingProcessHandle;
TypeGenerated;SubtypeGenerated;[PropertyName[=PropertyValue]]...
LIST EVENTID <EventID> returns a result buffer with the above information, for a single EventID only.
LIST REGCLIENTS returns a list of all registered processes along with the TYPEs and SUBTYPEs for which they are registered.
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 machineB.ibm.com. All option values are the default REGISTRATION values.
Goal: List all types that have at least one registered process, along with their subtypes:
LIST TYPES
Result:
build;sp
Goal: List all types that have at least one registered process, but not their subtypes:
LIST TYPE
Result:
build
Goal: List all subtypes of type build :
LIST TYPE build
Result:
Sp
Goal: List all registered processes:
LIST REGCLIENTS
Result:
build;Sp;machineB.ibm.com;SpanishJavaTest;1;60000;5;1
build;all subtypes;machineB.ibm.com;EnglishJavaTest;1;60000;5;1
Goal: List all processes that have been notified about EventID 10 (of TYPE build, SUBTYPE sp, generated from the STAF command line, generating handle = 25), but which have not yet acknowledged. Property Version=2.1.0 = C.
LIST EVENTID 10
Result:
machineB.ibm.com;SpanishJavaTest;0;60000;4;1;10;machineB.ibm.com;STAF/Client;25;build;sp;Version=2.1.0 machineB.ibm.com;EnglishJavaTest;0;60000;4;1;10;machineB.ibm.com;STAF/Client;25;build;sp;Version=2.1.0
Goal: List all processes that have been notified about any EventID but have not yet acknowledged (assume 2 events of TYPE build have generated, the event in the previous example and an event of TYPE build, SUBTYPE en, generated from the cstaf command line, generating handle = 30. EventID's 10 and 11, respectively.):
LIST EVENTIDS
Result:
10;machineB.ibm.com;SpanishJavaTest;0;60000;4;1;machineB.ibm.com;STAF/Client;25;build;sp;Version=2.1.0 10;machineB.ibm.com;EnglishJavaTest;0;60000;4;1;machineB.ibm.com;STAF/Client;25;build;sp;Version=2.1.0 11;machineB.ibm.com;EnglishJavaTest;0;60000;4;1;machineB.ibm.com;STAF/Client;30;build;en;Version=2.1.0
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.
EN 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.
Goal: Clear all information about the currently registered events.
RESET REG FORCE
Goal: Clear all information about the currently generated events.
RESET GEN FORCE
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. |