OnTime

Syntax

OnTime When[$], Name$ [, Tolerance]

Remarks

Sets up a background timer that runs a macro at the time specified by When[$]. If Word is occupied at the specified time — for example, if a dialog box is displayed or Word is performing a large sort operation — the macro runs as soon as Word is idle.

If you close Word before When[$], the timer is canceled and is not reactivated when you start Word. To reset the timer each time you start Word — for example, if you want to automatically set an alarm macro at your next Word session (see the example in this entry) — name the macro that includes the OnTime instruction "AutoExec." For information about AutoExec and other auto macros, see
Chapter 2, "Getting Started with Macros," in Part 1, "Learning WordBasic."

Argument	Explanation

When[$]	The time the macro is to be run, expressed as text in a 24-hour format (hours:minutes:seconds) or as a serial number, a decimal representation of the date, time, or both. For more information on serial numbers, see DateSerial(). When you specify the time as text, including seconds is optional. For example, 2:37 p.m. is expressed as "14:37" and 2:37 a.m. is expressed as "02:37" or "2:37." Midnight is "00:00:00." You can include a string representing the date before the time. There are several available date formats. You can control the default date format by choosing the International option in Control Panel (Windows) or by using a control panel such as Date & Time (Macintosh). If the date is not specified, the macro runs at the first occurrence of the specified time.
Name$	The name of the macro to be run. For the macro to run, it must be available both when the OnTime instruction is run and when the specified time has arrived. For this reason, it is best to specify a macro in the global template, NORMAL.DOT. The format MacroName.SubroutineName is not allowed.
Tolerance	If Name$ has not yet started within Tolerance seconds after When, Word will not run the macro. If Tolerance is 0 (zero) or omitted, Word always runs the macro, regardless of how many seconds elapse before Word is idle and can run the macro.

Note

Word can run only one OnTime macro at a time. If you start a second, the first OnTime macro is canceled.

Example

This example sets up a simple alarm clock function in Word. The first macro in the example sets up the background timer.

'Alarm program: Prompts user to input time for alarm to sound
'Current time appears in title bar of input box
Sub MAIN
Alarm$ = InputBox$("Time? (HH:mm:ss), 24hr", "Alarm " + Time$())
'Set background timer to run macro called Beeper
'No tolerance is set, so alarm will always sound
OnTime Alarm$, "Beeper" 
End Sub

The following macro sounds an alarm and displays an alert message in response to the timer set up by the preceding macro. This macro must be named "Beeper" to work properly with the preceding macro.

Sub MAIN                        'Beeper program
For count = 1 To 7
    Beep
    Beep
    For TL = 1 To 100        'Adds a delay between beeps
    Next
Next
MsgBox "Preset alarm sounded", "Beeper " + Time$(), 48
End Sub

See Also

Date$(), DateSerial(), DateValue(), Day(), Month(), Now(), TimeValue(), Today(), Year()