Scans a range of A/D channels and stores the samples in an array. a_in_scan() 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.
a_in_scan(board_num, low_chan, high_chan, num_points, 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)
The first A/D channel in the scan. When a_load_queue() is used, the channel count is determined by the total number of entries in the channel gain queue, and low_chan is ignored.
high_chan (int)
The last A/D channel in the scan. When a_load_queue() is used, the channel count is determined by the total number of entries in the channel gain queue, and high_chan is ignored.
num_points (int)
The total number of A/D samples to collect. If more than one channel is being sampled, the number of samples collected per channel is equal to count / (high_chan – low_chan + 1).
rate (int)
The rate at which samples are acquired, in samples per second per channel.
For example, sampling four channels, 0 to 3, at a rate of 10,000 scans per second (10 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 actual sampling rate in some cases will vary a small amount from the requested rate. The actual rate is returned.
The channel count is determined by the low_chan and high_chan parameters. Channel Count=(high_chan - low_chan + 1).
When a_load_queue() is used, the channel count is determined by the total number of entries in the channel gain queue. low_chan and high_chan are ignored.
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 selected A/D board.
mem_handle (int)
Handle for the Windows buffer to store data. This buffer must have been previously allocated. For 16-bit data, create the buffer with win_buf_alloc(). For data that is > 16-bit and ≤ 32-bit, use win_buf_alloc_32() . For data that is > 32-bit and ≤ 64-bit, use win_buf_alloc_64(). When using scaled data, use scaled_win_buf_alloc().
options (ScanOptions)
Flags that control various options. May contain any combination of non-contradictory choices in the options parameter values table 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 a_in_scan() 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 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. stop_background() 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 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 a_pretrig() function). Only the former case applies for a_in_scan(). 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 a_convert_pretrig_data() 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 stop_background(). Normally this option should be used in combination with BACKGROUND so that your program will regain control. count parameter 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 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 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 for packet size information for your particular DAQ hardware. |
| 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 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, 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, since the operation status is not available until one packet of data is collected –typically 512 samples). The implication is that when acquiring 100 samples at 100 Hz using BLOCKIO (the default for boards supporting EXTCLOCK), the operation will not complete until 5.12 seconds has elapsed. |
| 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 and can be programmed for rising or falling edge or an analog level; refer to set_trigger() and board-specific information for details.
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 will then continue until NumPoints& samples have been 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 above to rate). |
| 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. 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 more than 200 kHz; the speed of your system may vary. DO NOT use this option if you do not have to. |
| 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 stop_background() is called.
You can specify the number of samples to acquire with each trigger event. This is the trigger count. Use the set_config() config_item option BIADTRIGCOUNT to set the trigger count. If you specify a trigger count that is either zero or greater than the value of the a_in_scan() count parameter, the trigger count is set to the value of the count parameter. Specify the CONTINUOUS option with the trigger count set to zero to fill the buffer with num_points 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 scaled_win_buf_alloc().
Results using SCALEDATA may be slightly different from results using to_eng_units() 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 to_eng_units(). |
You will generate an error if you specify a total A/D rate beyond the capability of the board. The maximum sampling rate depends on the A/D board that is being used and on the sampling mode options.
In order to understand the functions, you must read the board-specific information. 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 review board-specific information. We suggest that you copy board-specific information to reference as you read this manual and examine the example programs.