Scans a range of A/D channels and stores the samples in an array. AInScan() reads the specified number of A/D samples at the specified sampling rate from the specified range of A/D channels from the specified board. If the A/D board has programmable gain, then it sets the gain to the specified range. The collected data is returned to the data array.
Member of the MccBoard class.
VB .NET
Public Function AInScan(ByVal lowChan As Integer, ByVal highChan As Integer, ByVal numPoints As Integer, ByRef rate As Integer, ByVal range As MccDaq.Range, ByVal memHandle As IntPtr, ByVal options As MccDaq.ScanOptions) As MccDaq.ErrorInfo
C# .NET
public MccDaq.ErrorInfo AInScan(int lowChan, int highChan, int numPoints,ref int rate, MccDaq.Range range, IntPtr memHandle, MccDaq.ScanOptions options)
The following methods are deprecated, and should only be used for legacy applications. The methods above are preferred, and must be used for 64-bit application development.
VB .NET
Public Function AInScan(ByVal lowChan As Integer, ByVal highChan As Integer, ByVal numPoints As Integer, ByRef rate As Integer, ByVal range As MccDaq.Range, ByVal memHandle As Integer, ByVal options As MccDaq.ScanOptions) As MccDaq.ErrorInfo
C# .NET
public MccDaq.ErrorInfo AInScan(int lowChan, int highChan, int numPoints, ref int rate, MccDaq.Range range, int memHandle, MccDaq.ScanOptions options)
lowChan
First A/D channel of the scan. When ALoadQueue() is used, the channel count is determined by the total number of entries in the channel gain queue. lowChan is ignored.
highChan
Last A/D channel of the scan. When ALoadQueue() is used, the channel count is determined by the total number of entries in the channel gain queue. highChan is ignored.
low / high Channel # - The maximum allowable channel depends on which type of A/D board is being used. For boards that have both single ended and differential inputs the maximum allowable channel number also depends on how the board is configured. For example, a USB-1208FS has four channels for differential, eight for single-ended.
numPoints
Number of A/D samples to collect. Specifies the total number of A/D samples to collect. If more than one channel is being sampled, then the number of samples collected per channel is equal to count ÷ (highChan – lowChan + 1).
rate
The rate at which samples are acquired, in samples per second per channel.
For example, sampling four channels, 0-3, at a rate of 10,000 scans per second (10 kilohertz (kHz)) results in an A/D converter rate of 40 kHz: four channels at 10,000 samples per channel per second. With other software, you specify the total A/D chip rate. In those systems, the per channel rate is equal to the A/D rate divided by the number of channels in a scan.
The channel count is determined by the lowChan and highChan parameters. Channel Count = (highChan - lowChan + 1).
When ALoadQueue() is used, the channel count is determined by the total number of entries in the channel gain queue. lowChan and highChan are ignored.
rate also returns the value of the actual rate set, which may be different from the requested rate because of pacer limitations.
range
A/D range code. If the selected A/D board does not have a programmable range feature, this parameter is ignored. Otherwise, set the range parameter 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 the Windows buffer to store data. This buffer must have been previously allocated. For 16-bit data, create the buffer with WinBufAllocEx(). For data that is >16-bit and ≤32-bit, use WinBufAlloc32Ex(). For data that is >32-bit and ≤64-bit, use WinBufAlloc64Ex(). When using scaled data, use ScaledWinBufAllocEx().
options
Bit fields that control various options. Refer to the constants in the "options parameter values" section below.
All of the options settings are MccDaq.ScanOptions enumerated constants. To set a variable to one of these constants, you must refer to the MccDaq object and the ScanOptions enumeration (variable = MccDaq.ScanOptions.SingleIo, variable = MccDaq.ScanOptions.DmaIo, etc.).
| Data transfer modes | The following four mode determine how data is transferred from the board to PC memory. If none of these options are specified (recommended), the optimum sampling mode is automatically chosen based on board type and sampling speed. Use the default method unless you have a reason to select a specific transfer mode.
|
| Background | If the Background option is not used, the AInScan() method will not return control to your program until all of the requested data has been collected and returned to the buffer. When the Background option is used, control will return 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 GetStatus() with AiFunction to check on the status of the background operation. Alternatively, some boards support EnableEvent() for event notification of changes in status of Background scans. Use StopBackground() with AiFunction to stop the background process before it has completed. StopBackground() should be executed after normal termination of all background methods in order to clear variables and flags. |
| BurstMode | Enables burst mode sampling. Scans from lowChan to highChan are clocked at the maximum A/D rate between samples in order to minimize channel to channel skew. Scans are initiated at the rate specified by the rate parameter.
BurstMode is not recommended for use with the SingleIo option. If this combination is used, the count value should be set as low as possible, preferably to the number of channels in the scan. Otherwise, overruns may occur. |
| ConvertData | This option is used to align data, either within each byte (in the case of some 12-bit devices) or within the buffer (see the APreTrig() method). Only the former case applies for AInScan. The data stored on some 12-bit devices is offset in the devices data register. For these devices, the ConvertData option converts the data to 12-bit A/D values by shifting the data to the first 12 bits within the byte. For devices that store the data without an offset and for all 16-bit devices, this option is ignored.
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 AConvertData() 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 AConvertData() to retrieve the data and the channel number from the buffer after the data acquisition to the buffer is complete. |
| Continuous | This option puts the method in an endless loop. Once it collects the required number of samples, it resets to the start of the buffer and begins again. The only way to stop this operation is with StopBackground(). Normally this option should be used in combination with Background so that your program will regain control.
numPoints parameter settings in Continuous mode: For some DAQ hardware, numPoints must be an integer multiple of the packet size. Packet size is the amount of data that a DAQ device transmits back to the PC's memory buffer during each data transfer. Packet size can differ among DAQ hardware, and can even differ on the same DAQ product depending on the transfer method. In some cases, the minimum value for the numPoints parameter may change when the Continuous option is used. This can occur for several reasons; the most common is that in order to trigger an interrupt on boards with FIFOs, the circular buffer must occupy at least half the FIFO. Typical half-FIFO sizes are 256, 512 and 1,024. Another reason for a minimum numPoints value is that the buffer in memory must be periodically transferred to the user buffer. If the buffer is too small, data is overwritten during the transfer resulting in garbled data. Refer to board-specific information in the Universal Library User's Guide for packet size information for your particular DAQ hardware. |
| DTConnect | All A/D values will be sent to the A/D board's DT-Connect port. This option is incorporated into the ExtMemory option. Use DTConnect only if the external board is not supported by the Universal Library. |
| ExtClock | If this option is used then conversions will be controlled by the signal on the external clock input rather than by the internal pacer clock. Each conversion will be triggered on the appropriate edge of the clock input signal (refer to the board-specific information contained in the Universal Library User's Guide). In most cases, when this option is used the rate parameter is ignored. The sampling rate is dependent on the clock signal. Options for the board will default to a transfer mode that will allow the maximum conversion rate to be attained unless otherwise specified.
In some cases, such as with the PCI-DAS4020/12, an approximation of the rate is used to determine the size of the packets to transfer from the board. Set the rate parameter to an approximate maximum value. SingleIo is recommended for slow external clock rates: If the rate of the external clock is very slow (for example less than 200 Hz) and the board you are using supports BlockIo, you may want to include the SingleIo option. This is because the status for the operation is not available until one packet of data has been collected (typically 512 samples). The implication is that, if acquiring 100 samples at 100 Hz using BlockIo (the default for boards that support it if ExtClock is used), the operation will not complete until 5.12 seconds has elapsed. |
| ExtMemory | Causes the command to send the data to a connected memory board via the DT-Connect interface rather than returning the data to the buffer. Data for each call to this method will be appended unless MemReset() is called. The data should be unloaded with the MemRead() method before collecting new data. When ExtMemory option is used, the reference to the buffer (memHandle) may be set to null or 0. Continuous option cannot be used with ExtMemory. Do not use ExtMemory and DtConnect together. The transfer modes DmaIo, SingleIo and BlockIo have no meaning when used with this option. |
| ExtTrigger | If this option is specified, the sampling will not begin until the trigger condition is met. On many boards, this trigger condition is programmable (refer to SetTrigger() and to board-specific info for details). On other boards, only 'polled gate' triggering is supported. Assuming active high operation, data acquisition will commence immediately if the trigger input is high. If the trigger input is low, acquisition will be held off until it goes high, and then continue until numPoints samples are taken, regardless of the state of the trigger input.
This option is most useful if the signal is a pulse with a very low duty cycle (trigger signal in TTL low state most of the time) so that triggering will be held off until the occurrence of the pulse. |
| HighResRate | Acquires data at a high resolution rate. When specified, the rate at which samples are acquired is in "samples per 1000 seconds per channel". When this option is not specified, the rate at which samples are acquired is in "samples per second per channel" (refer to the rate parameter above). |
| NoCalibrateData | Turns off real-time software calibration for boards which are software calibrated, by applying calibration factors to the data on a sample by sample basis as it is acquired. Examples are the PCM-DAS16/330 and PCM-DAS16x/12.
Turning off software calibration saves CPU time during a high speed acquisition run. This may be required if your processor is less than a 150 MHz Pentium and you desire an acquisition speed in excess of 200 kHz. These numbers may not apply to your system. Only trial will tell for sure. DO NOT use this option if you do not have to. If this option is used, the data must be calibrated after the acquisition run with the ACalibrateData() method. |
| NoToDints | Disables the system's time-of-day interrupts for the duration of the scan. These interrupts are used to update the systems real time clock and are also used by various other programs.
These interrupts can limit the maximum sampling speed of some boards - particularly the PCM-DAS08. If the interrupts are turned off using this option, the real-time clock will fall behind by the length of time that the scan takes. |
| RetrigMode | Re-arms the trigger after a trigger event is performed. With this mode, the scan begins when a trigger event occurs. When the scan completes, the trigger is re-armed to acquire the next the batch
of data. You can specify the number of samples in the scan for each trigger event (described below). The RetrigMode option can be used with the Continuous option to continue arming the trigger until StopBackground() is called.
You can specify the number of samples to acquire with each trigger event. This is the trigger count (retrigCount). Use SetAdRetrigCount() to set the trigger count. If you specify a trigger count that is either zero or greater than the value of the AInScan() numPoints parameter, the trigger count is set to the value of numPoints. Specify the Continuous option with the trigger count set to zero to fill the buffer with numPoints samples, re-arm the trigger, and refill the buffer upon the next trigger. |
| ScaleData | Converts raw scan data — to voltage, temperature, and so on, depending upon the selected channel sensor category — during the analog input scan, and puts the scaled data directly into the user buffer. The user buffer should have been allocated with ScaledWinBufAllocEx().
Results using ScaleData may be slightly different from results using ToEngUnits() near range limits, due to the nature of the calibration being applied and the internal calculation using floating count values. If this is undesirable use ToEngUnits(). |
You will generate an error if you specify a total A/D rate beyond the capability of the board. For example, if you specify LowChan = 0, HighChan = 7 (8 channels total), and Rate = 20,000, and you are using a CIO-DAS16/JR, you will get an error – you have specified a total rate of 8*20,000 = 160,000, but the CIO-DAS16/JR is capable of converting only 120,000 samples per second.
The maximum sampling rate depends on the A/D board that is being used. It is also dependent on the sampling mode options.
In order to understand the functions, you must read the board-specific information contained in the in the Universal Library User's Guide. Examine and run the example programs before attempting your own program. Following this advice will save you hours of frustration, and possibly time wasted holding for technical support.
This note, which appears elsewhere, is especially applicable to this function. Refer to the board-specific information for your hardware in the Universal Library User's Guide. We suggest that you make a copy of that page for reference as you read this manual and examine the example programs.