Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

11    Time

System Management

Exploring Palm OS®

The Palm Powered™ device has a real-time clock and programmable timer. The real-time clock maintains the current time even when the system is in sleep mode (turned off). It's capable of generating an interrupt to wake the device when an alarm is set by the user. The programmable timer is used to generate the system tick count interrupts while the processor is in doze or running mode. The system tick interrupts are required for periodic activity such as polling the digitizer for user input, key debouncing, and so on.

The Date and Time Manager (called Time Manager in this chapter) provides access to the timing resources on the Palm Powered device.

The basic Time Manager API provides support for setting and getting the real-time clock in seconds and for getting the current system ticks value (but not for setting it). The System Manager provides more advanced functionality for setting up a timer task that executes periodically or in a given number of system ticks, and includes a number of macros that allow you to convert a system time value (a time interval, in ticks) to and from more natural units such as seconds and milliseconds.

This chapter discusses the following topics:

Using Real-Time Clock Functions ^TOP^

The real-time clock functions of the Time Manager include TimSetSeconds() and TimGetSeconds(). Real time on the Palm Powered device is measured in seconds from midnight, Jan. 1, 1904. Call TimSecondsToDateTime() and TimDateTimeToSeconds() to convert between seconds and a structure specifying year, month, day, hour, minute, and second.

Using System Ticks Functions ^TOP^

The Palm Powered device maintains a tick count that starts at 0 when the device is reset. This tick increments 1000 times per second when running on the Palm Powered device.

For tick-based timing purposes, applications could use the macro SysTicksPerSecond(), which is conditionally compiled for different platforms. However, the use of a more natural set of units, such as seconds or milliseconds, is preferrable. The various SysTimeIn... macros, such as SysTimeInMilliSecs(), allow you to convert a system time value (a time interval, in ticks) to more conventional units. To convert from such units back to a system time value, use one of the SysTimeTo... macros, such as SysTimeToMilliSecs().

Use the function TimGetTicks() to read the current tick count.

Although the TimGetTicks() function could be used in a loop to implement a delay, it is recommended that applications use the SysTaskDelay() function instead. The SysTaskDelay() function automatically puts the unit into low-power mode during the delay. Using TimGetTicks() in a loop consumes much more current.