niHSDIO_FetchWaveformU8

NI Digital Waveform Generator/Analyzer

niHSDIO_FetchWaveformU8

Specific Function

C Function Prototype

ViStatus niHSDIO_FetchWaveformU8 (ViSession vi, ViInt32 samplesToRead, ViInt32 maxTimeMilliseconds, ViInt32* numberOfSamplesRead, ViUInt8[] data);

Purpose

Transfers acquired binary data from onboard memory to PC memory. The data was acquired to onboard memory previously by calling the niHSDIO_Initiate function.

If the number of samples specified in samplesToRead is still not available after the number of milliseconds specified in maxTimeMilliseconds, this function returns no data with a timeout error.

The fetch position can be modified by using niHSDIO_SetAttributeViInt32 and the NIHSDIO_ATTR_FETCH_RELATIVE_TO or NIHSDIO_ATTR_FETCH_OFFSET attributes. The default value for NIHSDIO_ATTR_FETCH_RELATIVE_TO is NIHSDIO_VAL_CURRENT_READ_POSITION. The default value for NIHSDIO_ATTR_FETCH_OFFSET is 0.

Calling this function is not necessary if you use the niHSDIO_ReadWaveformU8 function, as the fetch is performed as part of that function.

Parameters

Name Type Description
vi ViSession This handle identifies your instrument session. vi was obtained from niHSDIO_InitAcquisitionSession.
samplesToRead ViInt32 Specifies the number of samples to fetch.
maxTimeMilliseconds ViInt32 Specifies in milliseconds how long to allow the function to complete before returning a timeout error.

A value of 0 causes the function to return immediately with up to the number of samples specified in samplesToRead. If you set maxTimeMilliseconds to a value other than 0, and timeout occurs before all the samples are acquired, you receive a timeout error. If you specify a value for samplesToRead that is greater than the number of samples in the device memory, NI-HSDIO returns the available samples after maxTimeMilliseconds. A value of -1 causes the function to never time out.
numberOfSamplesRead ViInt32 Returns the number of samples that were successfully fetched and transferred into data[].
data ViUInt8[] Returns the preallocated array where samples are written.

Return Value