Skip to content

NI SCOPE Measurement Functions

Kevin Reimnitz edited this page Mar 24, 2021 · 1 revision

Measurement Functions

niScope_AddWaveformProcessing

C Function Prototype

ViStatus niScope_AddWaveformProcessing (ViSession vi, ViConstString channelList, ViInt32 measFunction);

Purpose

Adds one measurement to the list of processing steps that are completed before the measurement. The processing is added on a per channel basis, and the processing measurements are completed in the same order they are registered. All measurement library parameters—the attributes starting with NISCOPE_ATTR_MEAS—are cached at the time of registering the processing, and this set of parameters is used during the processing step. The processing measurements are streamed, so the result of the first processing step is used as the input for the next step. The processing is done before any other measurements.

Related topics:

  • Array Measurements in NI-SCOPE
  • Scalar Measurements in NI-SCOPE

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.
measFunction ViInt32 The array measurement to add.

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


niScope_ClearWaveformMeasurementStats

C Function Prototype

ViStatus niScope_ClearWaveformMeasurementStats (ViSession vi, ViConstString channelList, ViInt32 clearableMeasurementFunction);

Purpose

Clears the waveform stats on the channel and measurement you specify. If you want to clear all of the measurements, use NISCOPE_VAL_ALL_MEASUREMENTS in the clearableMeasurementFunction parameter.

Every time a measurement is called, the statistics information is updated, including the min, max, mean, standard deviation, and number of updates. This information is fetched with niScope_FetchMeasurementStats. The multi-acquisition array measurements are also cleared with this function.

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.
clearableMeasurementFunction ViInt32 The scalar measurement or array measurement to clear the stats for.

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


niScope_ClearWaveformProcessing

C Function Prototype

ViStatus niScope_ClearWaveformProcessing (ViSession vi, ViConstString channelList);

Purpose

Clears the list of processing steps assigned to the given channel. The processing is added using the niScope_AddWaveformProcessing function, where the processing steps are completed in the same order in which they are registered. The processing measurements are streamed, so the result of the first processing step is used as the input for the next step. The processing is also done before any other measurements.

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.

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


niScope_FetchArrayMeasurement

C Function Prototype

ViStatus niScope_FetchArrayMeasurement (ViSession vi, ViConstString channelList, ViReal64 timeout, ViInt32 arrayMeasFunction, ViInt32 measWfmSize, ViReal64* measWfm, struct niScope_wfmInfo* wfmInfo;

Purpose

Obtains a waveform from the digitizer and returns the specified measurement array. This function may return multiple waveforms depending on the number of channels, the acquisition type, and the number of records you specify.

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

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.
arrayMeasFunction ViInt32 The array measurement to perform.
measWfmSize ViInt32 The maximum number of samples returned in the measurement waveform array for each waveform measurement. Use niScope_ActualMeasWfmSize to determine the number of available samples.
!Note Note  Use the attribute NISCOPE_ATTR_FETCH_MEAS_NUM_SAMPLES to set the number of samples to fetch when performing a measurement. For more information about when to use this attribute, refer to the NI KnowledgeBase.
Output
Name Type Description
measWfm ViReal64*

Returns an array whose length is the number of waveforms times measWfmSize; call niScope_ActualNumWfms to determine the number of waveforms; call niScope_ActualMeasWfmSize to determine the size of each waveform.

NI-SCOPE returns this data sequentially, so all record 0 waveforms are first. For example, with 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


niScope_FetchMeasurement

C Function Prototype

ViStatus niScope_FetchMeasurement (ViSession vi, ViConstString channelList, ViReal64 timeout, ViInt32 scalarMeasFunction, ViReal64* result);

Purpose

Fetches a waveform from the digitizer and performs the specified waveform measurement. Refer to Using Fetch Functions for more information.

Many of the measurements use the low, mid, and high reference levels. You configure the low, mid, and high references by using NISCOPE_ATTR_MEAS_CHAN_LOW_REF_LEVEL, NISCOPE_ATTR_MEAS_CHAN_MID_REF_LEVEL, and NISCOPE_ATTR_MEAS_CHAN_HIGH_REF_LEVEL to set each channel differently.

Related topics:

  • Making Waveform Measurements

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.
scalarMeasFunction ViInt32 The scalar measurement to be performed.
Output
Name Type Description
result ViReal64* Contains an array of all measurements acquired; call niScope_ActualNumWfms to determine the array length.

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


niScope_FetchMeasurementStats

C Function Prototype

ViStatus niScope_FetchMeasurementStats (ViSession vi, ViConstString channelList, ViReal64 timeout, ViInt32 scalarMeasFunction, ViReal64* result, ViReal64* mean, ViReal64* stdev, ViReal64* min, ViReal64* max, ViInt32*numInStats);

Purpose

Obtains a waveform measurement and returns the measurement value. This function may return multiple statistical results depending on the number of channels, the acquisition type, and the number of records you specify.

You specify a particular measurement type, such as rise time, frequency, or voltage peak-to-peak. The waveform on which the digitizer calculates the waveform measurement is from an acquisition that you previously initiated. The statistics for the specified measurement function are returned, where the statistics are updated once every acquisition when the specified measurement is fetched by any of the Fetch Measurement functions. If a Fetch Measurement function has not been called, this function fetches the data on which to perform the measurement. The statistics are cleared by calling niScope_ClearWaveformMeasurementStats. Refer to Using Fetch Functions for more information on incorporating fetch functions in your application.

Many of the measurements use the low, mid, and high reference levels. You configure the low, mid, and high references with NISCOPE_ATTR_MEAS_CHAN_LOW_REF_LEVEL, NISCOPE_ATTR_MEAS_CHAN_MID_REF_LEVEL, and NISCOPE_ATTR_MEAS_CHAN_HIGH_REF_LEVEL to set each channel differently.

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.
scalarMeasFunction ViInt32 The scalar measurement to be performed on each fetched waveform.
Output
Name Type Description
result ViReal64* Returns the resulting measurement
mean ViReal64* Returns the mean scalar value, which is obtained by averaging each niScope_FetchMeasurementStats call.
stdev ViReal64* Returns the standard deviation of the most recent numInStats measurements.
min ViReal64* Returns the smallest scalar value acquired (the minimum of the numInStats measurements).
max ViReal64* Returns the largest scalar value acquired (the maximum of the numInStats measurements).
numInStats ViInt32* Returns the number of times niScope_FetchMeasurementStats has been called.

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


niScope_ReadMeasurement

C Function Prototype

ViStatus_VI_FUNC niScope_ReadMeasurement (ViSession vi, ViConstString channelList, ViReal64 timeout, ViInt32 scalarMeasFunction, ViReal64* result);

Purpose

Initiates an acquisition, waits for it to complete, and performs the specified waveform measurement for a single channel and record or for multiple channels and records.

Refer to Using Fetch Functions for more information.

Many of the measurements use the low, mid, and high reference levels. You configure the low, mid, and high references by using NISCOPE_ATTR_MEAS_CHAN_LOW_REF_LEVEL, NISCOPE_ATTR_MEAS_CHAN_MID_REF_LEVEL, and NISCOPE_ATTR_MEAS_CHAN_HIGH_REF_LEVEL to set each channel differently.

Related topics:

  • Making Waveform Measurements
  • Acquisition Functions

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.
scalarMeasFunction ViInt32 The scalar measurement to be performed
Output
Name Type Description
result ViReal64* Contains an array of all measurements acquired. Call niScope_ActualNumWfms to determine the array length.

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


Table of Contents

Internal Development

Creating and Setting Up a gRPC Server

Server Security Support

Creating a gRPC Client

gRPC Client Examples

Session Utilities API Reference

Driver Documentation

gRPC API Differences From C API

Sharing Driver Sessions Between Clients

C API Docs
NI-DAQmx
NI-DCPOWER
NI-DIGITAL PATTERN DRIVER
NI-DMM
NI-FGEN
NI-FPGA
NI-RFmx Bluetooth
NI-RFmx NR
NI-RFmx WCDMA
NI-RFmx GSM
NI-RFmx CDMA2k
NI-RFmx Instr
NI-RFmx LTE
NI-RFmx SpecAn
NI-RFmx TD-SCDMA
NI-RFmx WLAN
NI-RFSA
NI-RFSG
NI-SCOPE
NI-SWITCH
NI-TCLK
NI-XNET
Clone this wiki locally