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 user's manual for the board) 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 the cbSetTrigger() function for more details.
C/C++
int cbAPretrig(int BoardNum, int LowChan, int HighChan, long *PretrigCount, long *TotalCount, long *Rate, int Range, int MemHandle, int Options)
Visual Basic
Function cbAPretrig(ByVal BoardNum&, ByVal LowChan&, ByVal HighChan&, PretrigCount&, TotalCount&, Rate&, ByVal Range&, ByVal MemHandle&, ByVal Options&) As Long
BoardNum
The number associated with the board when it was installed with InstaCal or created with cbCreateDaqDevice(). BoardNum may be 0 to 99. The board must have an A/D.
LowChan
First A/D channel of scan.
HighChan
Last A/D channel of scan.
LowChan/HighChan: The maximum allowable channel depends on which type of A/D board is being used. When a board has both single ended and differential inputs, the maximum allowable channel number also depends on how the board is configured (such as 8 channels for DIFF inputs, and 16 channels for SE inputs).
PretrigCount
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 pretrigger (most products), PretrigCount must be less than (TotalCount – 512). For these devices, if the trigger occurs too early, fewer than the requested number of pre-trigger samples will be collected, and a TOOFEW error will occur. The PretrigCount will be set to indicate how many samples were actually collected. The post trigger samples will still be collected.
For software implementations of pretrigger, PretrigCount must be less than TotalCount. For these devices, triggers that occur before the requested number of pre-trigger samples are collected are ignored. See board-specific information contained in the UL Users Guide for details.
TotalCount
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 pretrigger (most products), TotalCount must be greater than or equal to the PretrigCount + 512. If the trigger occurs too early, fewer than the requested number of samples will be collected, and a TOOFEW error will occur. The TotalCount will be set to indicate how many samples were actually collected.
For software implementations of pretrigger, TotalCount must be greater than PretrigCount. For these devices, triggers that occur before the requested number of pre-trigger samples are collected are ignored. See board-specific information.
TotalCount 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 and return that value to the TotalCount argument.
PretrigCount must also 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 and return that value to the PretrigCount argument.
Rate
Sample rate in scans per second.
Range
A/D Range code. If the selected A/D board does not have a programmable gain feature, this argument is ignored. Otherwise, set to any range that is supported by the selected A/D board. Refer to board specific information for a list of the supported A/D ranges of each board.
MemHandle
Handle for Windows buffer to store data. This buffer must have been previously allocated with the cbWinBufAlloc() function.
For hardware trigger types, the buffer referenced by MemHandle must be big enough to hold at least TotalCount + 512 integers.
Options
Bit fields that control various options. This field may contain any combination of non-contradictory choices from the values listed in the Options argument values section below.
| BACKGROUND | If the BACKGROUND option is not used, the cbAPretrig() 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 cbGetStatus() with AIFUNCTION to check on the status of the background operation. Alternatively, some boards support cbEnableEvent() for event notification of changes in status of BACKGROUND scans. Use cbStopBackground() with AIFUNCTION to terminate the background process before it has completed. Call cbStopBackground() after normal termination of all background functions to clear variables and flags. For hardware trigger types, you cannot use the CONVERTDATA option in combination with the BACKGROUND option for this function. To correctly order and parse the data, use cbAConvertPretrigData() after the function completes |
| CONVERTDATA | For hardware trigger types, the data is collected into a "circular" buffer. The CONVERTDATA option is used to align data within the buffer when the data acquisition is complete. This option is ignored for all 16-bit devices, and for 12-bit devices that store the data without an offset (refer to cbAInScan()). Note that you can also call cbAConvertPretrigData() to align data within the buffer when the data acquisition is complete. Use of CONVERTDATA is recommended unless one of the following two conditions exist: 1) On some devices, CONVERTDATA may not be specified if you are using the BACKGROUND option and DMA transfers. In this case, if data conversion is required, use cbAConvertData() to re-align the data. 2) Some 12-bit boards store the data as a 12-bit A/D value and a 4-bit channel number. Using CONVERTDATA will strip out the channel number from the data. If you prefer to store the channel number as well as the data, call cbAConvertData() to retrieve the data and the channel number from the buffer after the data acquisition to the buffer is complete. The CONVERTDATA option is not required for software triggered types. |
| 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. |
| EXTMEMORY | Causes this function to send the data to a connected memory board via the DT-Connect interface rather than returning the data to the buffer. If you use this option to send the data to a MEGA-FIFO memory board, then you must use cbMemReadPretrig() to later read the pre-trigger data from the memory board. If you use cbMemRead(), the data will NOT be in the correct order. Every time this option is used, it overwrites any data already stored in the memory board. All data should be read from the board (with cbMemReadPretrig()) before collecting any new data. When this option is used, the MemHandle argument is ignored. The MEGA-FIFO memory must be fully populated in order to use the cbAPretrig() function with the EXTMEMORY option. |
| DTCONNECT | When DTCONNECT option is used with this function, the data from ALL A/D conversions is sent out the DT-Connect interface. While this function is waiting for a trigger to occur, it will send data out the DT-Connect interface continuously. If you have a Measurement Computing memory board plugged into the DT-Connect interface then you should use EXTMEMORY option rather than this option. |
For hardware trigger types, the buffer referenced by MemHandle must be big enough to hold at least TotalCount + 512 integers.