# $EPIC: timerctl.txt,v 1.4 2006/08/29 18:22:56 sthalik Exp $
======Synopsis:======
$[[timerctl]](REFNUMS) \
$[[timerctl]](REFNUM <refnum>) \\
$[[timerctl]](ADD <refnum> <interval> <events> <commands> <subargs> <window>) (NOT IMPLEMENTED YET) \\
$[[timerctl]](DELETE <refnum>) \\
$[[timerctl]](GET <refnum> <item>) \\
$[[timerctl]](SET <refnum> <item> <value>) \\

======Technical:======
   * This function is a low-level interface to the client's [[timer]] system.
   * The REFNUMS operation returns all of the [[timer]] names (refnums) that are currently pending, including any system timers that may not be visible from the /[[timer]] command.
   * The REFNUM operation returns <refnum> if <refnum> is a pending timer.
   * The ADD operation isn't implemented yet.  Sorry.
   * The DELETE operation removes a pending [[timer]].  It returns 0 on success, and the empty string if the timer doesn't exist or is a system timer.
   * The GET/SET operators work by retreiving or setting attributes of the pending [[timer]]s.  The SET operator always returns the empty string, whether the operation succeeded or failed.  The GET operator returns the empty string if the requested timer doesn't exist.

======GET and SET attributes:======
|        TIMEOUT  |The $[[utime function|utime]]() when the timer expires.          |
|        COMMAND  |The commands that will be run when timer expires  |
|        SUBARGS  |The value that $* will have when timer is run.    |
|        REPEATS  |The number of times this timer should be run      |
|        INTERVAL |The $[[utime function|utime]]() between REPEATs.                 |
|        SERVER   |The server in whose context the timer is run.     |
|        WINDOW   |The window in whose context the timer is run.     |

The //GET num SERVER// and //GET num WINDOW// attributes will return -1 if
the window is not a server or window timer.  Naturally if both return -1 
then it is neither: it is a general timer by rule.

If you SET the //SERVER// or //WINDOW// value, it unconditionally turns 
the timer into a server or window timer, no matter what it was before.

You are never permitted to SET any value for system timers.

You should be able to set the CANCELABLE and FIRES attributes, but that
isn't supported yet.

======History:======
The $[[timerctl]]() function first appeared in EPIC4-1.1.8.