Alarm

The Alarm provides a mechanism which notifies a user when a specified time and date have arrived. Once the Alarm has been set, the alarm notification will be received at the specified time and date even if the Alarm component's module is not currently loaded. On some devices, the alarm may even cause the device to power up if it is off when the specified date and time occur.

If the Alarm is enabled when the program's module is unloaded or the device shuts down, then the module's module_goTo() routine will be called when the Alarm triggers. If the Alarm is not enabled when the program's module is unloaded or the device shuts down, then the Alarm will forget its alarm date and alarm time; the value of all its properties will be lost.

Applications should use Alarms sparingly. A Calendar program, for example, might have only one Alarm component, and have that set to the closest even for which the user desires an alarm. When that event occurs, the Alarm could be set to the next event the user needs to be notified about.

Alarm Properties

Standard Properties:

class, enabled, parent, version
enabled: Set this property to one to turn on the alarm; set it to zero to turn it off.

moduleContext string
If the Alarm's module is loaded as a result of the alarm, this value will be passed as the context argument to the module_goTo() routine.

uniqueID string
This string uniquely identifies the Alarm, differentiating it from any other Alarm components which may be on the device at the time. To make your Alarm's name unique, you might want to name it after your company and application name--For example, "Sanrio Keroppi's Day Hopper." This property must be set to something other than its default for the alarm to be useful. Changing the value of this property causes the Alarm to forget its alarm time and alarm date.

Alarm Events

The alarm has no event. When the alarm triggers, the application's module_goTo() routine is called with value of the Alarm's moduleContext property passed as the context argument to module_goTo(). The Alarm's enabled property becomes zero when this happens.

Alarm Actions

GetAlarmDate()

GetAlarmDate() AS STRUCT Date

Get date of alarm. The date is returned in a Date structure:

STRUCT Date
year AS integer
month AS integer
day AS integer
END STRUCT

Make sure that you've set the uniqueID property to a non-empty string before invoking this action; otherwise, an error will result.

GetAlarmTime()

GetAlarmTime() AS STRUCT TimeOfDay

Get time of alarm. The time is represented as a TimeOfDay structure:

STRUCT TimeOfDay
hour AS integer
minute AS integer
second AS integer
END STRUCT

Make sure that you've set the uniqueID property to a non-empty string before invoking this action; otherwise, an error will result.

SetAlarmDate()

SetAlarmDate(date AS STRUCT Date)

Set date of alarm.

Make sure that you've set the uniqueID property to a non-empty string before invoking this action; otherwise, an error will result.

SetAlarmTime()

SetAlarmTime(time AS STRUCT TimeOfDay)

Set time of alarm.

Make sure that you've set the uniqueID property to a non-empty string before invoking this action; otherwise, an error will result.