Skip to content

NI SCOPE Configure Functions

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

Configure Functions

niScope_AutoSetup

C Function Prototype

ViStatus niScope_AutoSetup (ViSession vi);

Purpose

Automatically configures the instrument. When you call this function, the digitizer senses the input signal and automatically configures many of the instrument settings. If a signal is detected on a channel, the driver chooses the smallest available vertical range that is larger than the signal range. For example, if the signal is a 1.2 Vpk-pk sine wave, and the device supports 1 V and 2 V vertical ranges, the driver will choose the 2 V vertical range for that channel.

If no signal is found on any analog input channel, a warning is returned, and all channels are enabled. A channel is considered to have a signal present if the signal is at least 10% of the smallest vertical range available for that channel.

The following settings are changed:

General
Acquisition mode Normal
Reference clock Internal
Vertical
Vertical coupling AC (when AC is supported; otherwise DC)
Vertical bandwidth    Full
Vertical range Changed by auto setup
Vertical offset 0 V
Probe attenuation Unchanged by auto setup
Input impedance Unchanged by auto setup
Horizontal
Sample rate Changed by auto setup
Min record length Changed by auto setup
Enforce realtime True
Number of Records Changed to 1
Triggering
Trigger type Edge if signal present, otherwise immediate
Trigger channel Lowest numbered channel with a signal present
Trigger slope Positive
Trigger coupling DC
Reference position 50%
Trigger level 50% of signal on trigger channel
Trigger delay 0
Trigger holdoff 0
Trigger output None

Related topics:

  • Configuring an Acquisition Using Auto_Setup

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.

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_ConfigureAcquisition

C Function Prototype

ViStatus niScope_ConfigureAcquisition(ViSession vi, ViInt32 acquisitionType);

Purpose

Configures how the oscilloscope acquires data and fills the waveform record.

Related topics:

  • Acquisition Functions

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
acquisitionType ViInt32

Specifies the manner in which the digitizer acquires data and fills the waveform record; NI-SCOPE sets NISCOPE_ATTR_ACQUISITION_TYPE to this value.

Defined Values
NISCOPE_VAL_NORMAL (0) Sets the oscilloscope to normal resolution mode. The oscilloscope can use real-time sampling or equivalent-time sampling.
NISCOPE_VAL_FLEXRES (1001) Sets legacy oscilloscopes to flexible resolution mode, if supported.
NISCOPE_VAL_DDC (1002) Sets legacy oscilloscopes to DDC mode, if supported. To use DDC mode for the PXI/PCI-5142 or PXIe-5622, set this control to NISCOPE_VAL_NORMAL and set the NISCOPE_ATTR_DDC_ENABLED attribute to VI_TRUE.

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_ConfigureHorizontalTiming

C Function Prototype

ViStatus niScope_ConfigureHorizontalTiming (ViSession vi, ViReal64 minSampleRate, ViInt32 minNumPts, ViReal64 refPosition, ViInt32 numRecords, ViBoolean enforceRealtime);

Purpose

Configures the common properties of the horizontal subsystem for a multirecord acquisition in terms of minimum sample rate.

Related topics:

  • Configuring the Horizontal Settings
  • NI-TClk Overview
  • Coercions of Horizontal Parameters

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
minSampleRate ViReal64 The sampling rate for the acquisition. Refer to NISCOPE_ATTR_MIN_SAMPLE_RATE for more information.
minNumPts ViInt32

The minimum number of points you need in the record for each channel; call niScope_ActualRecordLength to obtain the actual record length used.

Valid Values: Greater than 1; limited by available memory
refPosition ViReal64 The position of the Reference Event in the waveform record specified as a percentage.
numRecords ViInt32 The number of records to acquire
enforceRealtime ViBoolean

Indicates whether the digitizer enforces real-time measurements or allows equivalent-time (RIS) measurements; not all digitizers support RIS—refer to Features Supported by Device) for more information.

Default value: VI_TRUE

Defined Values

VI_TRUE—Allow real-time acquisitions only

VI_FALSE—Allow real-time and equivalent-time acquisitions

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_ConfigureChanCharacteristics

C Function Prototype

ViStatus niScope_ConfigureChanCharacteristics (ViSession vi, ViConstString channelList, ViReal64 inputImpedance, ViReal64 maxInputFrequency);

Purpose

Configures the attributes that control the electrical characteristics of the channel—the input impedance and the bandwidth.

Related topics:

  • Using Configure Chan Characteristics
  • Impedance and Impedance Matching

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.
inputImpedance ViReal64 The input impedance for the channel; NI-SCOPE sets NISCOPE_ATTR_INPUT_IMPEDANCE to this value.
maxInputFrequency ViReal64 The bandwidth for the channel; NI-SCOPE sets NISCOPE_ATTR_MAX_INPUT_FREQUENCY to this value. Pass 0 for this value to use the hardware default bandwidth. Pass –1 for this value to achieve full bandwidth.

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_ConfigureVertical

C Function Prototype

ViStatus niScope_ConfigureVertical (ViSession vi, ViConstString channelList, ViReal64 range, ViReal64 offset, ViInt32 coupling, ViReal64 probeAttenuation, ViBoolean enabled);

Purpose

Configures the most commonly configured attributes of the digitizer vertical subsystem, such as the range, offset, coupling, probe attenuation, and the channel.

Related topics:

  • Configuring the Vertical Settings
  • NI-SCOPE Programming Flow
  • Coercions of Vertical Parameters

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.
range ViReal64 Specifies the vertical range Refer to NISCOPE_ATTR_VERTICAL_RANGE for more information.
offset ViReal64 Specifies the vertical offset. Refer to NISCOPE_ATTR_VERTICAL_OFFSET for more information.
coupling ViInt32 Specifies how to couple the input signal. Refer to NISCOPE_ATTR_VERTICAL_COUPLING for more information.
probeAttenuation ViReal64 Specifies the probe attenuation. Refer to NISCOPE_ATTR_PROBE_ATTENUATION for valid values.
enabled ViBoolean Specifies whether the channel is enabled for acquisition. Refer to NISCOPE_ATTR_CHANNEL_ENABLED for more information.

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_ActualMeasWfmSize

C Function Prototype

ViStatus niScope_ActualMeasWfmSize(ViSession vi, ViInt32 arrayMeasFunction, ViInt32* measWfmSize);

Purpose

Returns the total available size of an array measurement acquisition.

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
arrayMeasFunction ViInt32 The array measurement to perform.
Output
Name Type Description
measWfmSize ViInt32* Returns the size (in number of samples) of the resulting analysis waveform.

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_ActualNumWfms

C Function Prototype

ViStatus niScope_ActualNumWfms (ViSession vi, ViConstString channelList, ViInt32* numWfms);

Purpose

Helps you to declare appropriately sized waveforms. NI-SCOPE handles the channel list parsing for you.

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.
Output
Name Type Description
numWfms ViInt32* Returns the number of records times the number of channels; if the niScope_ConfigureAcquisition acquisitionType is set to NISCOPE_VAL_DDC, this value is multiplied by two.

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_ActualRecordLength

C Function Prototype

ViStatus niScope_ActualRecordLength (ViSession vi, ViInt32* recordLength);

Purpose

Returns the actual number of points the digitizer acquires for each channel. After configuring the digitizer for an acquisition, call this function to determine the size of the waveforms that the digitizer acquires. The value is equal to or greater than the minimum number of points specified in any of the Configure Horizontal functions.

Related topics:

  • Sample Rate
  • Coercions of Horizontal Parameters

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
Output
Name Type Description
recordLength ViInt32* Returns the actual number of points the digitizer acquires for each channel; NI-SCOPE returns the value held in the NISCOPE_ATTR_HORZ_RECORD_LENGTH attribute.

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_SampleMode

C Function Prototype

ViStatus niScope_SampleMode (ViSession vi, ViInt32* sampleMode);

Purpose

Returns the sample mode the digitizer is currently using.

Related topics:

  • Sampling Methods

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
Output
Name Type Description
sampleMode ViInt32* Returns the sample mode the digitizer is currently using; NI-SCOPE returns the value of the NISCOPE_ATTR_SAMPLE_MODE attribute.

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_SampleRate

C Function Prototype

ViStatus niScope_SampleRate (ViSession vi, ViReal64* actualSampleRate);

Purpose

Returns the effective sample rate, in samples per second, of the acquired waveform using the current configuration. Refer to Coercions of Horizontal Parameters for more information about sample rate coercion.

Related topics:

  • Sample Rate
  • Coercions of Horizontal Parameters
  • Sample Clock

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
Output
Name Type Description
actualSampleRate ViReal64* Returns the effective sample rate of the acquired waveform the digitizer acquires for each channel; the driver returns the value held in the NISCOPE_ATTR_HORZ_SAMPLE_RATE attribute.

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_ConfigureTriggerDigital

C Function Prototype

ViStatus niScope_ConfigureTriggerDigital (ViSession vi, ViConstString triggerSource, ViInt32 slope, ViReal64 holdoff, ViReal64 delay);

Purpose

Configures the common properties of a digital trigger.

When you initiate an acquisition, the digitizer waits for the start trigger, which is configured through the NISCOPE_ATTR_ACQ_ARM_SOURCE (Start Trigger Source) attribute. The default is immediate. Upon receiving the start trigger the digitizer begins sampling pretrigger points. After the digitizer finishes sampling pretrigger points, the digitizer waits for a reference (stop) trigger that you specify with a function such as this one. Upon receiving the reference trigger the digitizer finishes the acquisition after completing posttrigger sampling. With each Configure Trigger function, you specify configuration parameters such as the trigger source and the amount of trigger delay.

Notes  For multirecord acquisitions, all records after the first record are started by using the Advance Trigger Source. The default is immediate.

You can adjust the amount of pre-trigger and post-trigger samples using the reference position parameter on the niScope_ConfigureHorizontalTiming function. The default is half of the record length.

Some features are not supported by all digitizers. Refer to Features Supported by Device for more information.

Digital triggering is not supported in RIS mode.

Related topics:

  • Digital Triggers
  • Equivalent-Time Sampling and Random Interleaved Sampling

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
triggerSource ViConstString Specifies the trigger source. Refer to NISCOPE_ATTR_TRIGGER_SOURCE for defined values.
slope ViInt32 Specifies whether you want a rising edge or a falling edge to trigger the digitizer. Refer to NISCOPE_ATTR_TRIGGER_SLOPE for more information.
holdoff ViReal64 The length of time the digitizer waits after detecting a trigger before enabling NI-SCOPE to detect another trigger. Refer to NISCOPE_ATTR_TRIGGER_HOLDOFF for more information.
delay ViReal64 How long the digitizer waits after receiving the trigger to start acquiring data. Refer to NISCOPE_ATTR_TRIGGER_DELAY_TIME for more information.

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_ConfigureTriggerEdge

C Function Prototype

ViStatus niScope_ConfigureTriggerEdge (ViSession vi, ViConstString triggerSource, ViReal64 level, ViInt32 slope, ViInt32 triggerCoupling, ViReal64 holdoff, ViReal64 delay);

Purpose

Configures common properties for analog edge triggering.

When you initiate an acquisition, the digitizer waits for the start trigger, which is configured through the NISCOPE_ATTR_ACQ_ARM_SOURCE (Start Trigger Source) attribute. The default is immediate. Upon receiving the start trigger the digitizer begins sampling pretrigger points. After the digitizer finishes sampling pretrigger points, the digitizer waits for a reference (stop) trigger that you specify with a function such as this one. Upon receiving the reference trigger the digitizer finishes the acquisition after completing posttrigger sampling. With each Configure Trigger function, you specify configuration parameters such as the trigger source and the amount of trigger delay.

Note  Some features are not supported by all digitizers. Refer to Features Supported by Device) for more information.

Related topics:

  • Edge Triggers

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
triggerSource ViConstString Specifies the trigger source. Refer to NISCOPE_ATTR_TRIGGER_SOURCE for defined values.
level ViReal64 The voltage threshold for the trigger. Refer to NISCOPE_ATTR_TRIGGER_LEVEL for more information.
slope ViInt32 Specifies whether you want a rising edge or a falling edge to trigger the digitizer. Refer to NISCOPE_ATTR_TRIGGER_SLOPE for more information.
triggerCoupling ViInt32 Applies coupling and filtering options to the trigger signal. Refer to NISCOPE_ATTR_TRIGGER_COUPLING for more information.
holdoff ViReal64 The length of time the digitizer waits after detecting a trigger before enabling NI-SCOPE to detect another trigger. Refer to NISCOPE_ATTR_TRIGGER_HOLDOFF for more information.
delay ViReal64 How long the digitizer waits after receiving the trigger to start acquiring data. Refer to NISCOPE_ATTR_TRIGGER_DELAY_TIME for more information.

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_ConfigureTriggerGlitch

ViStatus niScope_ConfigureTriggerGlitch (ViSession Instrument_Handle, ViChar _VI_FAR Trigger_Source[], ViReal64 Level, ViReal64 Width, ViInt32 Polarity, ViInt32 Condition, ViInt32 Trigger_Coupling, ViReal64 Holdoff, ViReal64 Delay);

Purpose

Configures common properties for glitch triggering.

A glitch trigger occurs when a pulse that crosses a vertical threshold you specify and with a polarity you specify also has a width that is either greater than or less than a duration you specify.

Trigger System Operation

When you initiate an acquisition, the trigger system operates in the following manner.

  • The digitizer waits for the start trigger, which is configured through the NISCOPE_ATTR_ACQ_ARM_SOURCE attribute. The default is NISCOPE_VAL_IMMEDIATE.
  • Upon receiving the start trigger, the digitizer begins sampling pretrigger points.
  • After the digitizer finishes sampling pretrigger points, the digitizer waits for a reference (stop) trigger that you specify with a trigger function such as this one.
  • Upon receiving the reference trigger, the digitizer finishes the acquisition after completing posttrigger sampling.

With each Configure Trigger function, you specify configuration parameters such as the trigger source and the amount of trigger delay. Additionally, you can adjust the amount of pretrigger and posttrigger samples using the refPosition input of the niScope_ConfigureHorizontalTiming function. The default is half the record length.

For multirecord acquisitions, all records after the first record are started based on the setting of the NISCOPE_ATTR_ADV_TRIG_SRC attribute. The default value is NISCOPE_VAL_IMMEDIATE.

Note  Some features are not supported by all digitizers. Refer to Features Supported by Device) for more information.

Related topics:

  • Glitch Triggers

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
triggerSource ViConstString Specifies the trigger source. Refer to NISCOPE_ATTR_TRIGGER_SOURCE for defined values.
level ViReal64 The voltage threshold for the trigger. Refer to NISCOPE_ATTR_TRIGGER_LEVEL for more information.
Width ViReal64

Specifies, in seconds, the glitch duration to be used in combination with the glitch condition that triggers the oscilloscope.

The oscilloscope triggers when it detects a pulse of duration either less than or greater than this value depending on the value of the NISCOPE_ATTR_GLITCH_CONDITION attribute. Refer to the NISCOPE_ATTR_GLITCH_WIDTH attribute for more information.

Polarity ViInt32 Specifies the polarity of the pulses that trigger the oscilloscope for glitch triggering. Refer to the NISCOPE_ATTR_GLITCH_POLARITY attribute for defined values.
Glitch Condition ViInt32 Specifies whether the oscilloscope triggers on pulses of duration less than or greater than the specified NISCOPE_ATTR_GLITCH_WIDTH. Refer to the NISCOPE_ATTR_GLITCH_CONDITION attribute for defined values.
triggerCoupling ViInt32 Applies coupling and filtering options to the trigger signal. Refer to NISCOPE_ATTR_TRIGGER_COUPLING for more information.
holdoff ViReal64 The length of time the digitizer waits after detecting a trigger before enabling NI-SCOPE to detect another trigger. Refer to NISCOPE_ATTR_TRIGGER_HOLDOFF for more information.
delay ViReal64 How long the digitizer waits after receiving the trigger to start acquiring data. Refer to NISCOPE_ATTR_TRIGGER_DELAY_TIME for more information.

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_ConfigureTriggerHysteresis

C Function Prototype

ViStatus niScope_ConfigureTriggerHysteresis (ViSession vi, ViConstString triggerSource, ViReal64 level, ViReal64 hysteresis, ViInt32 slope, ViInt32 triggerCoupling, ViReal64 holdoff, ViReal64 delay);

Purpose

Configures common properties for analog hysteresis triggering. This kind of trigger specifies an additional value, specified in the hysteresis parameter, that a signal must pass through before a trigger can occur. This additional value acts as a kind of buffer zone that keeps noise from triggering an acquisition.

When you initiate an acquisition, the digitizer waits for the start trigger, which is configured through the NISCOPE_ATTR_ACQ_ARM_SOURCE (Start Trigger Source)). The default is immediate. Upon receiving the start trigger the digitizer begins sampling pretrigger points. After the digitizer finishes sampling pretrigger points, the digitizer waits for a reference (stop) trigger that you specify with a function such as this one. Upon receiving the reference trigger the digitizer finishes the acquisition after completing posttrigger sampling. With each Configure Trigger function, you specify configuration parameters such as the trigger source and the amount of trigger delay.

Note  Some features are not supported by all digitizers. Refer to Features Supported by Device) for more information.

Related topics:

  • Hysteresis Triggers

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
triggerSource ViConstString Specifies the trigger source. Refer to NISCOPE_ATTR_TRIGGER_SOURCE for defined values.
level ViReal64 The voltage threshold for the trigger. Refer to NISCOPE_ATTR_TRIGGER_LEVEL for more information.
hysteresis ViReal64 The size of the hysteresis window on either side of the level in volts; the digitizer triggers when the trigger signal passes through the hysteresis value you specify with this parameter, has the slope you specify with slope, and passes through the level. Refer to NISCOPE_ATTR_TRIGGER_HYSTERESIS for defined values.
slope ViInt32 Specifies whether you want a rising edge or a falling edge to trigger the digitizer. Refer to NISCOPE_ATTR_TRIGGER_SLOPE for more information.
triggerCoupling ViInt32 Applies coupling and filtering options to the trigger signal. Refer to NISCOPE_ATTR_TRIGGER_COUPLING for more information.
holdoff ViReal64 The length of time the digitizer waits after detecting a trigger before enabling NI-SCOPE to detect another trigger. Refer to NISCOPE_ATTR_TRIGGER_HOLDOFF for more information.
delay ViReal64 How long the digitizer waits after receiving the trigger to start acquiring data. Refer to NISCOPE_ATTR_TRIGGER_DELAY_TIME for more information.

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_ConfigureTriggerImmediate

C Function Prototype

ViStatus niScope_ConfigureTriggerImmediate (ViSession vi);

Purpose

Configures common properties for immediate triggering. Immediate triggering means the digitizer triggers itself.

When you initiate an acquisition, the digitizer waits for a trigger. You specify the type of trigger that the digitizer waits for with a Configure Trigger function, such as niScope_ConfigureTriggerImmediate.

Related topics:

  • Immediate Triggers

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.

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_ConfigureTriggerRunt

ViStatus niScope_ConfigureTriggerRunt (ViSession Instrument_Handle, ViChar _VI_FAR Trigger_Source[], ViReal64 Low_Threshold, ViReal64 High_Threshold, ViInt32 Polarity, ViInt32 Trigger_Coupling, ViReal64 Holdoff, ViReal64 Delay);

Purpose

Configures common properties for runt triggering.

A runt trigger occurs when both the leading edge and trailing edge of a pulse cross only one of two trigger thresholds you specify and with a polarity you specify, where the polarity is relative to the threshold crossed.

Trigger System Operation

When you initiate an acquisition, the trigger system operates in the following manner.

  • The digitizer waits for the start trigger, which is configured through the NISCOPE_ATTR_ACQ_ARM_SOURCE attribute. The default is NISCOPE_VAL_IMMEDIATE.
  • Upon receiving the start trigger, the digitizer begins sampling pretrigger points.
  • After the digitizer finishes sampling pretrigger points, the digitizer waits for a reference (stop) trigger that you specify with a trigger function such as this one.
  • Upon receiving the reference trigger, the digitizer finishes the acquisition after completing posttrigger sampling.

With each Configure Trigger function, you specify configuration parameters such as the trigger source and the amount of trigger delay. Additionally, you can adjust the amount of pretrigger and posttrigger samples using the refPosition input of the niScope_ConfigureHorizontalTiming function. The default is half the record length.

For multirecord acquisitions, all records after the first record are started based on the setting of the NISCOPE_ATTR_ADV_TRIG_SRC attribute. The default value is NISCOPE_VAL_IMMEDIATE.

Note  Some features are not supported by all digitizers. Refer to Features Supported by Device) for more information.

Related topics:

  • Runt Triggers

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
triggerSource ViConstString Specifies the trigger source. Refer to NISCOPE_ATTR_TRIGGER_SOURCE for defined values.
Low Threshold ViReal64 Specifies, in volts, the lower of two thresholds that bound the vertical range to examine for runt pulses. Refer to the NISCOPE_ATTR_RUNT_LOW_THRESHOLD attribute for more information.
High Threshold ViReal64 Specifies, in volts, the higher of two thresholds that bound the vertical range to examine for runt pulses. Refer to the NISCOPE_ATTR_RUNT_HIGH_THRESHOLD attribute for more information.
Polarity ViInt32 Specifies the polarity of the runt pulses, relative to the runt threshold the pulses cross, that trigger the oscilloscope for runt triggering. Refer to the NISCOPE_ATTR_RUNT_POLARITY attribute for defined values.
triggerCoupling ViInt32 Applies coupling and filtering options to the trigger signal. Refer to NISCOPE_ATTR_TRIGGER_COUPLING for more information.
holdoff ViReal64 The length of time the digitizer waits after detecting a trigger before enabling NI-SCOPE to detect another trigger. Refer to NISCOPE_ATTR_TRIGGER_HOLDOFF for more information.
delay ViReal64 How long the digitizer waits after receiving the trigger to start acquiring data. Refer to NISCOPE_ATTR_TRIGGER_DELAY_TIME for more information.

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_ConfigureTriggerSoftware

C Function Prototype

ViStatus niScope_ConfigureTriggerSoftware (ViSession vi, ViReal64 holdoff, ViReal64 delay);

Purpose

Configures common properties for software triggering.

When you initiate an acquisition, the digitizer waits for the start trigger, which is configured through the NISCOPE_ATTR_ACQ_ARM_SOURCE (Start Trigger Source) attribute. The default is immediate. Upon receiving the start trigger the digitizer begins sampling pretrigger points. After the digitizer finishes sampling pretrigger points, the digitizer waits for a reference (stop) trigger that you specify with a function such as this one. Upon receiving the reference trigger the digitizer finishes the acquisition after completing posttrigger sampling. With each Configure Trigger function, you specify configuration parameters such as the trigger source and the amount of trigger delay.

To trigger the acquisition, use niScope_SendSoftwareTriggerEdge.

Note   Some features are not supported by all digitizers. Refer to Features Supported by Device) for more information.

Related topics:

  • Software Triggers

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
holdoff ViReal64 The length of time the digitizer waits after detecting a trigger before enabling NI-SCOPE to detect another trigger. Refer to NISCOPE_ATTR_TRIGGER_HOLDOFF for more information.
delay ViReal64 How long the digitizer waits after receiving the trigger to start acquiring data. Refer to NISCOPE_ATTR_TRIGGER_DELAY_TIME for more information.

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_ConfigureTriggerVideo

C Function Prototype

ViStatus niScope_ConfigureTriggerVideo (ViSession vi, ViConstString triggerSource, ViBoolean enableDCRestore, ViInt32 signalFormat, ViInt32 event, ViInt32 lineNumber, ViInt32 polarity, ViInt32 triggerCoupling, ViReal64 holdoff, ViReal64 delay);

Purpose

Configures the common properties for video triggering, including the signal format, TV event, line number, polarity, and enable DC restore. A video trigger occurs when the digitizer finds a valid video signal sync.

When you initiate an acquisition, the digitizer waits for the start trigger, which is configured through the NISCOPE_ATTR_ACQ_ARM_SOURCE (Start Trigger Source) attribute. The default is immediate. Upon receiving the start trigger the digitizer begins sampling pretrigger points. After the digitizer finishes sampling pretrigger points, the digitizer waits for a reference (stop) trigger that you specify with a function such as this one. Upon receiving the reference trigger the digitizer finishes the acquisition after completing posttrigger sampling. With each Configure Trigger function, you specify configuration parameters such as the trigger source and the amount of trigger delay.

Note  Some features are not supported by 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.
triggerSource ViConstString Specifies the trigger source. Refer to NISCOPE_ATTR_TRIGGER_SOURCE for defined values.
enableDCRestore ViBoolean Offsets each video line so the clamping level (the portion of the video line between the end of the color burst and the beginning of the active image) is moved to zero volt. Refer to NISCOPE_ATTR_ENABLE_DC_RESTORE for defined values.
signalFormat ViInt32 Specifies the type of video signal sync the digitizer should look for. Refer to NISCOPE_ATTR_TV_TRIGGER_SIGNAL_FORMAT for more information.
event ViInt32 Specifies the TV event you want to trigger on. You can trigger on a specific or on the next coming line or field of the signal.
lineNumber ViInt32

Selects the line number to trigger on. The line number range covers an entire frame and is referenced as shown on Vertical Blanking and Synchronization Signal. Refer to NISCOPE_ATTR_TV_TRIGGER_LINE_NUMBER for more information.

Default value: 1
polarity ViInt32 Specifies the polarity of the video signal sync.
triggerCoupling ViInt32 Applies coupling and filtering options to the trigger signal. Refer to NISCOPE_ATTR_TRIGGER_COUPLING for more information.
holdoff ViReal64 The length of time the digitizer waits after detecting a trigger before enabling NI-SCOPE to detect another trigger. Refer to NISCOPE_ATTR_TRIGGER_HOLDOFF for more information.
delay ViReal64 How long the digitizer waits after receiving the trigger to start acquiring data. Refer to NISCOPE_ATTR_TRIGGER_DELAY_TIME for more information.

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_ConfigureTriggerWidth

ViStatus niScope_ConfigureTriggerWidth (ViSession Instrument_Handle, ViChar _VI_FAR Trigger_Source[], ViReal64 Level, ViReal64 Low_Threshold, ViReal64 High_Threshold, ViInt32 Polarity, ViInt32 Condition, ViInt32 Trigger_Coupling, ViReal64 Holdoff, ViReal64 Delay);

Purpose

Configures common properties for width triggering.

A width trigger occurs when a pulse that crosses a vertical threshold you specify and with a polarity you specify also has a duration that is either within or outside a duration range you specify.

Trigger System Operation

When you initiate an acquisition, the trigger system operates in the following manner.

  • The digitizer waits for the start trigger, which is configured through the NISCOPE_ATTR_ACQ_ARM_SOURCE attribute. The default is NISCOPE_VAL_IMMEDIATE.
  • Upon receiving the start trigger, the digitizer begins sampling pretrigger points.
  • After the digitizer finishes sampling pretrigger points, the digitizer waits for a reference (stop) trigger that you specify with a trigger function such as this one.
  • Upon receiving the reference trigger, the digitizer finishes the acquisition after completing posttrigger sampling.

With each Configure Trigger function, you specify configuration parameters such as the trigger source and the amount of trigger delay. Additionally, you can adjust the amount of pretrigger and posttrigger samples using the refPosition input of the niScope_ConfigureHorizontalTiming function. The default is half the record length.

For multirecord acquisitions, all records after the first record are started based on the setting of the NISCOPE_ATTR_ADV_TRIG_SRC attribute. The default value is NISCOPE_VAL_IMMEDIATE.

Note  Some features are not supported by all digitizers. Refer to Features Supported by Device) for more information.

Related topics:

  • Width Triggers

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
triggerSource ViConstString Specifies the trigger source. Refer to NISCOPE_ATTR_TRIGGER_SOURCE for defined values.
level ViReal64 The voltage threshold for the trigger. Refer to NISCOPE_ATTR_TRIGGER_LEVEL for more information.
Low Threshold ViReal64 Specifies, in seconds, the lower bound on the range of pulse durations that triggers the oscilloscope. Refer to the NISCOPE_ATTR_WIDTH_LOW_THRESHOLD attribute for defined values.
High Threshold ViReal64 Specifies, in seconds, the upper bound on the range of pulse durations that triggers the oscilloscope. Refer to the NISCOPE_ATTR_WIDTH_HIGH_THRESHOLD attribute for defined values.
Polarity ViInt32 Specifies the polarity of the pulses that trigger the oscilloscope for width triggering. Refer to the NISCOPE_ATTR_WIDTH_POLARITY attribute for defined values.
Condition ViInt32 Specifies whether the oscilloscope triggers on pulses of duration within or outside the range of pulse durations bounded by Low Threshold and High Threshold. Refer to the NISCOPE_ATTR_WIDTH_CONDITION attribute for defined values.
triggerCoupling ViInt32 Applies coupling and filtering options to the trigger signal. Refer to NISCOPE_ATTR_TRIGGER_COUPLING for more information.
holdoff ViReal64 The length of time the digitizer waits after detecting a trigger before enabling NI-SCOPE to detect another trigger. Refer to NISCOPE_ATTR_TRIGGER_HOLDOFF for more information.
delay ViReal64 How long the digitizer waits after receiving the trigger to start acquiring data. Refer to NISCOPE_ATTR_TRIGGER_DELAY_TIME for more information.

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_ConfigureTriggerWindow

C Function Prototype

ViStatus niScope_ConfigureTriggerWindow (ViSession vi, ViConstString triggerSource, ViReal64 lowLevel, ViReal64 highLevel, ViInt32 windowMode, ViInt32 triggerCoupling, ViReal64 holdoff, ViReal64 delay);

Purpose

Configures common properties for analog window triggering. A window trigger occurs when a signal enters or leaves a window you specify with the high level or low level parameters.

When you initiate an acquisition, the digitizer waits for the start trigger, which is configured through the NISCOPE_ATTR_ACQ_ARM_SOURCE (Start Trigger Source) attribute. The default is immediate. Upon receiving the start trigger the digitizer begins sampling pretrigger points. After the digitizer finishes sampling pretrigger points, the digitizer waits for a reference (stop) trigger that you specify with a function such as this one. Upon receiving the reference trigger the digitizer finishes the acquisition after completing posttrigger sampling. With each Configure Trigger function, you specify configuration parameters such as the trigger source and the amount of trigger delay.

To trigger the acquisition, use niScope_SendSoftwareTriggerEdge.

Note   Some features are not supported by all digitizers. Refer to Features Supported by Device) for more information.

Related topics:

  • Window Triggers

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
triggerSource ViConstString Specifies the trigger source. Refer to NISCOPE_ATTR_TRIGGER_SOURCE for defined values.
lowLevel ViReal64 Passes the voltage threshold you want the digitizer to use for low triggering.
highLevel ViReal64 Passes the voltage threshold you want the digitizer to use for high triggering.
windowMode ViInt32 Specifies whether you want the trigger to occur when the signal enters or leaves a window.
triggerCoupling ViInt32 Applies coupling and filtering options to the trigger signal. Refer to NISCOPE_ATTR_TRIGGER_COUPLING for more information.
holdoff ViReal64 The length of time the digitizer waits after detecting a trigger before enabling NI-SCOPE to detect another trigger. Refer to NISCOPE_ATTR_TRIGGER_HOLDOFF for more information.
delay ViReal64 How long the digitizer waits after receiving the trigger to start acquiring data. Refer to NISCOPE_ATTR_TRIGGER_DELAY_TIME for more information.

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_SendSoftwareTriggerEdge

C Function Prototype

ViStatus niScope_SendSoftwareTriggerEdge (ViSession vi, ViInt32 whichTrigger);

Purpose

Sends the selected trigger to the digitizer. Call this function if you called niScope_ConfigureTriggerSoftware when you want the Reference trigger to occur. You can also call this function to override a misused edge, digital, or hysteresis trigger. If you have configured NISCOPE_ATTR_ACQ_ARM_SOURCE, NISCOPE_ATTR_ARM_REF_TRIG_SRC, or NISCOPE_ATTR_ADV_TRIG_SRC, call this function when you want to send the corresponding trigger to the digitizer.

Related topics:

  • Software Triggers

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
whichTrigger ViInt32

Specifies the type of trigger to send to the digitizer.

Defined Values

NISCOPE_VAL_SOFTWARE_TRIGGER_START (0L)
NISCOPE_VAL_SOFTWARE_TRIGGER_ARM_REFERENCE (1L)
NISCOPE_VAL_SOFTWARE_TRIGGER_REFERENCE (2L)
NISCOPE_VAL_SOFTWARE_TRIGGER_ADVANCE (3L)

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_AdjustSampleClockRelativeDelay

C Function Prototype

ViStatus niScope_AdjustSampleClockRelativeDelay(ViSession vi, ViReal64 delay);

Purpose

Applies offset, in seconds, to the sample clock relative to the reference clock when using the onboard clock.

Each time this function is called, the sample clock is offset from the reference clock by the specified amount of time.

Adjustment range: ±1 Sample Clock Period

Programming Patterns

Use this function when performing manual adjustment to correct for skew and jitter between oscilloscopes synchronized with NI-TClk.

  1. Apply time offset with this function to reduce skew and/or jitter.
  2. Use the NISCOPE_ATTR_OSCILLATOR_PHASE_DAC_VALUE attribute to convert this time offset into a value that can apply the manual adjustment across sessions and improve synchronization repeatability.

For details on performing manual adjustment, refer to Improving NI-TClk Synchronization of Oscilloscopes with Manual Adjustment.

Related topics:

  • Improving NI-TClk Synchronization of Oscilloscopes with Manual Adjustment
  • Sample Clock
  • Reference Clock/Phase-Lock Loop
  • NI-TClk Overview

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
delay ViReal64 How long the digitizer waits after receiving the trigger to start acquiring data. Refer to NISCOPE_ATTR_TRIGGER_DELAY_TIME for more information.

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_ConfigureClock

C Function Prototype

ViStatus niScope_ConfigureClock (ViSession vi, ViConstString inputClockSource, ViConstString outputClockSource, ViConstString clockSyncPulseSource, ViBoolean masterEnabled);

Purpose

Configures the attributes for synchronizing the digitizer to a reference or sending the digitizer's reference clock output to be used as a synchronizing clock for other digitizers.

Note  Some features are not supported by all digitizers. Refer to Features Supported by Device) for more information.

Related topics:

  • Sample Clock
  • Sample Rate
  • Coercions of Horizontal Parameters

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
inputClockSource ViConstString Specifies the input source for the PLL reference clock (such as the 1-20 MHz clock on SMC-based devices) to which the digitizer is phase-locked for all digitizers. Refer to NISCOPE_ATTR_INPUT_CLOCK_SOURCE for more information.
outputClockSource ViConstString Specifies the output source for the reference clock to which the sample clock of another oscilloscope can be phase-locked. Refer to NISCOPE_ATTR_OUTPUT_CLOCK_SOURCE for more information
clockSyncPulseSource ViConstString Specifies the line on which the sample clock or the one-time sync pulse is sent or received. This line should be the same for all devices to be synchronized. Refer to NISCOPE_ATTR_CLOCK_SYNC_PULSE_SOURCE for more information.
masterEnabled ViBoolean Specifies whether the device is a master or a slave. The master device is typically the originator of the trigger signal and the clock sync pulse. For a standalone device, set this control to VI_FALSE.

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_ExportSignal

C Function Prototype

ViStatus niScope_ExportSignal (ViSession vi, ViInt32 signal, ViConstString signalIdentifier, ViConstString outputTerminal);

Purpose

Note  This function replaces niScope_ConfigureTriggerOutput.
Configures the digitizer to generate a signal that other devices can detect when configured for digital triggering or sharing clocks. The signal parameter specifies what condition causes the digitizer to generate the signal. The outputTerminal parameter specifies where to send the signal on the hardware (such as a PFI connector or RTSI line).

In cases where multiple instances of a particular signal exist, use the signalIdentifier input to specify which instance to control. For normal signals, only one instance exists and you should leave this parameter set to the empty string. You can call this function multiple times and set each available line to a different signal.

To unprogram a specific line on device, call this function with the signal you no longer want to export and set outputTerminal to NISCOPE_VAL_NONE.

Related topics:

  • Triggering
  • SMC-Based Digitizers Acquisition Engine State Diagram
  • PXI Trigger Lines

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
signal ViInt32

Signal (clock, trigger, or event) to export.

Defined Values
NISCOPE_VAL_REF_TRIGGER (1) Generate a pulse when detecting the Stop/Reference trigger.
NISCOPE_VAL_START_TRIGGER (2) Generate a pulse when detecting a Start trigger.
NISCOPE_VAL_END_OF_ACQUISITION_EVENT (3) Generate a pulse when the acquisition finishes.
NISCOPE_VAL_END_OF_RECORD_EVENT (4) Generate a pulse at the end of the record.
NISCOPE_VAL_ADVANCE_TRIGGER (5) Generate a pulse when detecting an Advance trigger.
NISCOPE_VAL_READY_FOR_ADVANCE_EVENT (6) Asserts when the digitizer is ready to advance to the next record.
NISCOPE_VAL_READY_FOR_START_EVENT (7) Asserts when the digitizer is initiated and ready to accept a Start trigger and begin sampling.
NISCOPE_VAL_READY_FOR_REF_EVENT (10) Asserts when the digitizer is ready to accept a Reference trigger.
NISCOPE_VAL_REF_CLOCK (100) Export the Reference clock for the digitizer to the specified terminal.
NISCOPE_VAL_SAMPLE_CLOCK (101) Export the Sample clock for the digitizer to the specified terminal.
NISCOPE_VAL_5V_OUT (13) Exports a 5 V power supply.
signalIdentifier ViConstString Describes the signal being exported.
outputTerminal ViConstString

Identifies the hardware signal line on which the digital pulse is generated.

Defined Values
NISCOPE_VAL_RTSI_0 ("VAL_RTSI_0")
NISCOPE_VAL_RTSI_1 ("VAL_RTSI_1")
NISCOPE_VAL_RTSI_2 ("VAL_RTSI_2")
NISCOPE_VAL_RTSI_3 ("VAL_RTSI_3")
NISCOPE_VAL_RTSI_4 ("VAL_RTSI_4")
NISCOPE_VAL_RTSI_5 ("VAL_RTSI_5")
NISCOPE_VAL_RTSI_6 ("VAL_RTSI_6")
NISCOPE_VAL_RTSI_7 ("VAL_RTSI_7")
NISCOPE_VAL_PXI_STAR ("VAL_PXI_STAR")
NISCOPE_VAL_PFI_0 ("VAL_PFI_0")
NISCOPE_VAL_PFI_1 ("VAL_PFI_1")
NISCOPE_VAL_PFI_2 ("VAL_PFI_2")
NISCOPE_VAL_CLK_OUT ("VAL_CLK_OUT")

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_GetEqualizationFilterCoefficients

C Function Prototype

ViStatus _VI_FUNC niScope_GetEqualizationFilterCoefficients (ViSession vi, ViConstString channel, ViInt32 numberOfCoefficients, ViReal64* coefficients);

Purpose

Retrieves the custom coefficients for the equalization FIR filter on the device. This filter is designed to compensate the input signal for artifacts introduced to the signal outside of the digitizer. Because this filter is a generic FIR filter, any coefficients are valid. Coefficient values should be between +1 and –1.

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
channel ViConstString The channel to configure. For more information, refer to Channel String Syntax.
numberOfCoefficients ViInt32 The number of coefficients being passed in the coefficients array.
Output
Name Type Description
coefficients ViReal64* The custom coefficients for the equalization FIR filter on the device. These coefficients should be between +1 and –1. You can obtain the number of coefficients from the NISCOPE_ATTR_EQUALIZATION_NUM_COEFFICIENTS attribute.

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_GetFrequencyResponse

ViStatus _VI_FUNC niScope_GetFrequencyResponse (ViSession vi, ViConstString channelName, ViInt32 bufferSize, ViReal64 frequencies[], ViReal64 amplitudes[], ViReal64 phases[], ViInt32* numberOfFrequencies);

Purpose

Gets the frequency response of the digitizer for the current configurations of the channel attributes. Not all digitizers support this function.

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
channel ViConstString The channel to configure. For more information, refer to Channel String Syntax.
bufferSize ViInt32

The array size for the frequencies, amplitudes, and phases arrays that you pass in to the other parameters.

To determine the sizes of the buffers to allocate for the frequencies, amplitudes, and phases arrays, pass a value of 0 to the bufferSize parameter and a value of NULL to the frequencies parameter. In this case, the value returned by the numberOfFrequencies parameter is the size of the arrays necessary to hold the frequencies, amplitudes, and phases. Allocate three arrays of this size, then call this function again (with correct bufferSize parameter) to retrieve the actual values.
Output
Name Type Description
frequencies ViReal64 The array of frequencies that corresponds with the amplitude and phase response of the device.
amplitudes ViReal64 The array of amplitudes that correspond with the magnitude response of the device.
phases ViReal64 The array of phases that correspond with the phase response of the device.
numberOfFrequencies ViInt32 Returns the number of frequencies in the returned spectrum.

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_ConfigureEqualizationFilterCoefficients

C Function Prototype

ViStatus _VI_FUNC niScope_ConfigureEqualizationFilterCoefficients (ViSession vi, ViConstString channel, ViInt32 numberOfCoefficients, ViReal64* coefficients);

Purpose

Configures the custom coefficients for the equalization FIR filter on the device. This filter is designed to compensate the input signal for artifacts introduced to the signal outside of the digitizer. Because this filter is a generic FIR filter, any coefficients are valid. Coefficient values should be between +1 and –1.

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.
numberOfCoefficients ViInt32 The number of coefficients being passed in the coefficients array.
coefficients ViReal64* The custom coefficients for the equalization FIR filter on the device. These coefficients should be between +1 and –1. You can obtain the number of coefficients from the NISCOPE_ATTR_EQUALIZATION_NUM_COEFFICIENTS attribute. The NISCOPE_ATTR_EQUALIZATION_FILTER_ENABLED attribute must be set to TRUE to enable the filter.

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_ImportAttributeConfigurationFile

ViStatus niScope_ImportAttributeConfigurationFile (ViSession vi, ViConstString filePath);

Purpose

Imports an attribute configuration to the session from the specified file.

You can export and import session attribute configurations only between NISCOPE devices with identical bus types, model numbers, channel counts, and onboard memory sizes and between NI-SCOPE sessions with the same number of initialized channels..

!Note Note  You cannot call this function while the session is in a running state, such as while acquiring a signal.
Device Mapping Behavior

When exporting and importing configurations between NISCOPE sessions that were both initialized with multiple instruments, the configurations of the exporting instruments are mapped to the importing instruments in the order you specify in the resourceName input to the niScope_InitWithOptions or niScope_init functions.

For example, if your entry for resourceName is PXI1Slot1,PXI1Slot2 for the exporting session and PXI2Slot2,PXI2Slot3 for the importing session:

  • The configuration exported from PXI1Slot1 is imported into PXI2Slot2.
  • The configuration exported from PXI1Slot2 is imported into PXI2Slot3.
!Note Note  NI-SCOPE will return an error if the total number of channels initialized for the exporting session is not equal to the total number of channels initialized for the importing session.
Related Topics:

Attributes and Attribute Functions

Setting Attributes Before Reading Attributes

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
filePath ViConstString The absolute path to the file that contains the attribute configuration to import. If you specify an empty or relative path, this function returns an error.

Default File Extension: .niscopeconfig

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_ExportAttributeConfigurationFile

ViStatus niScope_ExportAttributeConfigurationFile (ViSession vi, ViConstString filePath);

Purpose

Exports the attribute configuration of the session to the specified file.

You can export and import session attribute configurations only between NISCOPE devices with identical bus types, model numbers, channel counts, and onboard memory sizes and between NI-SCOPE sessions with the same number of initialized channels.

This function verifies that the attributes you have configured for the session are valid. If the configuration is invalid, NI-SCOPE returns an error.

Device Mapping Behavior

When exporting and importing configurations between NISCOPE sessions that were both initialized with multiple instruments, the configurations of the exporting instruments are mapped to the importing instruments in the order you specify in the resourceName input to the niScope_InitWithOptions or niScope_init functions.

For example, if your entry for resourceName is PXI1Slot1,PXI1Slot2 for the exporting session and PXI2Slot2,PXI2Slot3 for the importing session:

  • The configuration exported from PXI1Slot1 is imported into PXI2Slot2.
  • The configuration exported from PXI1Slot2 is imported into PXI2Slot3.
!Note Note  NI-SCOPE will return an error if the total number of channels initialized for the exporting session is not equal to the total number of channels initialized for the importing session.
Related Topics:

Attributes and Attribute Functions

Setting Attributes Before Reading Attributes

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
filePath ViConstString The absolute path to a placeholder file you must create to contain the attribute configuration you want to export. If you specify an empty or relative path, this function returns an error.

Default file extension: .niscopeconfig

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_ImportAttributeConfigurationBuffer

ViStatus niScope_ImportAttributeConfigurationBuffer (ViSession vi, ViInt32 size, ViAddr configuration);

Purpose

Imports an attribute configuration to the session from the specified buffer.

You can export and import session attribute configurations only between NISCOPE devices with identical bus types, model numbers, channel counts, and onboard memory sizes and between NI-SCOPE sessions with the same number of initialized channels.

!Note Note  You cannot call this function while the session is in a running state, such as while acquiring a signal.
Device Mapping Behavior

When exporting and importing configurations between NISCOPE sessions that were both initialized with multiple instruments, the configurations of the exporting instruments are mapped to the importing instruments in the order you specify in the resourceName input to the niScope_InitWithOptions or niScope_init functions.

For example, if your entry for resourceName is PXI1Slot1,PXI1Slot2 for the exporting session and PXI2Slot2,PXI2Slot3 for the importing session:

  • The configuration exported from PXI1Slot1 is imported into PXI2Slot2.
  • The configuration exported from PXI1Slot2 is imported into PXI2Slot3.
!Note Note  NI-SCOPE will return an error if the total number of channels initialized for the exporting session is not equal to the total number of channels initialized for the importing session.
Related Topics:

Attributes and Attribute Functions

Setting Attributes Before Reading Attributes

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
size ViInt32 Specifies the size, in bytes, of the byte array to import. If you enter 0, this function returns the needed size.
configuration ViAddr Specifies the byte array that contains the attribute configuration to import.

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_ExportAttributeConfigurationBuffer

ViStatus niScope_ExportAttributeConfigurationBuffer (ViSession vi, ViInt32 size, ViAddr configuration);

Purpose

Exports the attribute configuration of the session to a buffer.

You can export and import session attribute configurations only between NISCOPE devices with identical bus types, model numbers, channel counts, and onboard memory sizes and between NI-SCOPE sessions with the same number of initialized channels.

This function verifies that the attributes you have configured for the session are valid. If the configuration is invalid, NI-SCOPE returns an error.

Device Mapping Behavior

When exporting and importing configurations between NISCOPE sessions that were both initialized with multiple instruments, the configurations of the exporting instruments are mapped to the importing instruments in the order you specify in the resourceName input to the niScope_InitWithOptions or niScope_init functions.

For example, if your entry for resourceName is PXI1Slot1,PXI1Slot2 for the exporting session and PXI2Slot2,PXI2Slot3 for the importing session:

  • The configuration exported from PXI1Slot1 is imported into PXI2Slot2.
  • The configuration exported from PXI1Slot2 is imported into PXI2Slot3.
!Note Note  NI-SCOPE will return an error if the total number of channels initialized for the exporting session is not equal to the total number of channels initialized for the importing session.
Related Topics:

Attributes and Attribute Functions

Setting Attributes Before Reading Attributes

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
size ViInt32 Specifies the size, in bytes, of the byte array to export. If you enter 0, this function returns the needed size.
configuration ViAddr Specifies the byte array that contains the exported configuration.

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

Home

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-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