Timer Service

Version 1.1.1

Last updated: May 4, 2005


Table of Contents

Timer Service
  • Description
  • Software Requirements
  • Registration
  • Variables
  • REGISTER
  • UNREGISTER
  • WATCH
  • UNWATCH
  • LIST
  • REFRESH
  • Timer Queue Messages
  • Timer Error Code Reference

  • Timer Service

    Description

    The Timer service is an external STAF service that provides the following functions: The purpose of the Timer service is to allow a process on one machine to periodically receive a notification message from the same or another machine. This can be used to have one machine periodically execute a process on another machine, as a "heartbeat" to monitor the activity of a machine, or any other purpose where a periodic timer may be useful.

    Software Requirements

    This service requires:

    Registration

    The Timer service is written in Java and since it is an external service, it must be registered with the SERVICE configuration statement. The syntax is:
    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

    Examples

    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.jar
    
    Or, you can dynamically add the Timer service using the SERVICE service's ADD SERVICE request.

    Variables

    The following variables are defined in the STAF configuration file and the Timer service will query their values:
    STAF/Service/Timer/MinFrequency: The minimum allowable frequency for a timer
    STAF/Service/Timer/UnregisterOnNoHandle: Unregister the timer if handle does not exist
    STAF/Service/Timer/UnregisterOnNoPath: Unregister the timer if no path to machine
    STAF/Service/Timer/TotalFireAttempts: The number of times to attempt to send a notification before unregistering the timer

    STAF/Service/Timer/MinFrequency

    Specifies the minimum allowable frequency, in milliseconds, that can be used with the REGISTER command. An error will be returned from REGISTER if the FREQUENCY parameter is less than the MinFrequency variable. A value of 0 will result in no minimum frequency.
    Example: var STAF/Service/Timer/MinFrequency=5000
    Default: 1000

    STAF/Service/Timer/UnregisterOnNoHandle

    Specifies a binary value that sets the behavior of the timer when the process which registered the timer does not exist. If 1, the timer will be automatically unregistered. If 0, the timer will discard the message and attempt to send a new message at the end of the next period.

    Note: If the specified value is not defined (not 1 or 0), the value will be set to 1.

    Example: var STAF/Service/Timer/UnregisterOnNoHandle=0
    Default: 1

    STAF/Service/Timer/UnregisterOnNoPath

    Specifies a binary value that sets the behavior of the timer when no path exists to the machine which registered the timer. This will occur if the machine cannot be contacted (machine down, network error) or if STAF is not running on the machine. If 1, the timer will be automatically unregistered (see STAF/Service/Timer/TotalFireAttempts). If 0, the timer will discard the message and attempt to send a new message at the end of the next period.

    Note: If the specified value is not defined (not 1 or 0), the value will be set to 1.

    Example: var STAF/Service/Timer/UnregisterOnNoPath=0
    Default: 1

    STAF/Service/Timer/TotalFireAttempts

    Specifies an integer for the number of times to try to attempt to send a timer message, before unregistering a timer, if the specified machine is not reachable (STAF not running, network error, etc). This variable only has an effect if the timer is configured to unregister on no path to machine, either configured globally or specific to the timer. A log message will be generated with the timer name and attempt number each time the attempt to queue a message fails.

    Note: Valid values are any positive integer, including 0. If an invalid value is specified, the default value will be used.

    Example: var STAF/Service/Timer/TotalFireAttempts=5
    Default: 3

    REGISTER

    Registers the requesting process to receive a timer notification at a given frequency

    Syntax

    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".

    Security

    Minimum security level of 3 required to register a timer.

    Return Codes

    All return codes from REGISTER are documented in "Timer Error Code Reference".

    Results

    The result buffer will contain an error message if an error occurred and will be empty otherwise.

    Examples

    Goal: Register a timer with a name of heartbeat and a frequency of 60 seconds.
    Syntax: REGISTER TYPE heartbeat FREQUENCY 60000
    Goal: Register a timer with a name of heartbeat, a frequency of 60 seconds, and a priority of 2.
    Syntax: REGISTER TYPE heartbeat FREQUENCY 60000 PRIORITY 2
    Goal: Register a timer with a name of timer07, a frequency of 30 seconds, and will override the global variable UnregisterOnNoPath to unregister when the machine which registered the timer cannot be reached.
    Syntax: REGISTER TYPE timer07 FREQUENCY 30000 UNREGONNOPATH 1
    Goal: Register a timer with a name of timer01, a frequency of 60 seconds. Register this timer by the process name.
    Syntax: REGISTER TYPE timer01 FREQUENCY 60000 BYNAME

    UNREGISTER

    Unregisters a process from receiving timer notifications for a given timer

    Syntax

    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.

    Security

    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.

    Return Codes

    All return codes from REGISTER are documented in "Timer Error Code Reference".

    Results

    The result buffer will contain an error message if an error occurred and will be empty otherwise.

    Examples

    Goal: Unregister a timer which the current process previously registered.
    Syntax: UNREGISTER TYPE heartbeat
    Goal: Unregister a timer registered by a process with a handle of 17 on machine A12.
    Syntax: UNREGISTER TYPE heartbeat MACHINE A12 HANDLE 17
    Goal: Unregister a timer registered by process name for process test on machine al5d4.
    Syntax: UNREGISTER TYPE timer07 MACHINE al5d4 PROCESS test
    Goal: Unregister a timer registered by process name by the process submitting the unregister request.
    Syntax: UNREGISTER TYPE timer07 BYNAME

    WATCH

    Notifies the Timer service to begin watching a machine. The Timer service will then register a timer with the machine to be watched, and track whether the machine being watched has sent a notification during the allotted time period (frequency + margin). The timer registered with the machine to be watched will have a type of: STAF/Service/<NAME>/Watch, where <NAME> is the registered name of the Timer service.

    Note: The machine to be watched must have the Timer Service running.

    Syntax

    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.

    Security

    Minimum security level of 3 required to register a machine to be watched.

    Return Codes

    All return codes from WATCH are documented in "Timer Error Code Reference".

    Results

    The result buffer will contain an error message if an error occurred and will be empty otherwise.

    Examples

    Goal: Register the machine 'machine1' to be watched with a frequency of 600000 and a margin of 10000.
    Syntax: WATCH MACHINE machine1 FREQUENCY 600000 MARGIN 10000

    UNWATCH

    Notifies the Timer service to stop watching a machine.

    Syntax

    UNWATCH MACHINE <Machine>
    

    Machine The name of the machine to stop watching.

    Security

    Minimum security level of 4 required for a process to unwatch a machine.

    Return Codes

    All return codes from UNWATCH are documented in "Timer Error Code Reference".

    Results

    The result buffer will contain an error message if an error occurred and will be empty otherwise.

    Examples

    Goal: Stop watching a machine named 'machine1'.
    Syntax: UNWATCH MACHINE machine1

    LIST

    List all registered timers or watches.

    Syntax

    LIST TIMERS | WATCHES [FORMAT]
    

    The optional parameter FORMAT formats the result into a more easily readable format.

    Security

    Minimum security level of 2 required to list timers.

    Return Codes

    All return codes from LIST are documented in the STAF User's Guide.

    Results

    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.

    Examples

    LIST TIMERS

    Result buffer might contain:
    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;
    
    LIST TIMERS FORMAT

    Result buffer might contain:
    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
    
    LIST WATCHES

    Result buffer might contain:
    MACHINE1;OK;19990816-11:28:44;600000;10000;
    SERVER;Missed;19990814-12:24:55;6000000;30000;
    
    LIST TIMERS FORMAT

    Result buffer might contain:
    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

    Update variable references

    Syntax

    REFRESH
    

    Security

    Minimum security level of 3 required to refresh variables.

    Return Codes

    All return codes from REFRESH are documented in the STAF User's Guide.

    Results

    The result buffer contains no data on return from a REFRESH command.

    Timer Queue Messages

    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.

    Timer Error Code Reference

    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.