DEFINE TIMER
Define a BTS timer.
Description
DEFINE TIMER defines a BTS
timer which will expire after a specified interval, or at a specified
time and date. When a timer is defined, an associated event is also
defined, in the event pool of the current activity. The name of the
associated event defaults to the name of the timer. When the timer
expires, its associated event fires.
Note:
- All dates and times refer to local time.
- A timer that specifies a time and date that has already passed expires immediately. Similarly, if the requested interval is zero, the timer expires immediately.
Options
- AFTER
- specifies
the interval of time that is to elapse before the timer is to expire.
You must specify one or more of DAYS(0–999), HOURS(0–23), MINUTES(0–59), and SECONDS(0–59). For example, HOURS(1) SECONDS(3) means one hour and three seconds (the minutes default to zero).
- AT
- specifies
the time at which the timer is to expire. You must specify one or more of HOURS(0–23), MINUTES(0–59), and SECONDS(0–59). For example:
- HOURS(1) means 1 a.m.
- HOURS(15) MINUTES(15) means 3:15 p.m.
- MINUTES(15) means 0:15 a.m.
- DAYOFMONTH(data-value)
- specifies, as a fullword binary value in the range 1–31, the day-of-the-month on which the timer is to expire.
- DAYOFYEAR(data-value)
- specifies, as a fullword binary value in the range 1–366, the day-of-the-year on which the timer is to expire. For example, DAYOFYEAR(1) specifies 1st January.
- DAYS(data-value)
- specifies
a fullword binary value in the range 0–999. This is a suboption of
the AFTER option. For its use and meaning, see AFTER.
The default value is zero.
- EVENT(data-value)
- specifies
the name (1–16 characters) of the event to be associated with the
timer. The acceptable characters are A-Z a-z 0-9 $ @ # . - and _.
Leading and embedded blank characters are not permitted. If the name
supplied is less than 16 characters, it is padded with trailing blanks
up to 16 characters.
The default event name is the name of the timer.
- HOURS(data-value)
- specifies
a fullword binary value in the range 0–23. This is a suboption of
the AFTER and AT options. For its use and meaning, see these options.
The default value is zero.
- MINUTES(data-value)
- specifies
a fullword binary value in the range 0–59. This is a suboption of
the AFTER and AT options. For its use and meaning, see these options.
The default value is zero.
- MONTH(data-value)
- specifies, as a fullword binary value in the range 1–12, the month in which the timer is to expire.
- ON
- specifies
the date at which the timer is to expire, as a combination of the
YEAR, MONTH, DAYOFMONTH, and DAYOFYEAR options.
If the ON option is not specified, the default date is today.
- SECONDS(data-value)
- specifies
a fullword binary value in the range 0–59. This is a suboption of
the AFTER and AT options. For its use and meaning, see these options.
The default value is zero.
- TIMER(data-value)
- specifies the name (1–16 characters) of the timer. The acceptable characters are A-Z a-z 0-9 $ @ # . - and _. Leading and embedded blank characters are not permitted. If the name supplied is less than 16 characters, it is padded with trailing blanks up to 16 characters.
- YEAR(data-value)
- specifies, as a fullword binary value in the range 0–2040, the year in which the timer is to expire.
Conditions
- 111 EVENTERR
- RESP2
values:
- 6
- The event name specified on the EVENT option is invalid.
- 7
- The event name specified on the EVENT option (or the default event name taken from the timer name) has already been defined to this activity.
- 16 INVREQ
- RESP2
values:
- 1
- The command was issued outside the scope of a currently-active activity.
- 11
- An invalid interval was specified.
- 12
- An invalid date or time was specified.
- 115 TIMERERR
- RESP2
values:
- 14
- The timer name specified on the TIMER option is invalid.
- 15
- The timer name specified on the TIMER option has already been defined to this activity.
Examples
DEFINE TIMER() AT HOURS(15)
defines
a timer that will expire at 3 p.m. today (or immediately if the local
time is already later than 3 p.m.).DEFINE TIMER() AT HOURS(15) ON YEAR(2001) MONTH(11) DAYOFMONTH(3)
defines
a timer that will expire at 3 p.m. on 3rd November 2001.DEFINE TIMER() AT HOURS(15) ON YEAR(2001) DAYOFYEAR(32)
defines
a timer that will expire at 3 p.m. on 1st February 2001.DEFINE TIMER() AT HOURS(8) ON YEAR(1997) MONTH(1) DAYOFMONTH(1)
defines
a timer that expires immediately.