Timer Service

Version 3.0.3

Last updated: December 1, 2009

Overview

Installation and Configuration

Variables

Request Syntax

UNREGISTER

WATCH

UNWATCH

LIST

REFRESH

VERSION

HELP

Timer Queue Messages

Timer Error Code Reference

Overview

The Timer service is an external STAF service that provides the following functions:

REGISTER - Registers the requesting process to receive a timer notification at a given frequency
UNREGISTER - Unregisters a process from receiving timer notifications for a given timer
WATCH - Notifies the Timer service to begin watching a machine.
UNWATCH - Notifies the Timer service to stop watching a machine.
LIST - List all currently running timers, watches, or the operational settings for the service.
REFRESH - Notifies the timer service that the variables associated with this service have changed
VERSION - Causes the timer service to output the version level
HELP - Causes the timer service to output help text

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.

Installation and Configuration

This service requires:

STAF Version 3.0.0 or later
Java 1.2 or later

Note that all machines submitting REGISTER/UNREGISTER requests to the Timer V3.x service and all machines specified in a WATCH/UNWATCH must be running STAF V3.0.0 or later.

Install the Timer service by downloading the TimerV303.tar/zip file from Get STAF Services and extracting its contents to a local directory (e.g. C:\STAF\services or /usr/local/staf/services). The STAFTimer.jar file is the service jar file needed when registering the Timer service.

The Timer service is written in Java and since it is an external service, it must be registered with the SERVICE configuration statement in the STAF configuration file. The syntax is:

SERVICE <Name> LIBRARY JSTAF EXECUTE <Service Jar File Name>
               [OPTION <Name[=Value]>]... [PARMS <Data Directory>]

where:

SERVICE specifies the name by which the Timer service will be known on this machine.
EXECUTE specifies the fully-qualified name of the STAFTimer.jar file. On Windows systems, this might be C:\STAF\services\timer\STAFTimer.jar. On Unix systems, this might be /usr/local/staf/services/timer/STAFTimer.jar.

OPTION specifes a configuration option that will be passed on to the JSTAF Java service proxy library. This is typically used by service proxy libraries to further control the interface to the actual service implementation. You may specify multiple OPTIONs for a given service. See the STAF User's Guide for more information on options for the JSTAF Java service proxy library.
PARMS specifies the fully-qualified name of the directory in which the Timer service should store persistent data. The default is {STAF/DataDir}/service/<Timer Service Name (lower-case)>

Examples

SERVICE Timer LIBRARY JSTAF EXECUTE C:/STAF/services/timer/STAFTimer.jar
SERVICE Timer LIBRARY JSTAF EXECUTE /usr/local/staf/services/timer/STAFTimer.jar
SERVICE Timer LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/services/timer/STAFTimer.jar PARMS {STAF/DataDir}/service/timer

Or, you can dynamically add the Timer service using the SERVICE service's ADD SERVICE request.

Variables

The following variables can be defined in the STAF configuration file or set dynamically using the VAR service 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: set 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: set 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: set 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: set var STAF/Service/Timer/TotalFireAttempts=5

Default: 3

Request Syntax

The Timer service provides the following requests:

REGISTER - Registers the requesting process to receive a timer notification at a given frequency.
UNREGISTER - Unregisters a process from receiving timer notifications for a given timer.
WATCH - Notifies the Timer service to begin watching a machine.
UNWATCH - Notifies the Timer service to stop watching a machine.
LIST - List all currently running timers, watches, or operational settings for the service.
REFRESH - Notifies the timer service that the variables associated with this service have changed
VERSION - Returns the version level of the Timer service.
HELP - Displays the help text for using the Timer service.

REGISTER

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

Syntax

REGISTER   TYPE <Type> FREQUENCY <Milliseconds> [PRIORITY <Level>] [KEY <Key>]
           [BYNAME] [UNREGONNOPATH <1 | 0>] [UNREGONNOHANDLE <1 | 0>]

TYPE specifies a name used to identify the type of timer.

FREQUENCY specifies the frequency of the timer in milliseconds.

PRIORITY specifies the priority level of the notification message to be sent to the registering machine. The default value is 5.

KEY specifies a key to identify the timer. The default value is an empty string. Any timer registered with a key must be unregistered specifying the key.

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.

UNREGONNOPATH may be specified to set timer specific values for the UnregisterOnNoPath variable. If this option is not specified, the timer will use the global values specified via the STAF VAR service.

UNREGONNOHANDLE may be specified to set timer specific values for the UnregisterOnNoHandle variable. If this option is not specified, the timer will use the global values specified via the STAF VAR service.

Note: If a timer already exists with the same TYPE, registering machine and process or handle, and key, you will get an Already Exists error code returned.

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 Appendix A, "API Return Codes", in the STAF User's Guide.

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 system 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

Goal: Register a timer with a name of heartbeat, a frequency of 2 minutes, and a key of MyHeartbeat.

Syntax: REGISTER TYPE heartbeat FREQUENCY 120000 KEY MyHeartbeat

UNREGISTER

Unregisters a process from receiving timer notifications for a given timer

Syntax

UNREGISTER TYPE <Type> [KEY] [BYNAME | <MACHINE <Machine> HANDLE <Handle #> | NAME <Handle Name>>]

TYPE specifies the type of the timer to terminate. This must be the same as the TYPE option used when the timer was registered.

KEY specifies a key to identify the timer. This must be the same as the KEY option used when the timer was registered, or do not specify the key if no key was specified when the timer was registered.

MACHINE specifies the machine which issued the register command if different from the current machine.

HANDLE specifies the handle number of the process which issued the REGISTER command if different from the current process handle number.

NAME specifies the handle name of the process which issued the REGISTER command.

BYNAME specifies to unregister this timer using the handle name rather than the handle number of the process. This is required if the timer was registered using the handle name.

Note: If the MACHINE parameter is specified, then BYNAME cannot be specified. The timer will be unregistered using either the handle number or the handle name based upon which parameter (HANDLE or NAME) 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 UNREGISTER are documented in Appendix A, "API Return Codes", in the STAF User's Guide.

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 tcp://server1.company.com@6500

Syntax: UNREGISTER TYPE heartbeat MACHINE tcp://server1.company.com@6500 HANDLE 17

Goal: Unregister a timer registered by process name for process test on machine tcp://client1.company.com@6500.

Syntax: UNREGISTER TYPE timer07 MACHINE tcp://client1.company.com@6500 PROCESS test

Goal: Unregister a timer registered by process name by the process submitting the unregister request.

Syntax: UNREGISTER TYPE timer07 BYNAME

Goal: Unregister a timer which the current process previously registered with a key of MyHeartbeat.

Syntax: UNREGISTER TYPE heartbeat KEY MyHeartbeat

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 and will have a key set to the name of the machine specified to be watched.

Note: The machine to be watched must have Timer Service V3.0.0 or later running.

Syntax

WATCH MACHINE <Machine> FREQUENCY <Milliseconds> [MARGIN <Milliseconds>]

MACHINE specifies the name of the machine to be watched.

FREQUENCY specifies the frequency at which the machine should send notifications, in milliseconds.

MARGIN specifies 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 Appendix A, "API Return Codes", in the STAF User's Guide.

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 10 minutes (600000 milliseconds) and a margin of 10 seconds (10000 milliseconds).

Syntax: WATCH MACHINE machine1 FREQUENCY 600000 MARGIN 10000

Goal: Register the machine client1.company.com to be watched with a frequency of 2 minutes (120000 milliseconds) and a margin of 10 seconds (10000 milliseconds).

Syntax: WATCH MACHINE client1.company.com FREQUENCY 120000 MARGIN 10000

UNWATCH

Notifies the Timer service to stop watching a machine.

Syntax

UNWATCH MACHINE <Machine>

MACHINE specifies 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 Appendix A, "API Return Codes", in the STAF User's Guide.

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

Goal: Stop watching a machine named 'client1.company.com'.

Syntax: UNWATCH MACHINE client1.company.com

LIST

List all registered timers, watches, or the operational settings for the Timer service.

Syntax

LIST <TIMERS [LONG]> | WATCHES | SETTINGS

TIMERS specifies to list the registerd timers.

LONG provides more detailed information when listing the registered timers.

WATCHES specifies to list the watches.

SETTINGS specifies to list the operational settings for the service.

Security

Minimum security level of 2 is required.

Return Codes

All return codes from LIST are documented in Appendix A, "API Return Codes", in the STAF User's Guide.

Results

If a LIST TIMERS request is specified, upon successful return, the result buffer will contain a marshalled <List> of <Map:STAF/Service/Timer/Timer> representing a list of the registered timers. The map is defined as follows:

Definition of map class STAF/Service/Timer/Timer

Description: This map class represents a registered timer.

Key Name Display Name Type Format / Value

type Type <String>

machine Machine <String>

notifyBy Notify By (Notify) <String> 'Handle' | 'Name'

notifiee Notifiee <String>

key Key <String>

lastTimestamp Last Fired Date-Time (Last Date-Time) <String> | <None> <YYYYMMDD-HH:MM:SS>

frequency Frequency (Freq) <String>

Notes:

The Type value is set to the name used to identify the timer.
The Machine value is set to the machine which submitted the REGISTER request.
The Notify By value is set to 'Handle' if the timer was registered by handle number or 'Name' if the timer was registered by handle name.
The Notifiee value is set to one of the following:

If the timer was registered by handle number, the value is set to the handle number of the process which submitted the REGISTER request.
If the timer was registered by handle name, the value is set to the handle name of the process which submitted the REGISTER request .

The Key value is set to the key specified when registering the timer, or an empty string if no key was specified when registering the timer.
The Last Fired Date-Time value is set to the timestamp of the last notification sent to the notifiee for the timer or <None> if no notification has been sent to the notifiee for the timer yet.
The Frequency value is set to the frequency of the timer is milliseconds.

Definition of map class STAF/Service/Timer/Timer
`type`	`Type`	`<String>`
`machine`	`Machine`	`<String>`
`notifyBy`	`Notify By (Notify)`	`<String>`	`'Handle' \| 'Name'`
`notifiee`	`Notifiee`	`<String>`
`key`	`Key`	`<String>`
`lastTimestamp`	`Last Fired Date-Time (Last Date-Time)`	`<String> \| <None>`	`<YYYYMMDD-HH:MM:SS>`
`frequency`	`Frequency (Freq)`	`<String>`
Notes: The `Type` value is set to the name used to identify the timer. The `Machine` value is set to the machine which submitted the `REGISTER` request. The `Notify By` value is set to `'Handle'` if the timer was registered by handle number or `'Name'` if the timer was registered by handle name. The `Notifiee` value is set to one of the following: If the timer was registered by handle number, the value is set to the handle number of the process which submitted the `REGISTER` request. If the timer was registered by handle name, the value is set to the handle name of the process which submitted the `REGISTER` request . The `Key` value is set to the key specified when registering the timer, or an empty string if no key was specified when registering the timer. The `Last Fired Date-Time` value is set to the timestamp of the last notification sent to the notifiee for the timer or `<None>` if no notification has been sent to the notifiee for the timer yet. The `Frequency` value is set to the frequency of the timer is milliseconds.

If a LIST TIMERS LONG request is specified, upon successful return, the result buffer will contain a marshalled <List> of <Map:STAF/Service/Timer/TimerLong> representing a list of the registered timers, containing detailed information about each timer. The map is defined as follows:

Definition of map class STAF/Service/Timer/TimerLong

Description: This map class represents detailed information about a registered timer.

Key Name Display Name Type Format / Value

type Type <String>

machine Machine <String>

notifyBy Notify By <String> 'Handle' | 'Name'

notifiee Notifiee <String>

key Key <String>

lastTimestamp Last Fired Date-Time <String> | <None> <YYYYMMDD-HH:MM:SS>

frequency Frequency <String>

priority Priority <String>

unRegOnNoPath Unregister On No Path <String> 'true' | 'false' | 'global'

unRegOnNoHandle Unregister On No Handle <String> 'true' | 'false' | 'global'

Notes:

The Type value is set to the named used to identify the timer.
The Machine value is set to the machine which submitted the REGISTER request.
The Notify By value is set to 'Handle' if the timer was registered by handle number or 'Name' if the timer was registered by handle name.
The Notifiee value is set to one of the following:

If the timer was registered by handle number, the value is set to the handle number of the process which submitted the REGISTER request.
If the timer was registered by handle name, the value is set to the handle name of the process which submitted the REGISTER request .

The Key value is set to the key specified when registering the timer, or an empty string if no key was specified when registering the timer.
The Last Fired Date-Time value is set to the timestamp of the last notification sent to the notifiee for the timer or <None> if no notification has been sent to the notifiee for the timer yet.
The Frequency value is set to the frequency of the timer is milliseconds.
The Priority value is set to the priority of the notification message sent to the notifiee for the timer.
The Unregister On No Path value is set to the value of the timer specific variable named STAF/Service/Timer/UnregisterOnNoPath. It can be set to one of three values:

'true' indicates that UNREGONNOPATH was set to 1 on the REGISTER request.
'false' indicates that UNREGONNOPATH was set to 0 on the REGISTER request.
'global' indicates no timer specific value is set.

The "Unregister On No Handle" value is set to the value of the timer specific variable named STAF/Service/Timer/UnregisterOnNoHandle.

'true' indicates that UNREGONNOHANDLE was set to 1 on the REGISTER request.
'false' indicates that UNREGONNOHANDLE was set to 0 on the REGISTER request.
'global' indicates no timer specific value is set.

Definition of map class STAF/Service/Timer/TimerLong
`type`	`Type`	`<String>`
`machine`	`Machine`	`<String>`
`notifyBy`	`Notify By`	`<String>`	`'Handle' \| 'Name'`
`notifiee`	`Notifiee`	`<String>`
`key`	`Key`	`<String>`
`lastTimestamp`	`Last Fired Date-Time`	`<String> \| <None>`	`<YYYYMMDD-HH:MM:SS>`
`frequency`	`Frequency`	`<String>`
`priority`	`Priority`	`<String>`
`unRegOnNoPath`	`Unregister On No Path`	`<String>`	`'true' \| 'false' \| 'global'`
`unRegOnNoHandle`	`Unregister On No Handle`	`<String>`	`'true' \| 'false' \| 'global'`
Notes: The `Type` value is set to the named used to identify the timer. The `Machine` value is set to the machine which submitted the `REGISTER` request. The `Notify By` value is set to `'Handle'` if the timer was registered by handle number or `'Name'` if the timer was registered by handle name. The `Notifiee` value is set to one of the following: If the timer was registered by handle number, the value is set to the handle number of the process which submitted the `REGISTER` request. If the timer was registered by handle name, the value is set to the handle name of the process which submitted the `REGISTER` request . The `Key` value is set to the key specified when registering the timer, or an empty string if no key was specified when registering the timer. The `Last Fired Date-Time` value is set to the timestamp of the last notification sent to the notifiee for the timer or `<None>` if no notification has been sent to the notifiee for the timer yet. The `Frequency` value is set to the frequency of the timer is milliseconds. The `Priority` value is set to the priority of the notification message sent to the notifiee for the timer. The `Unregister On No Path` value is set to the value of the timer specific variable named STAF/Service/Timer/UnregisterOnNoPath. It can be set to one of three values: `'true'` indicates that `UNREGONNOPATH` was set to 1 on the `REGISTER` request. `'false'` indicates that `UNREGONNOPATH` was set to 0 on the `REGISTER` request. `'global'` indicates no timer specific value is set. The "Unregister On No Handle" value is set to the value of the timer specific variable named STAF/Service/Timer/UnregisterOnNoHandle. `'true'` indicates that `UNREGONNOHANDLE` was set to 1 on the `REGISTER` request. `'false'` indicates that `UNREGONNOHANDLE` was set to 0 on the `REGISTER` request. `'global'` indicates no timer specific value is set.

If a LIST WATCHES request is specified, upon successful return, the result buffer will contain a marshalled <List> of <Map:STAF/Service/Timer/Watch> representing a list of the watches. The map is defined as follows:

Definition of map class STAF/Service/Timer/Watch

Description: This map class represents a watch.

Key Name Display Name Type Format / Value

machine Machine <String>

status Status <String> 'OK' | 'Missed'

lastTimestamp Last Fired Date-Time (Last Date-Time) <String> | <None> <YYYYMMDD-HH:MM:SS>

frequency Frequency (Freq) <String>

margin Margin <String>

Notes:

The Machine value is set to the name of the machine beiung watched.
The Status value indicates whether the machine is sending timely notifications.
The Last Fired Date-Time value is set to the timestamp of the last notification received from the machine or <None> if no notification has been received yet.
The Frequency value is set to the frequency (in milliseconds) with which the machine should respond.
The Margin value is set to the allowable margin of error before the machine is marked as not responding.

Definition of map class STAF/Service/Timer/Watch
`machine`	`Machine`	`<String>`
`status`	`Status`	`<String>`	`'OK' \| 'Missed'`
`lastTimestamp`	`Last Fired Date-Time (Last Date-Time)`	`<String> \| <None>`	`<YYYYMMDD-HH:MM:SS>`
`frequency`	`Frequency (Freq)`	`<String>`
`margin`	`Margin`	`<String>`
Notes: The `Machine` value is set to the name of the machine beiung watched. The `Status` value indicates whether the machine is sending timely notifications. The `Last Fired Date-Time` value is set to the timestamp of the last notification received from the machine or `<None>` if no notification has been received yet. The `Frequency` value is set to the frequency (in milliseconds) with which the machine should respond. The `Margin` value is set to the allowable margin of error before the machine is marked as not responding.

If a LIST SETTINGS request is specified, upon successful return, the result buffer will contain a marshalled <Map:STAF/Service/Timer/Settings> representing the operational settings for the Timer service. The map is defined as follows:

Definition of map class STAF/Service/Timer/Settings

Description: This map class represents the settings for the Timer service.

Key Name Display Name Type Format / Value

directory Directory <String>

Notes:

The "Directory" value is the directory where the Timer service writes its data. It's value can be overridden via a parameter when registering the Timer service.

Definition of map class STAF/Service/Timer/Settings
directory	Directory	`<String>`
Notes: The "Directory" value is the directory where the Timer service writes its data. It's value can be overridden via a parameter when registering the Timer service.

Examples

Goal: List all of the registered timers (in the short form).

Syntax: LIST TIMERS

Output: If the request is submitted from the command line and the commands in the file are executed successful, the result, in default format, could look like:

Type         Machine         Notify Notifiee     Key  Last Date-Time    Freq
------------ --------------- ------ ------------ ---- ----------------- ------
TIMER1       tcp://client1.c Handle 62                <None>            300000
             ompany.com@6500                      
HEARTBEAT    tcp://client2.c Handle 49                20050215-15:30:36 60000
             ompany.com@6500                        
FULL_REFRESH tcp://client3.c Name   REFRESH           20050215-15:28:44 600000
             ompany.com@6500
STAF/SERVICE tcp://client2.c Name   STAF/Service CLIE 20050215-15:20:53 60000
/TIMER/WATCH ompany.com@6500        /Timer       NT2
STAF/SERVICE tcp://client1.c Name   STAF/Service CLIE 20050215-15:20:46 45000
/TIMER/WATCH ompany.com@6500        Timer/Watch  NT1

Goal: List all of the registered timers in the long form (providing detailed information on the timers).

Syntax: LIST TIMERS LONG

Output: If the request is submitted from the command line and the commands in the file are executed successful, the result, in default format, could look like:

[
  {
    Type                   : TIMER1
    Machine                : tcp://client1.company.com@6500
    Notify By              : Handle
    Notifiee               : 62
    Key                    :
    Last Fired Date-Time   : <None>
    Frequency              : 300000
    Priority               : 4
    Unregister On No Path  : global
    Unregister On No Handle: global
  }
  {
    Type                   : HEARTBEAT
    Machine                : tcp://client2.company.com@6500
    Notify By              : Handle
    Notifiee               : 49
    Last Fired Date-Time   : 20050215-15:20:53
    Frequency              : 60000
    Priority               : 5
    Unregister On No Path  : global
    Unregister On No Handle: global
  }
  {
    Type                   : FULL REFRESH
    Machine                : tcp://client3.company.com@6500
    Notify By              : Name
    Notifiee               : REFRESH
    Last Fired Date-Time   : 20050215-15:28:44
    Frequency              : 600000
    Priority               : 2
    Unregister On No Path  : true
    Unregister On No Handle: false
  }
  {
    Type                   : STAF/SERVICE/TIMER/WATCH
    Machine                : tcp://client2.company.com@6500
    Notify By              : Name
    Notifiee               : STAF/Service/Timer
    Last Fired Date-Time   : 20050215-15:20:53
    Frequency              : 60000
    Priority               : 5
    Unregister On No Path  : global
    Unregister On No Handle: true
  }
  {
    Type                   : STAF/SERVICE/TIMER/WATCH
    Machine                : tcp://client1.company.com@6500
    Notify By              : Name
    Notifiee               : STAF/Service/Timer/Watch
    Last Fired Date-Time   : 20050215-15:20:46
    Frequency              : 45000
    Priority               : 5
    Unregister On No Path  : false
    Unregister On No Handle: false
  }
]

Goal: List all of the watches.

Syntax: LIST WATCHES

Output: If the request is submitted from the command line and the commands in the file are executed successful, the result, in default format, could look like:

Machine To Watch       Machine Status Last Fired Date-Time Frequency Margin
---------------------- -------------- -------------------- --------- ------
CLIENT1                OK             20050215-15:20:46    60000     10000
SERVER1.AUSTIN.IBM.COM Missed         20050215-12:24:55    600000    30000

Goal: List the operational settings for the Timer service.
Syntax: LIST SETTINGS
Output: If the request is submitted from the command line, the result, in default format, could look like:
```
Directory: C:\STAF\data\STAF\service\timer
```

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 Appendix A, "API Return Codes", in the STAF User's Guide.

Results

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

VERSION

VERSION displays the Timer Service version.

Syntax

VERSION

Security

This request requires at least trust level 1.

Results

The result is the version number of the Timer service.

Examples

Goal: Display the version of the Timer service on machine server1.company.com:
STAF server1.company.com timer VERSION
Output:
```
3.0.3
```

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 Timer service.

Examples

Goal: Display the syntax for the Timer service requests:

STAF local timer HELP

Output:

Timer Service Help

REGISTER   TYPE  FREQUENCY  [PRIORITY ] [KEY ]
           [BYNAME] [UNREGONNOPATH <1 | 0>] [UNREGONNOHANDLE <1 | 0>]
UNREGISTER TYPE  [KEY] [BYNAME |
            HANDLE  | NAME >]
WATCH      MACHINE  FREQUENCY  [MARGIN ]
UNWATCH    MACHINE 
LIST        | WATCHES | SETTINGS
REFRESH
VERSION
HELP

Timer Queue Messages

The timers use the STAF QUEUE service to send notifications to the process which submitted the REGISTER command.

The behavior of the timer if the process is not available is controlled by the variables UnregisterOnNoHandle and UnregisterOnNoPath.

The message queued to the process will have a queue type of "STAF/Service/Timer" with the content of the message being a <Map> defined as follows:

Definition for message map for a "STAF/Service/Timer" type queued message

Description: This map represents a timer message.

Key Name Type Format / Value

type <String>

timerServiceName <String>

timestamp <String> <YYYYMMDD-HH:MM:SS>

key <String>

Notes:

Key type will containe the type of the timer.
Key timerServiceName will contain the registered name of the Timer service that generated the timer.
Key timestamp will contain the formatted time at which the notification was generated.
Key key will contain the key specified when registering the timer. If no key was specified when the timer was registered, the value will be a empty string.

Definition for message map for a "STAF/Service/Timer" type queued message
`type`	`<String>`
`timerServiceName`	`<String>`
`timestamp`	`<String>`	`<YYYYMMDD-HH:MM:SS>`
`key`	`<String>`
Notes: Key `type` will containe the type of the timer. Key `timerServiceName` will contain the registered name of the Timer service that generated the timer. Key `timestamp` will contain the formatted time at which the notification was generated. Key `key` will contain the key specified when registering the timer. If no key was specified when the timer was registered, the value will be a empty string.

Here's an example of a queued message with queue type "STAF/Service/Timer" generated by the Timer service:

STAF local QUEUE GET WAIT
{
  Priority   : 5
  Date-Time  : 20050216-14:46:23
  Machine    : server1.austin.ibm.com
  Handle Name: STAF/Service/Timer
  Handle     : 15
  User       : none://anonymous
  Type       : STAF/Service/Timer
  Message    : {
    timerServiceName: Timer
    type            : HEARTBEAT
    timestamp       : 20050216-14:46:23
    key             :
  }
}

Timer Error Code Reference

There are no additional Timer return codes. The Timer service uses the common STAF return codes.

Definition of map class STAF/Service/Timer/Timer
Description: This map class represents a registered timer.
Key Name	Display Name	Type	Format / Value
`type`	`Type`	`<String>`
`machine`	`Machine`	`<String>`
`notifyBy`	`Notify By (Notify)`	`<String>`	`'Handle' \| 'Name'`
`notifiee`	`Notifiee`	`<String>`
`key`	`Key`	`<String>`
`lastTimestamp`	`Last Fired Date-Time (Last Date-Time)`	`<String> \| <None>`	`<YYYYMMDD-HH:MM:SS>`
`frequency`	`Frequency (Freq)`	`<String>`
Notes: The `Type` value is set to the name used to identify the timer. The `Machine` value is set to the machine which submitted the `REGISTER` request. The `Notify By` value is set to `'Handle'` if the timer was registered by handle number or `'Name'` if the timer was registered by handle name. The `Notifiee` value is set to one of the following: If the timer was registered by handle number, the value is set to the handle number of the process which submitted the `REGISTER` request. If the timer was registered by handle name, the value is set to the handle name of the process which submitted the `REGISTER` request . The `Key` value is set to the key specified when registering the timer, or an empty string if no key was specified when registering the timer. The `Last Fired Date-Time` value is set to the timestamp of the last notification sent to the notifiee for the timer or `<None>` if no notification has been sent to the notifiee for the timer yet. The `Frequency` value is set to the frequency of the timer is milliseconds.

Definition for message map for a "STAF/Service/Timer" type queued message
Description: This map represents a timer message.
Key Name	Type	Format / Value
`type`	`<String>`
`timerServiceName`	`<String>`
`timestamp`	`<String>`	`<YYYYMMDD-HH:MM:SS>`
`key`	`<String>`
Notes: Key `type` will containe the type of the timer. Key `timerServiceName` will contain the registered name of the Timer service that generated the timer. Key `timestamp` will contain the formatted time at which the notification was generated. Key `key` will contain the key specified when registering the timer. If no key was specified when the timer was registered, the value will be a empty string.