Waits for a trigger to occur and then returns a specified number of analog samples before and after the trigger occurred.
If only 'polled gate' triggering is supported, the trigger input line (refer to the device user manual) must be at TTL low before this function is called, or a TRIGSTATE error will occur. The trigger occurs when the trigger condition is met. Refer to set_trigger() for more details.
a_pretrig(board_num, low_chan, high_chan, pretrig_count, total_count, rate, ul_range, memhandle, options)
board_num (int)
The number associated with the board when it was installed with InstaCal or created with create_daq_device().
low_chan (int)
First D/A channel of scan.
high_chan (int)
Last D/A channel of scan.
pretrig_count (int)
Number of pre-trigger A/D samples to collect. Specifies the number of samples to collect before the trigger occurs.
For products using a hardware implementation of pre-trigger (most products), pretrig_count must be less than (total_count – 512). For these devices, if the trigger occurs too early, fewer than the requested number of pre-trigger samples will be collected, an ErrorCode.TOOFEW value will be returned as the first return value. The second return value will indicate how many samples were actually collected. The post trigger samples will still be collected.
For software implementations of pre-trigger, pretrig_count must be less than total_count. For these devices, triggers that occur before the requested number of pre-trigger samples are collected are ignored; refer to board-specific information for details.
pretrig_count must be evenly divisible by the number of channels being scanned. If it is not, this function will adjust the number (up) to the next valid value. The return value actual_pretrig_count will contain the new value.
total_count (int)
Total number of A/D samples to collect. Specifies the total number of samples that will be collected and stored in the buffer.
For products using a hardware implementation of pre-trigger (most products), total_count must be greater than or equal to the pretrig_count + 512. If the trigger occurs too early, fewer than the requested number of samples will be collected, and an ErrorCode.TOOFEW value will be returned as the first value. The third return value will indicate how many samples were actually collected.
For software implementations of pre-trigger, total_count must be greater than pretrig_count. For these devices, triggers that occur before the requested number of pre-trigger samples are collected are ignored; refer to board-specific information for details.
total_count must be evenly divisible by the number of channels being scanned. If it is not, this function will adjust the number (down) to the next valid value. The return value actual_total_count will contain the new value.
rate (int)
Sample rate in scans per second. The actual sampling rate in some cases will vary a small amount from the requested rate. The actual rate is returned in the actual_rate return value.
ul_range (ULRange)
A/D Range code. If the selected A/D board does not have a programmable gain feature, this parameter is ignored. Otherwise, set to any range that is supported by the board.
memhandle (int)
Handle for Windows buffer to store data. This buffer must have been previously allocated with win_buf_alloc().
For hardware trigger types, the buffer referenced by MemHandle must be big enough to hold at least total_count + 512 integers.
options (ScanOptions)
Flags that control various options. May contain any combination of non-contradictory choices in the options parameter values table below.
| BACKGROUND | If the BACKGROUND option is not used, the a_pretrig() function will not return to your program until all of the requested data has been collected and returned to the buffer. When the BACKGROUND option is used, control returns immediately to the next line in your program, and the data collection from the A/D into the buffer will continue in the background. Use get_status() with AIFUNCTION to check on the status of the background operation. Alternatively, some boards support enable_event() for event notification of changes in status of BACKGROUND scans. Use stop_background() with AIFUNCTION to terminate the background process before it has completed. Call stop_background() after normal termination of all background functions to clear variables and flags. |
| EXTCLOCK | This option is available only for boards that have separate inputs for external pacer and external trigger. See your hardware manual or board-specific information. |
For hardware trigger types, the buffer referenced by MemHandle must be big enough to hold at least total_count + 512 integers.