# a_in_scan()

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.

## Prototype

a_in_scan(board_num, low_chan, high_chan, num_points, rate, ul_range, memhandle, options)

## Parameters

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.

## Returns

- The actual rate set, which may be different from the requested rate because of pacer limitations. (int)

### options parameter values

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. SINGLEIO A/D data is transferred to memory one sample at a time. Rates attainable using SINGLEIO are PC-dependent and generally less than 4 kHz. DMAIO A/D transfers are initiated by a DMA request. BLOCKIO A/D transfers are handled in blocks (by REP-INSW for example). BLOCKIO is not recommended for slow acquisition rates. If the rate of acquisition is very slow (for example less than 200 Hz) BLOCKIO is probably not the best choice for transfer mode. The reason for this is that 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 operation will not complete until 5.12 seconds has elapsed. BURSTIO Allows higher sampling rates for sample counts up to full FIFO. Data is collected into the local FIFO. Data transfers to the PC are held off until after the scan is complete. For BACKGROUND scans, the count and index returned by get_status() remain 0 and the status equals RUNNING until the scan finishes. When the scan is complete and the data is retrieved, the count and index are updated and the status equals IDLE. BURSTIO is the default mode for non-Continuous fast scans (aggregate sample rates above 1000 Hz) with sample counts up to full FIFO. To avoid the BURSTIO default, specify BLOCKIO. BURSTIO is not a valid option for most boards. It is used mainly for USB products.
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.
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().

### Caution!

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.

### Important

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.