Reads the specified number of samples from the task buffer of a reader task.

Namespace:  Quanser.Hardware
Assembly:  Quanser.Hardware.Hil (in Quanser.Hardware.Hil.dll)

Syntax

Visual Basic (Declaration)
Function Read ( _
	numSamples As Integer, _
	analogBuffer As Double(), _
	encoderBuffer As Integer(), _
	digitalBuffer As SByte(), _
	otherBuffer As Double() _
) As Integer
C#
int Read(
	int numSamples,
	double[] analogBuffer,
	int[] encoderBuffer,
	sbyte[] digitalBuffer,
	double[] otherBuffer
)
Visual C++
int Read(
	int numSamples, 
	array<double>^ analogBuffer, 
	array<int>^ encoderBuffer, 
	array<signed char>^ digitalBuffer, 
	array<double>^ otherBuffer
)
JavaScript
function read(numSamples, analogBuffer, encoderBuffer, digitalBuffer, otherBuffer);

Parameters

numSamples
Type: System..::.Int32
The number of samples to read from the task buffer. Each "sample" consists of all the input channels specified when the task was created using TaskCreateReader(Int32, array<Int32>[]()[], array<Int32>[]()[], array<Int32>[]()[], array<Int32>[]()[]). For example, if numSamples is 5 and the task is configured to read three analog channels and two encoder channels, then the analog output buffer will contain 15 elements and the encoder output buffer will contain 10 elements.
analogBuffer
Type: array< System..::.Double >[]()[]

An array for receiving the voltage values read from the analog inputs. The array must contain numAnalogChannels * numSamples elements, where numAnalogChannels is the number of analog channels specified when the task was created. The array is organized as a linear array of samples, with each sample consisting of a group of channels. For example, if analog input channels 0, 1 and 3 are being read, than the data appears in the array as follows, where the numbers correspond to channel numbers:

0 1 3 0 1 3 ...

If no analog channels were specified in the call to TaskCreateReader(Int32, array<Int32>[]()[], array<Int32>[]()[], array<Int32>[]()[], array<Int32>[]()[]) then this parameter may be set to NoDoubleBuffer or nullptr.

encoderBuffer
Type: array< System..::.Int32 >[]()[]

An array for receiving the count values read from the encoder inputs. The array must contain numEncoderChannels * numSamples elements, where numEncoderChannels is the number of encoder channels specified when the task was created. The array is organized as a linear array of samples, with each sample consisting of a group of channels. For example, if encoder input channels 0, 1 and 3 are being read, than the data appears in the array as follows, where the numbers correspond to channel numbers:

0 1 3 0 1 3 ...

If no encoder channels were specified in the call to TaskCreateReader(Int32, array<Int32>[]()[], array<Int32>[]()[], array<Int32>[]()[], array<Int32>[]()[]) then this parameter may be set to NoIntegerBuffer or nullptr.

digitalBuffer
Type: array< System..::.SByte >[]()[]

An array for receiving the state values read from the digital inputs. The array must contain numDigitalChannels * numSamples elements, where numDigitalChannels is the number of digital channels specified when the task was created. The array is organized as a linear array of samples, with each sample consisting of a group of channels. For example, if digital input channels 0, 1 and 3 are being read, than the data appears in the array as follows, where the numbers correspond to channel numbers:

0 1 3 0 1 3 ...

If no digital channels were specified in the call to TaskCreateReader(Int32, array<Int32>[]()[], array<Int32>[]()[], array<Int32>[]()[], array<Int32>[]()[]) then this parameter may be set to NoBooleanBuffer or nullptr.

otherBuffer
Type: array< System..::.Double >[]()[]

An array for receiving the values read from the other inputs. The array must contain numOtherChannels * numSamples elements, where numOtherChannels is the number of other channels specified when the task was created. The array is organized as a linear array of samples, with each sample consisting of a group of channels. For example, if other input channels 0, 1 and 3 are being read, than the data appears in the array as follows, where the numbers correspond to channel numbers:

0 1 3 0 1 3 ...

If no other channels were specified in the call to TaskCreateReader(Int32, array<Int32>[]()[], array<Int32>[]()[], array<Int32>[]()[], array<Int32>[]()[]) then this parameter may be set to NoDoubleBuffer or nullptr.

Return Value

The return value is the number of samples read from the task buffer. This value may be less than the requested number of samples (including 0) if the task is stopped or has finished processing the total number of samples indicated in the call to Start(Hil..::.Clock, Double, Int32).

Remarks

The Read method reads the specified number of samples from the task buffer of a task created using the TaskCreateReader(Int32, array<Int32>[]()[], array<Int32>[]()[], array<Int32>[]()[], array<Int32>[]()[]) method. If there's not enough samples in the task buffer, then this method will block until the requested number of samples becomes available or the task stops. Since the task reads the hardware at the sampling rate specified in the call to Start(Hil..::.Clock, Double, Int32), and stores the data in the task buffer, this method will never block for longer than the requested number of samples times the sampling period.

Because this method blocks until enough data is available and the task buffer is filled at a given sampling rate, calling this method synchronizes the caller to that sampling rate (provided the task buffer is not being filled faster than we can read the data). Thus, the Read method may be used to implement control systems, system identification, synchronous data streaming and other operations requiring a fixed sampling rate. For control systems, the numSamples parameter is typically 1, since control calculations need to be performed on each sample. For data streaming, the numSamples parameter is typically half the number of samples in the task buffer to implement double-buffering.

Warning

Many cards allow the digital I/O lines to be programmed as inputs or outputs. The digital I/O lines are configured as inputs or outputs using the SetDigitalDirections(array<Int32>[]()[], array<Int32>[]()[]) method. All the channels which will be used as digital inputs or outputs must be configured accordingly using this function. Failure to configure the digital I/O may result in the Read(Int32, array<Double>[]()[], array<Int32>[]()[], array<SByte>[]()[], array<Double>[]()[]) method failing to read the digital I/O as expected.

Examples

This example illustrates how to read analog and encoder inputs using a task. The task reads from the first four analog input channels, and first two encoder input channels every millisecond using a hardware clock. The data may be processed each sampling instant. It runs for 5 seconds before stopping. Exceptions are ignored for simplicity.
C# Copy Code
int [] analogChannels  = { 0, 1, 2, 3 };
int [] encoderChannels = { 0, 1 };
double frequency       = 1000;
int    samples         = 5000;
int    samplesInBuffer = frequency;
int    samplesToRead   = 1;

double [] analogBuffer  = new double [samplesToRead * analogChannels.length];
int []    encoderBuffer = new int    [samplesToRead * encoderChannels.length];

Hil.Task task;

task = card.TaskCreateReader(samplesInBuffer, analogChannels, encoderChannels, nullptr, nullptr);
task.Start(Hil.Clock.Hardware0, frequency, samples);
for (int index = 0; index < samples; index += samplesToRead) {
    /* Block (if necessary) waiting for next samplesToRead samples */
    task.Read(samplesToRead, analogBuffer, encoderBuffer, nullptr, nullptr);

    /* ... process sample ... */
}
task.Stop();
Visual Basic Copy Code
Dim analogChannels() As Integer = {0, 1, 2, 3}
Dim encoderChannels() As Integer = {0, 1}
Dim frequency as Double = 1000
Dim samples As Integer = 5000
Dim samplesInBuffer As Integer = frequency
Dim samplesToRead As Integer = 1

Dim analogBuffer(samplesToRead * analogChannels.Length - 1) As Double
Dim encoderBuffer(samplesToRead * encoderChannels.Length - 1) As Integer
Dim task As Hil.Task
Dim index As Integer

task = card.TaskCreateReader(samplesInBuffer, analogChannels, encoderChannels, Hil.NoChannels, Hil.NoChannels)
task.Start(Hil.Clock.Hardware0, frequency, samples)
For index = 0 To samples - 1 Step samplesToRead
    ' Block (if necessary) waiting for next samplesToRead samples
    task.Read(samplesToRead, analogBuffer, encoderBuffer, Hil.NoBooleanBuffer, Hil.NoDoubleBuffer)

    ' ... process sample ...
Next
task.Stop()
Visual C++ Copy Code
array<int>^ analogChannels  = { 0, 1, 2, 3 };
array<int>^ encoderChannels = { 0, 1 };
double      frequency       = 1000;
int         samples         = 5000;
int         samplesInBuffer = frequency;
int         samplesToRead   = 1;

array<double>^ analogBuffer = gcnew array<double>(samplesToRead * analogChannels->Length);
array<int>^ encoderBuffer = gcnew array<int>(samplesToRead * encoderChannels->Length);
Hil::Task^ task;

task = card->TaskCreateReader(samplesInBuffer, analogChannels, encoderChannels, nullptr, nullptr);
task->Start(Hil::Clock::Hardware0, frequency, samples);
for (int index = 0; index < samples; index += samplesToRead) {
    /* Block (if necessary) waiting for next samplesToRead samples */
    task->Read(samplesToRead, analogBuffer, encoderBuffer, nullptr, nullptr);

    /* ... process sample ... */
}
task->Stop();

Exceptions

ExceptionCondition
Quanser.Hardware..::.HilException If the read cannot be performed then an exception is thrown. This situtation typically arises if the task buffer overflowed (ran out of space) after the last call to this method.

See Also