Data AcQuisition And Real-Time AnalysisScope - Spectrum - Spectrogram - Signal Generator
Software for Windows
Science with your Sound Card!
Contact us about
Sound Card Event Wait Macros
Macros: WaitKey, WaitPause, WaitAvg, WaitChange, WaitTrace
WaitKey="a" will cause macro execution to halt until the user hits the 'a' key. You may substitute any displayable alphanumeric or symbol key (including spaces), but not shift keys, function keys, Tab, Enter, Backspace, or other control characters.
The specified key is ignored during text or control value entry.
Key values are case sensitive, so WaitKey="A" will wait for 'A' and will ignore 'a'. Allowable characters run from ASCII value 32 (space) to 126 (tilde ~). You'll need to use the ASCII value to enter the " double quote character 34, as in WaitKey=34.
This command is especially useful for debugging macros containing loops. You insert a Msg statement to show relevant values, followed by a WaitKey statement to allow you to examine them. That way you can step through the loop one entire pass at a time, rather than one macro command at a time with the Macro Step button. The WaitKey method is also simpler and much more efficient than a polling loop using the Key? macro.
Alternatively, if you use WaitKey with any value higher than 126 it will wait for any displayable key, as well as Enter (13), TAB (9), or Backspace (8). You can then read the actual key using Key?#. This can be used to efficiently wait for a key, but with different actions depending on the key hit.
The _Get_String macro subroutine uses WaitKey to acquire a string from the user, displayed character by character, until the Enter key is received. Note that this subroutine uses MsgStyle=TCx before beginning the WaitKey loop. This prevents the message display from showing an [X] in the title bar, which might otherwise allow the user to inadvertently cancel the display while the macro is still waiting for characters.
Normally, macro commands are processed one after the other as fast as possible. That's ideal for setting up a test, but it's often less than ideal when actually collecting and saving data. The problem is that data collection takes a finite amount of time; if, for example, you use Gen=1 to begin stimulus generation and Input=1 to begin acquiring input data, when do you give SaveDQA to save it? You need to wait until data has been acquired and is ready to be saved.
One way to do that is by using Single Trigger mode with Pause=0 to unPause and wait for a trigger, followed by WaitPause=1. At this point the macro halts and waits until the trigger event causes Single to enter Pause mode. Then the macro proceeds to save the data.
Alternatively, you can set the Averager Frames Request to 1 (WavgFrames=1 or SpavgFrames=1) and start an average with Avg=1 before giving WaitPause=1. The next trace will satisfy the Frames Request, the averager will Pause, and macro processing will proceed. You can use any Trigger mode, or no triggering at all. (You could use WaitAvg instead of WaitPause... see below.)
You can also use WaitPause=1 in untriggered or non-Single triggered modes to allow the operator to specify when to save the data by manually hitting Pause. (Another way to do this is to have one macro that starts the test, and another that saves the data when the operator runs that macro.)
WaitPause=0 does the opposite: It suspends macro processing until unPause.
If the data to be acquired is in the form of a waveform or spectrum average, you could start the average (without Single) with Avg=1 and then give WaitPause=1. Macro command processing will be suspended, and the average will proceed until the requested number of Frames are averaged, which automatically invokes Pause mode. That will cause macro processing to resume, allowing you to save the data to a file.
But suppose the operator wants to manually Pause the average midway, and unPause after a noisy truck passes by. WaitPause doesn't distinguish between a Pause due to the average completing and a manual Pause.
WaitAvg, on the other hand, completely ignores Pause and waits only for the requested number of frames before proceeding. The average can thus be paused and resumed as many times as needed without affecting the macro operation.
A typical use would be:
Avg=1 ;Start the average WaitAvg= ;Wait until done A.SaveDQA="AvgData" ;Save the file
Note that WaitAvg= is given here without anything after the = sign. This simply activates the Macro Halt state until the average is done.
Some experiments need a variable amount of averaging, which an operator can judge by eye. The Frames Request can be set fairly high, and the operator can Pause the average when the result is acceptable. But if WaitAvg is waiting for the requested frames, the macro doesn't resume processing to save the data to a file (for example).
Instead, you can supply message text with WaitAvg, such as:
Avg=1 ;Start the average WaitAvg="Average IN PROGRESS. Click [x] to end." ;Shows during average Pause=1 ;Stop the average Msg= ;Clear the message A.SaveDQA="AvgData" ;Save the file
When the message box is closed, it also causes macro processing to resume. The Pause=1 command is needed to stop the average; it is redundant if the average ran to completion.
Similarly, it may sometimes be necessary to abort an average. Manually toggling it off during WaitAvg will again prevent the requested frames from being reached, so the macro will remain suspended. Instead, cancelling the WaitAvg message will result in the average being saved, even if it is unwanted.
Alternatively, you can click on the Cancel button in the macro dialog to abort the macro entirely, which may require opening the dialog (CTRL+F8) if it isn't already open.
WaitAvg is best used for highly automated data acquisition, where operator intervention is rarely needed. If the operator will be present anyway, a better approach may be to have a series of separate macros to be run. One starts the average, and a separate macro pauses it (if not at completion) and saves the file.
This approach gives the operator much more control, but still allows a large degree of automation. Further, by doing everything with macro commands (with descriptions as well as descriptive names), even a novice operator can run a complex test.
For use with Remote Control software, WaitAvg=>> (with no message text) will send a 'Done' message with the total Frames count when the average completes. See Custom Remote Control for more information.
WaitChange=Field5 halts macro processing until the specified Label or Field is changed. This can be used to require an operator to enter necessary information before a test begins. (It does nothing to validate the information, but it does prevent it being skipped.)
Having the name or ID number of the device, animal, or subject being tested allows later macro commands to use that as a file name for saving the acquired test data. See Example - File Name Auto-Increment under Macro Variables for details.
This same macro command has two entirely different uses.
WaitTrace= with no value given causes a running macro to halt until the next trace update. It can be used to allow simple synchronizing of macro and trace operations.
It could also be used in a long loop calculation to prevent it from blocking trace updates.
WaitTrace#N=X is a variant of the above that waits for X trace updates. Values of X may be any integer from 1 to 1000. This command can be used as a delay that also synchronizes with updates. The delay between the time the command is given and the first trace update is variable, and may be as much as the Trace Update Interval; after that the delay will be X-1 Trace Update Intervals. (This assumes that the actual trace update time is less than the Trace Update Interval; that may not be true for low settings and complex "busy" traces.)
A completely different use is WaitTrace=N, where N is any integer between 1 and 10000. This sets a "dead-man switch" that detects if a macro has run longer than N milliseconds without allowing a trace update, and inserts one if so. This not only prevents the screen from freezing, but also enables the Cancel button to abort the macro if it is stuck in a loop, for example. (Without this command, the automatic default limit is 100 msec.)
Questions? Comments? Contact us!We respond to ALL inquiries, typically within 24 hrs.
Over 35 Years of Innovative Instrumentation
© Copyright 2007 - 2023 by Interstellar Research
All rights reserved