NI SCOPE Measurement Functions
- niScope_AddWaveformProcessing
- niScope_ClearWaveformMeasurementStats
- niScope_ClearWaveformProcessing
- niScope_FetchArrayMeasurement
- niScope_FetchMeasurement
- niScope_FetchMeasurementStats
- niScope_ReadMeasurement
ViStatus niScope_AddWaveformProcessing (ViSession vi, ViConstString channelList, ViInt32 measFunction);
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.
- Array Measurements in NI-SCOPE
- Scalar Measurements in NI-SCOPE
| 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. |
| 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 |
ViStatus niScope_ClearWaveformMeasurementStats (ViSession vi, ViConstString channelList, ViInt32 clearableMeasurementFunction);
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.
| 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. |
| 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 |
ViStatus niScope_ClearWaveformProcessing (ViSession vi, ViConstString channelList);
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.
| 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. |
| 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 |
ViStatus niScope_FetchArrayMeasurement (ViSession vi, ViConstString channelList, ViReal64 timeout, ViInt32 arrayMeasFunction, ViInt32 measWfmSize, ViReal64* measWfm, struct niScope_wfmInfo* wfmInfo;
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. |
|---|
| 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. |
| 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 |
ViStatus niScope_FetchMeasurement (ViSession vi, ViConstString channelList, ViReal64 timeout, ViInt32 scalarMeasFunction, ViReal64* result);
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.
- Making Waveform Measurements
| 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. |
| 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 |
ViStatus niScope_FetchMeasurementStats (ViSession vi, ViConstString channelList, ViReal64 timeout, ViInt32 scalarMeasFunction, ViReal64* result, ViReal64* mean, ViReal64* stdev, ViReal64* min, ViReal64* max, ViInt32*numInStats);
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.
| 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. |
| 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 |
ViStatus_VI_FUNC niScope_ReadMeasurement (ViSession vi, ViConstString channelList, ViReal64 timeout, ViInt32 scalarMeasFunction, ViReal64* result);
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.
- Making Waveform Measurements
- Acquisition Functions
| 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. |
| 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 |