NI FGEN Frequency List Output Functions

Frequency List Output Functions

• niFgen_CreateFreqList
• niFgen_ConfigureFreqList
• niFgen_ClearFreqList
• niFgen_QueryFreqListCapabilities

niFgen_CreateFreqList

ViStatus niFgen_CreateFreqList (ViSession vi, ViInt32 waveform, ViInt32 frequencyListLength, ViReal64[] frequencyArray, ViReal64[] durationArray, ViInt32* frequencyListHandle);

Purpose

Creates a frequency list from an array of frequencies (frequencyArray) and an array of durations (durationArray). The two arrays should have the same number of elements, and this value must also be the size of the frequencyListLength. The function returns a handle that identifies the frequency list (the frequencyListHandle). You can pass this handle to niFgen_ConfigureFreqList to specify what frequency list you want the signal generator to produce.

Note:  The signal generator must not be in the Generating state when you call this function.

You must call the niFgen_ConfigureOutputMode function to set the outputMode parameter to NIFGEN_VAL_OUTPUT_FREQ_LIST before calling this function. A frequency list consists of a list of frequencies and durations. The signal generator generates each frequency for the given amount of time and then proceeds to the next frequency. When the end of the list is reached, the signal generator starts over at the beginning of the list.

Parameters

Input
Name	Type	Description
vi	ViSession	Identifies your instrument session. vi is obtained from the niFgen_init, niFgen_InitWithOptions, or niFgen_InitializeWithChannels functions and identifies a particular instrument session.
waveform	ViInt32	Specifies the standard waveform that you want the signal generator to produce. NI-FGEN sets the NIFGEN_ATTRIBUTE_FUNC_WAVEFORM attribute to this value. Default Value: NIFGEN_VAL_WFM_SINE Defined Values

NIFGEN_VAL_WFM_SINE	Specifies that the signal generator produces a sinusoid waveform.
NIFGEN_VAL_WFM_SQUARE	Specifies that the signal generator produces a square waveform.
NIFGEN_VAL_WFM_TRIANGLE	Specifies that the signal generator produces a triangle waveform.
NIFGEN_VAL_WFM_RAMP_UP	Specifies that the signal generator produces a positive ramp waveform.
NIFGEN_VAL_WFM_RAMP_DOWN	Specifies that the signal generator produces a negative ramp waveform.
NIFGEN_VAL_WFM_DC	Specifies that the signal generator produces a constant voltage.
NIFGEN_VAL_WFM_NOISE	Specifies that the signal generator produces white noise.
NIFGEN_VAL_WFM_USER	Specifies that the signal generator produces a user-defined waveform as defined with the niFgen_DefineUserStandardWaveform function.

Name	Type	Description
frequencyListLength	ViInt32	Specifies the number of steps in the frequency list you want to create. The value must be between the minimum and maximum frequency list lengths that the signal generator allows. You can obtain the minimum and maximum frequency list lengths from the minimumFrequencyListLength and maximumFrequencyListLength parameters in the niFgen_QueryFreqListCapabilities function. frequency and duration must each be at least as long as this frequency list length. Default Value: None
frequencyArray	ViReal64[]	Specifies the array of frequencies to form the frequency list. The array must have at least as many elements as the value you specify in frequencyListLength. Each frequencyArray element has a corresponding durationArray element that indicates how long that frequency is repeated. Units: hertz Default Value: None
durationArray	ViReal64[]	Specifies the array of durations to form the frequency list. The array must have at least as many elements as the value that you specify in frequencyListLength. Each durationArray element has a corresponding frequencyArray element and indicates how long in seconds to generate the corresponding frequency. Units: seconds Default Value: None
Output
Name	Type	Description
frequencyListHandle	ViInt32*	Returns the handle that identifies the new frequency list. You can pass this handle to niFgen_ConfigureFreqList to generate the arbitrary sequence.

Return Value

Name	Type	Description
status	ViStatus	Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You can examine the status code from each call to an NI-FGEN function to determine if an error occurred. To obtain a text description of the status code, call the niFgen_error_message function. To obtain additional information about the error condition, call the niFgen_GetError function. To clear the error information from NI-FGEN, call the niFgen_ClearError function. The general meaning of the status code is as follows:

Value	Meaning
0	Success
Positive Values	Warnings
Negative Values	Errors

niFgen_ConfigureFreqList

ViStatus niFgen_ConfigureFreqList (ViSession vi, ViConstString channelName, ViInt32 frequencyListHandle, ViReal64 amplitude, ViReal64 dcOffset, ViReal64 startPhase);

Purpose

Configures the attributes of the signal generator that affect frequency list generation (the NIFGEN_ATTRIBUTE_FREQ_LIST_HANDLE, NIFGEN_ATTRIBUTE_FUNC_AMPLITUDE, NIFGEN_ATTRIBUTE_FUNC_DC_OFFSET, and NIFGEN_ATTRIBUTE_FUNC_START_PHASE attributes).

Note:  The signal generator must not be in the Generating state when you call this function.

You must call the niFgen_ConfigureOutputMode function to set the outputMode parameter to NIFGEN_VAL_OUTPUT_FREQ_LIST before calling this function.

Parameters

Input
Name	Type	Description
vi	ViSession	Identifies your instrument session. vi is obtained from the niFgen_init, niFgen_InitWithOptions, or niFgen_InitializeWithChannels functions and identifies a particular instrument session.
channelName	ViConstString	Specifies the channel name for which you want to configure the frequency list. Default Value: "0"
frequencyListHandle	ViInt32	Specifies the handle of the frequency list that you want the signal generator to produce. NI-FGEN sets the NIFGEN_ATTRIBUTE_FREQ_LIST_HANDLE attribute to this value. You can create a frequency list using the niFgen_CreateFreqList function, which returns a handle that you use to identify the list. Default Value: None
amplitude	ViReal64	Specifies the amplitude of the standard waveform that you want the signal generator to produce. This value is the amplitude at the output terminal. NI-FGEN sets the NIFGEN_ATTRIBUTE_FUNC_AMPLITUDE attribute to this value. For example, to produce a waveform ranging from –5.00 V to +5.00 V, set the amplitude to 10.00 V. Units: peak-to-peak voltage Default Value: None Note:   This parameter does not affect signal generator behavior when you set the waveform parameter of the niFgen_ConfigureStandardWaveform function to NIFGEN_VAL_WFM_DC.
dcOffset	ViReal64	Specifies the DC offset of the standard waveform that you want the signal generator to produce. The value is the offset from ground to the center of the waveform you specify with the waveform parameter, observed at the output terminal. For example, to configure a waveform with an amplitude of 10.00 V to range from 0.00 V to +10.00 V, set the dcOffset to 5.00 V. NI-FGEN sets the NIFGEN_ATTRIBUTE_FUNC_DC_OFFSET attribute to this value. Units: volts Default Value: None
startPhase	ViReal64	Specifies the horizontal offset of the standard waveform you want the signal generator to produce. Specify this attribute in degrees of one waveform cycle. NI-FGEN sets theNIFGEN_ATTRIBUTE_FUNC_START_PHASE attribute to this value. A start phase of 180 degrees means output generation begins halfway through the waveform. A start phase of 360 degrees offsets the output by an entire waveform cycle, which is identical to a start phase of 0 degrees. Units: degrees of one cycle Default Value: None degrees Note:   This parameter does not affect signal generator behavior when you set the waveform parameter to NIFGEN_VAL_WFM_DC.

Return Value

Name	Type	Description
status	ViStatus	Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You can examine the status code from each call to an NI-FGEN function to determine if an error occurred. To obtain a text description of the status code, call the niFgen_error_message function. To obtain additional information about the error condition, call the niFgen_GetError function. To clear the error information from NI-FGEN, call the niFgen_ClearError function. The general meaning of the status code is as follows:

Value	Meaning
0	Success
Positive Values	Warnings
Negative Values	Errors

niFgen_ClearFreqList

ViStatus niFgen_ClearFreqList (ViSession vi, ViInt32 frequencyListHandle);

Purpose

Removes a previously created frequency list from the signal generator memory and invalidates the frequency list handle.

Note:   The signal generator must not be in the Generating state when you call this function.

Parameters

Input
Name	Type	Description
vi	ViSession	Identifies your instrument session. vi is obtained from the niFgen_init, niFgen_InitWithOptions, or niFgen_InitializeWithChannels functions and identifies a particular instrument session.
frequencyListHandle	ViInt32	Specifies the handle of the frequency list you want the signal generator to remove. You create multiple frequency lists using niFgen_CreateFreqList. niFgen_CreateFreqList returns a handle that you use to identify each list. Specify a value of -1 to clear all frequency lists. Defined Value NIFGEN_VAL_ALL_FLISTS — Remove all frequency lists from the signal generator. Default Value: None

Return Value

Name	Type	Description
status	ViStatus	Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You can examine the status code from each call to an NI-FGEN function to determine if an error occurred. To obtain a text description of the status code, call the niFgen_error_message function. To obtain additional information about the error condition, call the niFgen_GetError function. To clear the error information from NI-FGEN, call the niFgen_ClearError function. The general meaning of the status code is as follows:

Value	Meaning
0	Success
Positive Values	Warnings
Negative Values	Errors

niFgen_QueryFreqListCapabilities

ViStatus niFgen_QueryFreqListCapabilities (ViSession vi, ViInt32* maximumNumberOfFreqLists, ViInt32* minimumFrequencyListLength, ViInt32* maximumFrequencyListLength, ViReal64* minimumFrequencyListDuration, ViReal64* maximumFrequencyListDuration, ViReal64* frequencyListDurationQuantum);

Purpose

Returns the attributes of the signal generator that are related to creating frequency lists. These attributes are NIFGEN_ATTRIBUTE_MAX_NUM_FREQ_LISTS, NIFGEN_ATTRIBUTE_MIN_FREQ_LIST_LENGTH, NIFGEN_ATTRIBUTE_MAX_FREQ_LIST_LENGTH, NIFGEN_ATTRIBUTE_MIN_FREQ_LIST_DURATION, NIFGEN_ATTRIBUTE_MAX_FREQ_LIST_DURATION, and NIFGEN_ATTRIBUTE_FREQ_LIST_DURATION_QUANTUM.

Parameters

Input
Name	Type	Description
vi	ViSession	Identifies your instrument session. vi is obtained from the niFgen_init, niFgen_InitWithOptions, or niFgen_InitializeWithChannels functions and identifies a particular instrument session.
Output
Name	Type	Description
maximumNumberOfFreqLists	ViInt32	Returns the maximum number of frequency lists that the signal generator allows. NI-FGEN obtains this value from the NIFGEN_ATTRIBUTE_MAX_NUM_FREQ_LISTS attribute.
minimumFrequencyListLength	ViInt32	Returns the minimum number of steps that the signal generator allows in a frequency list. NI-FGEN obtains this value from the NIFGEN_ATTRIBUTE_MIN_FREQ_LIST_LENGTH attribute.
maximumFrequencyListLength	ViInt32	Returns the maximum number of steps that the signal generator allows in a frequency list. NI-FGEN obtains this value from the NIFGEN_ATTRIBUTE_MAX_FREQ_LIST_LENGTH attribute.
minimumFrequencyListDuration	ViReal64	Returns the minimum duration that the signal generator allows in a step of a frequency list. NI-FGEN obtains this value from the[NIFGEN_ATTRIBUTE_MIN_FREQ_LIST_DURATION attribute.
maximumFrequencyListDuration	ViReal64	Returns the maximum duration that the signal generator allows in a step of a frequency list. NI-FGEN obtains this value from the NIFGEN_ATTRIBUTE_MAX_FREQ_LIST_DURATION attribute.
frequencyListDurationQuantum	ViReal64	Returns the quantum of which all durations must be a multiple in a frequency list. NI-FGEN obtains this value from the NIFGEN_ATTRIBUTE_FREQ_LIST_DURATION_QUANTUM attribute.

Return Value

Name	Type	Description
status	ViStatus	Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You can examine the status code from each call to an NI-FGEN function to determine if an error occurred. To obtain a text description of the status code, call the niFgen_error_message function. To obtain additional information about the error condition, call the niFgen_GetError function. To clear the error information from NI-FGEN, call the niFgen_ClearError function. The general meaning of the status code is as follows:

Value	Meaning
0	Success
Positive Values	Warnings
Negative Values	Errors