Scans a range of A/D channels and stores the samples in an array. cbAInScan() 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.
C/C++
int cbAInScan(int BoardNum, int LowChan, int HighChan, long Count, long *Rate, int Range, int MemHandle, int Options)
Visual Basic
Function cbAInScan(ByVal BoardNum&, ByVal LowChan&, ByVal HighChan&, ByVal Count&, 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.
LowChan
The first A/D channel in the scan. When cbALoadQueue() is used, the channel count is determined by the total number of entries in the channel gain queue, and LowChan is ignored.
HighChan
The last A/D channel in the scan. When cbALoadQueue() is used, the channel count is determined by the total number of entries in the channel gain queue, and HighChan is ignored.
Low / High Channel number: 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 CIO-DAS1600 has 8 channels for differential, 16 for single ended.
Count
The number of A/D samples to collect. Specifies the total number of A/D samples that will be collected. If more than one channel is being sampled, 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, if you sample four channels, 0 to 3, at a rate of 10,000 scans per second (10 kHz), the resulting A/D converter rate is 40 kHz: four channels at 10,000 samples per channel per second. This is different from some software where 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 cbALoadQueue 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 argument is ignored. Otherwise, set the Range argument 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 cbWinBufAlloc(). For data that is >16-bit and ≤32-bit, use cbWinBufAlloc32(). For data that is >32-bit and ≤64-bit, use cbWinBufAlloc64(). When using scaled data, use cbScaledWinBufAlloc().
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.
| Transfer method options | The following four options 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 method.
|
| BACKGROUND | If the BACKGROUND option is not used then the cbAInScan() 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 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 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. cbStopBackground() should be executed after normal termination of all background functions 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 in order to minimize channel to channel skew. Scans are initiated at the rate specified by the Rate argument. 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 cbAPreTrig() function). Only the former case applies for cbAInScan(). 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 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. |
| CONTINUOUS | This option puts the function 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 cbStopBackground(). Normally this option should be used in combination with BACKGROUND so that your program will regain control. Count argument settings in CONTINUOUS mode: For some DAQ hardware, Count 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 Count argument 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 Count value is that the buffer in memory must be periodically transferred to the user buffer. If the buffer is too small, data will be 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 Universal Library. |
| EXTCLOCK | If this option is used, 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 in the Universal Library User's Guide). In most cases, when this option is used the Rate argument 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 argument 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. The reason for this is that 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 function will be appended unless cbMemReset() is called. The data should be unloaded with the cbMemRead() function before collecting new data. When EXTMEMORY option is used, the MemHandle argument can 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, BLOCKIO and BURSTIO 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 the cbSetTrigger() function and board-specific information for details) and can be programmed for rising or falling edge or an analog level.
On other boards, only 'polled gate' triggering is supported. In this case, 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 unit it goes high. Acquisition continues until Count samples are taken, regardless of the state of the trigger input. For "polled gate" triggering, 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 argument above). |
| NOCALIBRATEDATA | Turns off real-time software calibration for boards which are software calibrated. This is done 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 cbACalibrateData() function. |
| NOTODINTS | If this option is specified, the system's time-of-day interrupts are disabled 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 cbStopBackground() is called.
You can specify the number of samples to acquire with each trigger event. This is the trigger count. Use the cbSetConfig() ConfigItem option BIADTRIGCOUNT to set the trigger count. If you specify a trigger count that is either zero or greater than the value of the cbAInScan() Count argument, the trigger count will be set to the value of the Count argument. Specify the CONTINUOUS option with the trigger count set to zero to fill the buffer with Count 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 cbScaledWinBufAlloc().
Results using SCALEDATA may be slightly different from results using cbToEngUnits() 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 cbToEngUnits(). |
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 found in the Universal Library User's Guide. The example programs should be examined and run prior to attempting any programming of your own. 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. Now is the time to read the board specific information for your board that is contained in the Universal Library User's Guide. We suggest that you make a copy of this information for reference as you read this manual and examine the example programs.