Last updated: May 4, 2005
SERVICE <Service Name> LIBRARY JSTAF EXECUTE <Service Jar File Name> [PARMS <Data Directory>]
<Service Name> is the name by which the Timer service will be known on this machine.
<Service Jar File Name> is the fully-qualified name of the STAFTimer.jar file.
<Data Directory> is the fully-qualified name of the directory in which the Timer service should store persistent data. The default is {STAF/Config/STAFRoot}\bin
SERVICE Timer LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/services/STAFTimer.jar SERVICE Timer LIBRARY JSTAF EXECUTE C:/STAF/services/STAFTimer.jar PARMS C:/STAF/data/timer SERVICE Timer LIBRARY JSTAF EXECUTE /usr/local/staf/services/STAFTimer.jarOr, you can dynamically add the Timer service using the SERVICE service's ADD SERVICE request.
REGISTER TYPE <Name> FREQUENCY <Frequency> [PRIORITY <Level>] [UNREGONNOPATH <1 | 0>] [UNREGONNOHANDLE <1 | 0>] [BYNAME]
Name Any string which can be used to identify the type of timer.
Frequency The frequency of the timer in milliseconds.
Level The priority level of the notification message to be sent to the registering machine. The default value is 5.
The optional parameters UNREGONNOPATH and UNREGONNOHANDLE may be used to set timer specific values for the variables UnregisterOnNoPath and UnregisterOnNoHandle. If these optional parameters are omitted, the timer will use the global values specified via the STAF VAR service.
The optional parameter BYNAME specifies to register the timer by process name rather than by the handle of the process. Any timer registered by name must be unregistered by name.
Note: If a timer already exists with the same TYPE and registering machine and process or handle it will be updated with the new frequency, and optionally the new priority, and REGISTER will return success.
The Timer service uses the STAF Queue service for interprocess communication. See "Timer Queue Messages".
Minimum security level of 3 required to register a timer.
All return codes from REGISTER are documented in "Timer Error Code Reference".
The result buffer will contain an error message if an error occurred and will be empty otherwise.
UNREGISTER TYPE <Name> [[MACHINE <Machine> HANDLE <Handle> | PROCESS <Process>] | [BYNAME]]
Name The type of the timer to terminate. This should be the same as the Name parameter used in the Register command.
Machine The machine which issued the register command if different from the current machine.
Handle The handle of the process which issued the register command if different from the current process handle.
Process The name of the process which issued the register command.
The optional parameter BYNAME specifies to unregister this timer using the process name rather than the handle of the process. This is required if the timer was registered using the process name.
Note: If the MACHINE parameter is specified then BYNAME cannot be specified. The timer will be unregistered using either the handle or the process name based upon which parameter (HANDLE or PROCESS) is specified with MACHINE.
Minimum security level of 3 required for a process to unregister a timer which it previously registered. Minimum security level of 4 required for a process to unregister a timer registered by a process on a different machine.
All return codes from REGISTER are documented in "Timer Error Code Reference".
The result buffer will contain an error message if an error occurred and will be empty otherwise.
Note: The machine to be watched must have the Timer Service running.
WATCH MACHINE <Machine> FREQUENCY <Frequency> [MARGIN <Margin>]
Machine The name of the machine to be watched.
Frequency The frequency at which the machine should send notifications, in milliseconds.
Margin The allowable margin of error, in milliseconds, in the response time of the machine being watched, before the machine is considered to be not responding.
Note: If the optional parameter MARGIN is not specified then the allowable margin of error is assumed to be 0.
Minimum security level of 3 required to register a machine to be watched.
All return codes from WATCH are documented in "Timer Error Code Reference".
The result buffer will contain an error message if an error occurred and will be empty otherwise.
UNWATCH MACHINE <Machine>
Machine The name of the machine to stop watching.
Minimum security level of 4 required for a process to unwatch a machine.
All return codes from UNWATCH are documented in "Timer Error Code Reference".
The result buffer will contain an error message if an error occurred and will be empty otherwise.
LIST TIMERS | WATCHES [FORMAT]
The optional parameter FORMAT formats the result into a more easily readable format.
Minimum security level of 2 required to list timers.
All return codes from LIST are documented in the STAF User's Guide.
The result buffer will contain data in the following format after a request to LIST TIMERS:
<NAME>;<FREQUENCY>;<PRIORITY>;<MACHINE>;<PROCESS>;<HANDLE>;<LAST_FIRED_TIMESTAMP>;<UNREGONNOPATH>;<UNREGONNOHANDLE>;
The result buffer will contain data in the following format after a request to LIST TIMERS FORMAT:
Type :<NAME> Frequency :<FREQUENCY> Priority :<PRIORITY> Machine :<MACHINE> Process :<PROCESS> Handle :<HANDLE> LastFireTime :<LAST_FIRED_TIME> UnRegOnNoPath :<UNREGONNOPATH> UnRegOnNoHandle :<UNREGONNOHANDLE>
NAME The string used to identify the type of timer.
FREQUENCY The set frequency of the timer in milliseconds.
PRIORITY The priority of the notification message.
MACHINE The machine which submitted the REGISTER command.
PROCESS The name of the process which submitted the REGISTER command for this timer.
HANDLE The numeric handle of the process which submitted the REGISTER command for this timer. (byname indicates the timer was registered by name, so the Timer service does not store handle information for this timer.)
LAST_FIRED_TIMESTAMP The timestamp of the last notification sent to the registered process for this timer.
UNREGONNOPATH The value of the timer specific variable UnregisterOnNoPath. (global indicates no timer specific value set)
UNREGONNOHANDLE The value of the timer specific variable UnregisterOnNoHandle. (global indicates no timer specific value set)
The result buffer will contain data in the following format after a request to LIST WATCHES:
<MACHINE>;<STATUS>;<LAST_TIMESTAMP>;<FREQUENCY>;<MARGIN>;
The result buffer will contain data in the following format after a request to LIST WATCHES FORMAT:
Machine To Watch :<MACHINE> Machine Status :<STATUS> Last Timestamp :<LAST_TIMESTAMP> Frequency :<FREQUENCY> Margin :<MARGIN>
MACHINE The name of the machine being watched.
STATUS An indicator of whether the machine is sending timely notifications.
LAST_TIMESTAMP The the timestamp of the last notification received from the machine.
FREQUENCY The frequency with which the machine should respond.
MARGIN The allowable margin of error before the machine is marked as not responding.
HEARTBEAT;60000;5;al1b4.austin.ibm.com;TIMER;199;19990816-11:32:36;true;false; FULL_REFRESH;600000;2;al5d4.austin.ibm.com;REFRESH;byname;19990816-11:28:44;global;true;
Type : HEARTBEAT Frequency : 60000 Priority : 5 Machine : al1b4.austin.ibm.com Process : TIMER Handle : 199 LastFireTime : 19990816-11:32:36 UnRegOnNoPath : true UnRegOnNoHandle : false
Type : FULL_REFRESH Frequency : 600000 Priority : 2 Machine : al5d4.austin.ibm.com Process : REFRESH Handle : Registered By Name LastFireTime : 19990816-11:28:44 UnRegOnNoPath : Using Global Setting UnRegOnNoHandle : true
MACHINE1;OK;19990816-11:28:44;600000;10000; SERVER;Missed;19990814-12:24:55;6000000;30000;
Machine To Watch : MACHINE1 Machine Status : OK Last Timestamp : 19990816-11:28:44 Frequency : 600000 Margin : 10000
Machine To Watch : SERVER Machine Status : Missed Last Timestamp : 19990814-12:24:55 Frequency : 6000000 Margin : 30000
REFRESH
Minimum security level of 3 required to refresh variables.
All return codes from REFRESH are documented in the STAF User's Guide.
The result buffer contains no data on return from a REFRESH command.
The timers use the STAF Queue service to send notifications to the process which submitted the REGISTER command. The format of the messages is:
STAF/SERVICE/<REGISTERED_NAME>;<NAME>;<TIMESTAMP>;
The behavior of the timer if the process is not available is controlled by the variables UnregisterOnNoHandle and UnregisterOnNoPath.
REGISTERED_NAME The registered name of the timer service.
NAME The string used to identify the type of timer.
TIMESTAMP The time at which the notification was generated.
In addition to the common STAF return codes, the following Timer
return codes are defined:
Table 1. Timer Service Return Codes
Error Code | Meaning | Comment |
---|---|---|
4001 | Invalid Frequency | The FREQUENCY specified in the REGISTER command conflicts with the minimum allowable frequency set by the variable MinFrequency. |
4002 | Invalid Priority | The PRIORITY specified in the REGISTER command is invalid. |
4003 | Invalid Type | The Type specified in the UNREGISTER command does not exist for this machine and process. |
4004 | Machine Not Watched | The machine specified in the UNWATCH command is not currently being watched. |