Article # 72, added by Geoworks, historical record
| first | previous | index | next | last |

Using TimerStart for real-time events.




There are two concepts of real-time clock alarms:
1) An event that is registered with the Real-time Clock Manager,
2) A simple timer that sends the event at a given time.


The benefit of registering an event with the RTCM is that the timer
will not be stopped and freed when your application exits (this is
what happens if you start a standard timer with TimerStart()).
The RTCM event is registered via call to RTCMRegisterEvent().  
The specified message will be sent to your application's process.
If you application is not currently running, the RTCM will launch
it and send the message.


TimerStart(TIMER_EVENT_REAL_TIME), similarly, starts a real-time
clock on the device that will send a message at the date and time
you specify.  The big difference is that this timer will be freed
by the system when your application exits, so it is only useful
for near-term real-time events.

For TIMER_EVENT_REAL_TIME, you pass the date that the event should
happen in the "ticks" parameter and the time of day in the "interval"
parameter of TimerStart().

The date is stored in a compressed format that is word-sized.
The year (since 1980) is in the high 7 bits; the month is in
the next 4 bits; and the day is in the low 5-bits.

The hour is stored in the high byte of "interval" and the
minute is stored in the low byte of "interval."

For example, if I wanted to have a wakeup notification sent
on March 5, 1996 at 8:05am, I would set up the "ticks" and
"interval" parameter as follows:

ticks = 0x2065;
 (year = 1996-1980 = 16 = 0x10,  0x10 << 9 = 0x2000;
  month = 3,  0x03 << 5 = 0x0060;
  day = 5,  0x05 << 0 = 0x0005)

interval = 0x0805;


No matter which real-time event you are considering, you 
may find it useful to use the TimerFileDateTime structure
with TimerGetFileDateTime() or the TimerDateAndTime structure
with TimerGetDateAndTime().  

To help in calculating new dates based on the current time,
you can use LocalCalcDaysInMonth().