Timer Macros

Macros: WaitSecs, WaitTime, WaitCyclic0-9

Three kinds of macro timers are available. All of them suspend macro processing, either for a specified duration or until a specified time. While macros are suspended, all other Daqarta operations continue normally. You can use these macros to run tests with specified durations or start and stop times, or at specified intervals.

• WaitSecs waits for a specified duration.
• WaitTime waits until a specified time and/or date.
• WaitCyclic0-9 timers wait for repeating intervals.

WaitSecs:

WaitSecs delays macro processing for a specified duration, which can either be in seconds or H:M:S format. Thus WaitSecs=3600 and WaitSecs=1:0:0 both specify a 1 hour delay. Fractional seconds are allowed, such as WaitSecs=65.25 or WaitSecs=1:5.25 for 65.25 seconds. (But see the resolution discussion below.)

Note that WaitSecs=1:00 specifies 1 minute, not 1 hour.

Maximum delay is equivalent to just over 1193 hrs or 49.7 days. You can set the maximum by giving a very large value, such as WaitSecs=5G which attempts to set 5 billion seconds. Daqarta will limit it automatically.

Minimum delay and delay resolution are determined by your version of Windows. Win9x versions only resolve to about 55 msec ( WaitSecs=55m) whereas NT, 2K, and XP typically resolve to about 10 msec. Note, however, that WaitSecs timing is not a high priority operation, so there may be several 10s of msec lag while other operations like screen updates are taking place.

WaitSecs is ideal for setting the duration of long tests or sound exposures. Typically, a ' !' auto-run start-up macro will load the needed GEN setup and prompt the user to set any test-specific details like level or frequency before hitting a test start macro. That might look like:

  Field1=>d          ;Start date
  Field2=>t          ;Start time
  Gen=1              ;Sound on
  WaitSecs=12:0:0    ;Run for 12 hours
  Gen=0              ;Sound off
  Field3=>t          ;Stop time

Note that the above macro writes the start date, start time, and stop time to Field1-Field3. Not shown here are the commands in the start-up macro that would set Label1-Label3 to identify these. Labels and Fields are included when a DQA file is saved, so the above macro could have included a SaveDQA command to preserve a record of the test times. See the WaitChange command for an example of how to prompt the user for a file name before the start of the test.

You can use another WaitSecs at the start of the above macro to delay before starting the test. For example, you may want to run a very noisy test when the building is empty at night or over the weekend, to be completed just before anyone starts work the next day. See also the following WaitTime command for this purpose.

WaitTime:

WaitTime waits until the specified time and/or date before proceeding. Alternatively, it can wait until a specified day of the week, or list of days, for tasks that recur on regular weekly schedules. Or you can specify only the day of the month for tasks that recur monthly, or only the time of day for those that recur daily. Special options allow you to specify the timing of tasks that recur each hour, minute, or second. (See WaitCyclic0-9 for other recurring timers.) Specified times can be local or UTC.

Note that dates are always specified in D/M/Y format, regardless of the date format chosen in the Date/Time Preferences menu. This allows macro timers to work the same way on any system, so you can exchange macro files with Daqarta users anywhere in the world.

Month and year may be omitted if the date is in the current month. Year may be omitted if the date is in the current year. If you specify a year value of 99 or less, it will have 2000 added to it.

Times are in H:M:S format and must always be preceded by ' @'. 24-hour time is assumed, but you can add a ' P' after the time to specify PM. You can specify fractional seconds, but as with WaitSecs the resolution is limited by your system.

WaitTime=15/3/2020@10:30 specifies 15 Mar 2020 at 10:30 AM local time.

Note that WaitTime will waken your system from Standby or Hibernation, if needed (and if your system supports these modes). However, the wake-up process begins at the time specified in WaitTime... depending on how long your system takes to get ready, actual macro processing may not resume for a minute or more. If it is critical that your test run at a specified time, you should use back-to-back WaitTime macros, with the first one set for (say) five minutes before the actual test start time in order to insure the system is ready.

To schedule tasks that recur monthly, daily, hourly, or each minute or second, you can omit larger units of time. For example, you can omit the year and month to schedule a task that recurs each month. (You can't schedule annual tasks by omitting only the year, however.)

WaitTime=U15@1:00P specifies the 15th of the month at 1:00 PM UTC time. If that is already past for this month, the timer will wait until that time and date next month.

WaitTime=31@8:00 specifies the 31st of the month at 8:00 AM local time. If the current month has less than 31 days, this command uses the last day of the month. If the specified time is already past for this month, the timer will wait until the last day of the next month.

WaitTime=@0:10 specifies 10 minutes after midnight, local time, regardless of date. If that time is past for the current day, it will wait until the next day.

WaitTime=@H:15 specifies 15 minutes after the hour. If that time is past for the current hour, it will wait until the next hour.

WaitTime=@H:M:00 specifies the next minute.

WaitTime=@H:M:S: specifies the next second. Note that a colon is required after S, and that, unlike the next day, hour, or minute options above, no fractional seconds are allowed.

Note that you can not use M: without H:, or S: without H:M:.

WaitTime=Mo@12:00 specifies Monday at noon, local time. Days of the week are entered as:

  Su = Sunday
  Mo = Monday
  Tu = Tuesday
  We = Wednesday
  Th = Thursday
  Fr = Friday
  Sa = Saturday

WaitTime=Mo/We/Fr@10:00 specifies Monday, Wednesday, or Friday at 10:00 AM local time, whichever comes next.

To use the above command to activate a recurring task, put it at the start of a master macro that performs the entire task or series of tasks. For example, suppose it is called DoTasksMWF and performs Task1 and Task2:

  WaitTime=Mo/We/Fr@10:00
  @Task1
  @Task2

Now invoke DoTasksMWF in a loop, typically from the ' !' auto-run macro:

  @DoTasksMWF=5G

5G is an easy way to enter the biggest possible value. Daqarta will limit it to 2^32 - 1 or 4294967295, which at 3 times a week will run for 27.5 million years.

You can use multiple WaitTime commands to run different tests at different times on the same day. In the above example, Test1 will run at 10:00 AM. If you want Test2 to run at 1:00 PM you would precede it with WaitTime=@1:00P. This will run at the next 1:00 PM after it is called, so you must make sure Test1 has completed before that time, or Test2 will run at 1:00 PM on the following day. This principle applies to all such recurring times; for example, WaitTime=@H:M:S: requires that the preceding task take well under one second.

Suppose you want Task1 to run as above at 10:00 AM on Monday, Wednesday, and Friday, and Task2 at 1 PM on Tuesday and Thursday. As a first attempt, you might be inclined to try:

  WaitTime=Mo/We/Fr@10:00
  @Task1
  WaitTime=Tu/Th@1:00P
  @Task2

This will work fine until Friday; after Task1 finishes, the next day that WaitTime=Tu/Th@1:00P will run is the following Tuesday, and by then Monday's Task1 will have been skipped. One way to avoid this problem is:

  WaitTime=Mo@10:00
  @Task1
  WaitTime=Tu@1:00P
  @Task2
  WaitTime=We@10:00
  @Task1
  WaitTime=Th@1:00P
  @Task2
  WaitTime=Fr@1:00P
  @Task1

WaitCyclic0-9:

There are 10 independent WaitCyclic timers, WaitCyclic0 through WaitCyclic9. Like WaitSecs, each can accept entries in seconds or H:M:S format, and is limited to a cycle of just over 1193 hrs or 49.7 days.

For tasks that must be repeated at standard unit intervals like each month, week, day, hour, minute, or second, the preceding WaitTime command is ideal. But there is no way to use it to repeat a task every 15 minutes for an hour, for example. Depending on the task and the required resolution, you might use WaitSecs=15:00 to delay for 15 minutes between each repetition. But that assumes that the task itself takes no time to complete; in reality, the schedule would slip farther and farther behind.

WaitCyclic0=15:00, on the other hand, will repeat each 15 minutes, regardless of how long the task takes, as long as it takes somewhat less than 15 minutes. Typically, you would put this at the start of the macro that performs the test, and call that macro in a loop. Suppose the macro is called TestQuarter and defined as:

  WaitCyclic0=15:00  ;Wait for next 15-minute mark
  @MyTest            ;Do test

Now we call it in a loop, here preceded by WaitTime so that the test sequence begins at noon:

  WaitTime=@12:00    ;Wait for noon
  @TestQuarter=5     ;Run 5 times, 12:00-1:00 PM
  WaitCyclic0=0      ;Stop timer when done

The first time TestQuarter is called, WaitCyclic0=15:00 sets a repeating interval timer for a 15 minute cycle and then runs MyTest immediately. That is the end of the first pass through TestQuarter.

On the next pass, WaitCyclic0=15:00 checks that the specified interval is unchanged from the last time it was called. If it is the same, as in this example, that means the interval timer is running, so macro processing is suspended until the current 15 minute cycle ends. Then MyTest is run again, and the loop repeats.

Since the first pass through TestQuarter was at noon, MyTest runs at 12:00, 12:15, 12:30, 12:45, and 1:00 PM.

That timing results from the fact that the WaitCyclic0 timers doesn't wait the first time it is called, just sets the timer for the next pass. If, on the other hand, you want it to wait on the first pass, put a ' W' before the time value, as in WaitCyclic0=W15:00. That will result in MyTest being run at 12:15, 12:30, 12:45, 1:00, and 1:15 PM.

Note that you should always stop a WaitCyclic timer when you are done using it, by setting its interval to 0. Not only does this prevent needless timer service interrupts, it also insures that the next time you use that timer you start fresh without a delay (assuming no ' W') if the next interval is the same.

On the other hand, if you want a subsequent test series to continue on the same interval schedule as the first, omit the reset until you are completely done with that schedule.

The avalability of 10 independent WaitCyclic timers allows construction of very complex timing schedules. These can be combined with recurring WaitTime intervals (as in the example above that waits for noon).

In general, WaitTime will give slightly greater accuracy over long periods composed of many short intervals, because it has higher initial resolution, and because it does not accumulate small errors like WaitCyclic can. The difference is like keeping time with a clock versus a stopwatch:

In this case the WaitTime "clock" has a high long-term accuracy, typically similar to a good digital watch, but the same as an "atomic" clock on systems that are connected to the internet regularly and have the "Internet Time" option set in Windows. Note, however, that any individual reading may be off by 10-15 msec (more on Win9x).

The WaitCyclic "stopwatch" has the same 10-15 msec resolution on each interval it times, not only for reading it but also for setting it as well. If you set a cycle of 1 minute and it is really 10 msec greater, that's an error of 0.0167 percent; not significant for most uses. But if you put it in a loop to count minutes, it will be off by 1 second after only 100 minutes.

Another difference between WaitTime and WaitCyclic is that the WaitTime clock is maintained between sessions, even when your computer is turned off. The WaitCyclic intervals must be re-synchronized each session (and preferably at each use), if you want intervals to start at particular clock times.