niScope_Fetch

NI High-Speed Digitizers Help (NI-SCOPE)

Edition Date: January 2017

Part Number: 370592AB-01

View Product Info

DOWNLOAD (Windows Only)


NI-SCOPE (English | Japanese)

C Function Prototype

ViStatus niScope_Fetch (ViSession vi, ViConstString channelList, ViReal64 timeout, ViInt32 numSamples, ViReal64* wfm, struct niScope_wfmInfo* wfmInfo);

Purpose

Returns the waveform from a previously initiated acquisition that the digitizer acquires for the specified channel. This function returns scaled voltage waveforms.

This function may return multiple waveforms depending on the number of channels, the acquisition type, and the number of records you specify.

Notes  You can use niScope_Read instead of this function. niScope_Read starts an acquisition on all enabled channels, waits for the acquisition to complete, and returns the waveform for the specified channel.

Some functionality, such as time stamping, is not supported in all digitizers. Refer to Features Supported by Device for more information.

Related topics:

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
channelList ViConstString The channel to configure. For more information, refer to Channel String Syntax.
timeout ViReal64 The time to wait in seconds for data to be acquired; using 0 for this parameter tells NI-SCOPE to fetch whatever is currently available. Using -1 for this parameter implies infinite timeout.
numSamples ViInt32 The maximum number of samples to fetch for each waveform. If the acquisition finishes with fewer points than requested, some devices return partial data if the acquisition finished, was aborted, or a timeout of 0 was used. If it fails to complete within the timeout period, the function returns an error.
Output
Name Type Description
wfm ViReal64* Returns an array whose length is the numSamples times number of waveforms. Call niScope_ActualNumWfms to determine the number of waveforms.

NI-SCOPE returns this data sequentially, so all record 0 waveforms are first. For example, with a channel list of 0,1, you would have the following index values:

index 0 = record 0, channel 0

index x = record 0, channel 1

index 2x = record 1, channel 0

index 3x = record 1, channel 1

Where x = the record length

wfmInfo struct niScope_ wfmInfo* Returns an array of structures with the following timing and scaling information about each waveform:
  • relativeInitialX—the time (in seconds) from the trigger to the first sample in the fetched waveform
  • absoluteInitialX—timestamp (in seconds) of the first fetched sample. This timestamp is comparable between records and acquisitions; devices that do not support this parameter use 0 for this output.
  • xIncrement—the time between points in the acquired waveform in seconds
  • actualSamples—the actual number of samples fetched and placed in the waveform array
  • gain—the gain factor of the given channel; useful for scaling binary data with the following formula:

voltage = binary data × gain factor + offset

  • offset—the offset factor of the given channel; useful for scaling binary data with the following formula:

voltage = binary data × gain factor + offset

Call niScope_ActualNumWfms to determine the size of this array.

Return Value

Name Type Description
Status ViStatus Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows:

Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

WAS THIS ARTICLE HELPFUL?

Not Helpful