NI FGEN Arbitrary Sequence Output Functions

Arbitrary Sequence Output Functions

• niFgen_QueryArbSeqCapabilities
• niFgen_CreateArbSequence
• niFgen_CreateAdvancedArbSequence
• niFgen_ConfigureArbSequence
• niFgen_ClearArbSequence
• niFgen_ClearArbMemory

niFgen_QueryArbSeqCapabilities

ViStatus niFgen_QueryArbSeqCapabilities (ViSession vi, ViInt32* maximumNumberofSequences, ViInt32* minimumSequenceLength, ViInt32* maximumSequenceLength, ViInt32* maximumLoopCount);

Purpose

Returns the attributes of the signal generator that are related to creating arbitrary sequences (the NIFGEN_ATTRIBUTE_MAX_NUM_SEQUENCES, NIFGEN_ATTRIBUTE_MIN_SEQUENCE_LENGTH, NIFGEN_ATTRIBUTE_MAX_SEQUENCE_LENGTH, and NIFGEN_ATTRIBUTE_MAX_LOOP_COUNT attributes).

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
maximumNumberofSequences	ViInt32*	Returns the maximum number of arbitrary waveform sequences that the signal generator allows. NI-FGEN obtains this value from the NIFGEN_ATTRIBUTE_MAX_NUM_SEQUENCES attribute.
minimumSequenceLength	ViInt32*	Returns the minimum number of arbitrary waveforms the signal generator allows in a sequence. NI-FGEN obtains this value from the NIFGEN_ATTRIBUTE_MIN_SEQUENCE_LENGTH attribute.
maximumSequenceLength	ViInt32*	Returns the maximum number of arbitrary waveforms the signal generator allows in a sequence. NI-FGEN obtains this value from the NIFGEN_ATTRIBUTE_MAX_SEQUENCE_LENGTH attribute.
maximumLoopCount	ViInt32*	Returns the maximum number of times the signal generator can repeat an arbitrary waveform in a sequence. NI-FGEN obtains this value from the NIFGEN_ATTRIBUTE_MAX_LOOP_COUNT 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

niFgen_CreateArbSequence

ViStatus niFgen_CreateArbSequence (ViSession vi, ViInt32 sequenceLength, ViInt32[] waveformHandlesArray, ViInt32[] loopCountsArray, ViInt32* sequenceHandle);

Purpose

Creates an arbitrary sequence from an array of waveform handles and an array of corresponding loop counts. This function returns a handle that identifies the sequence. You pass this handle to the niFgen_ConfigureArbSequence function to specify what arbitrary sequence you want the signal generator to produce.

Note:  You must call the niFgen_ConfigureOutputMode function to set the outputMode parameter to NIFGEN_VAL_OUTPUT_SEQ before calling this function.

An arbitrary sequence consists of multiple waveforms. For each waveform, you can specify the number of times that the signal generator produces the waveform before proceeding to the next waveform. The number of times to repeat a specific waveform is called the loop count.

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.
sequenceLength	ViInt32	Specifies the number of waveforms in the new arbitrary sequence that you want to create. The value you pass must be between the minimum and maximum sequence lengths that the signal generator allows. You can obtain the minimum and maximum sequence lengths from minimumSequenceLength and maximumSequenceLength in the niFgen_QueryArbSeqCapabilitiesfunction. Default Value: None
waveformHandlesArray	ViInt32[]	Specifies the array of waveform handles from which you want to create a new arbitrary sequence. The array must have at least as many elements as the value that you specify in sequenceLength. Each waveformHandlesArray element has a corresponding loopCountsArray element that indicates how many times that waveform is repeated. You obtain waveform handles when you create arbitrary waveforms with the niFgen_AllocateWaveform function or one of the following niFgen CreateWaveform functions: - niFgen_CreateWaveformF64 - niFgen_CreateWaveformI16 - niFgen_CreateWaveformFromFileI16 - niFgen_CreateWaveformFromFileF64 - niFgen_CreateWaveformFromFileHWS Default Value: None
loopCountsArray	ViInt32[]	Specifies the array of loop counts you want to use to create a new arbitrary sequence. The array must have at least as many elements as the value that you specify in the sequenceLength parameter. Each loopCountsArray element corresponds to a waveformHandlesArray element and indicates how many times to repeat that waveform. Each element of the loopCountsArray must be less than or equal to the maximum number of loop counts that the signal generator allows. You can obtain the maximum loop count from maximumLoopCount in the niFgen_QueryArbSeqCapabilities function. Default Value: None
Output
Name	Type	Description
sequenceHandle	ViInt32*	Returns the handle that identifies the new arbitrary sequence. You can pass this handle to niFgen_ConfigureArbSequence 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_CreateAdvancedArbSequence

ViStatus niFgen_CreateAdvancedArbSequence (ViSession vi, ViInt32 sequenceLength, ViInt32[] waveformHandlesArray, ViInt32[] loopCountsArray, ViInt32[] sampleCountsArray, ViInt32[] markerLocationArray, ViInt32[] coercedMarkersArray, ViInt32* sequenceHandle);

Purpose

Creates an arbitrary sequence from an array of waveform handles and an array of corresponding loop counts. This function returns a handle that identifies the sequence. You pass this handle to the niFgen_ConfigureArbSequence function to specify what arbitrary sequence you want the signal generator to produce.

The niFgen_CreateAdvancedArbSequence function extends on the niFgen_CreateArbSequence function by adding the ability to set the number of samples in each sequence step and to set marker locations.

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_SEQ before calling this function.

An arbitrary sequence consists of multiple waveforms. For each waveform, you specify the number of times the signal generator produces the waveform before proceeding to the next waveform. The number of times to repeat a specific waveform is called the loop count.

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.
sequenceLength	ViInt32	Specifies the number of waveforms in the new arbitrary sequence that you want to create. The value you pass must be between the minimum and maximum sequence lengths that the signal generator allows. You can obtain the minimum and maximum sequence lengths from minimumSequenceLength and maximumSequenceLength in the niFgen_QueryArbSeqCapabilities function. Default Value: None
waveformHandlesArray	ViInt32[]	Specifies the array of waveform handles from which you want to create a new arbitrary sequence. The array must have at least as many elements as the value that you specify in sequenceLength. Each waveformHandlesArray element has a corresponding loopCountsArray element that indicates how many times that waveform is repeated. You obtain waveform handles when you create arbitrary waveforms with the niFgen_AllocateWaveform function or one of the following niFgen CreateWaveform functions: - niFgen_CreateWaveformF64 - niFgen_CreateWaveformI16 - niFgen_CreateWaveformFromFileI16 - niFgen_CreateWaveformFromFileF64 - niFgen_CreateWaveformFromFileHWS Default Value: None
loopCountsArray	ViInt32[]	Specifies the array of loop counts you want to use to create a new arbitrary sequence. The array must have at least as many elements as the value that you specify in the sequenceLength parameter. Each loopCountsArray element corresponds to a waveformHandlesArray element and indicates how many times to repeat that waveform. Each element of the loopCountsArray must be less than or equal to the maximum number of loop counts that the signal generator allows. You can obtain the maximum loop count from maximumLoopCount in the niFgen_QueryArbSeqCapabilities function. Default Value: None
sampleCountsArray	ViInt32[]	Specifies the array of sample counts that you want to use to create a new arbitrary sequence. The array must have at least as many elements as the value you specify in the sequenceLength parameter. Each sampleCountsArray element corresponds to a waveformHandlesArray element and indicates the subset, in samples, of the given waveform to generate. Each element of the sampleCountsArray must be larger than the minimum waveform size, a multiple of the waveform quantum and no larger than the number of samples in the corresponding waveform. You can obtain these values by calling the niFgen_QueryArbWfmCapabilities function. Default Value: None
markerLocationArray	ViInt32[]	Specifies the array of marker locations to where you want a marker to be generated in the sequence. The array must have at least as many elements as the value you specify in the sequenceLength parameter. Each markerLocationArray element corresponds to a waveformHandlesArray element and indicates where in the waveform a marker is to generate. The marker location must be less than the size of the waveform the marker is in. The markers are coerced to the nearest marker quantum and the coerced values are returned in the coercedMarkersArray parameter. If you do not want a marker generated for a particular sequence stage, set this parameter to -1. Default Value: None
Output
Name	Type	Description
coercedMarkersArray	ViInt32[]	Returns an array of all given markers that are coerced (rounded) to the nearest marker quantum. Not all devices coerce markers. Default Value: None
sequenceHandle	ViInt32*	Returns the handle that identifies the new arbitrary sequence. You can pass this handle to niFgen_ConfigureArbSequence 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_ConfigureArbSequence

ViStatus niFgen_ConfigureArbSequence (ViSession vi, VViConstString channelName, ViInt32 sequenceHandle, ViReal64 gain, ViReal64 offset;

Purpose

Configures the signal generator attributes that affect arbitrary sequence generation. Sets the NIFGEN_ATTRIBUTE_ARB_SEQUENCE_HANDLE, NIFGEN_ATTRIBUTE_ARB_GAIN, and NIFGEN_ATTRIBUTE_ARB_OFFSET 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_SEQ 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 from which you want to configure an arbitrary sequence. Default Value: "0"
sequenceHandle	ViInt32	Specifies the handle of the arbitrary sequence that you want the signal generator to produce. NI-FGEN sets the NIFGEN_ATTRIBUTE_ARB_SEQUENCE_HANDLE attribute to this value. You can create an arbitrary sequence using the niFgen_CreateArbSequence or niFgen_CreateAdvancedArbSequence function. These functions return a handle that you use to identify the sequence. Default Value: None
gain	ViReal64	Specifies the factor by which the signal generator scales the arbitrary waveforms in the sequence. When you create an arbitrary waveform, you must first normalize the data points to a range of –1.00 to +1.00. You can use this parameter to scale the waveform to other ranges. The gain is applied before the offset is added. For example, to configure the output signal to range from –2.00 to +2.00 V, set gain to 2.00. Units: unitless Default Value: None
offset	ViReal64	Specifies the value the signal generator adds to the arbitrary waveform data. When you create arbitrary waveforms, you must first normalize the data points to a range of –1.00 to +1.00 V. You can use this parameter to shift the range of the arbitrary waveform. NI-FGEN sets the NIFGEN_ATTRIBUTE_ARB_OFFSET attribute to this value. For example, to configure the output signal to range from 0.00 to 2.00 V instead of –1.00 to 1.00 V, set the offset to 1.00. Units: volts 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_ClearArbSequence

ViStatus niFgen_ClearArbSequence (ViSession vi, ViInt32 sequenceHandle);

Purpose

Removes a previously created arbitrary sequence from the signal generator memory and invalidates the sequence 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.
sequenceHandle	ViInt32	Specifies the handle of the arbitrary sequence that you want the signal generator to remove. You can create an arbitrary sequence using the niFgen_CreateArbSequence or niFgen_CreateAdvancedArbSequence function. These functions return a handle that you use to identify the sequence. Defined Value: NIFGEN_VAL_ALL_SEQUENCES — Remove all sequences 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_ClearArbMemory

ViStatus niFgen_ClearArbMemory (ViSession vi);

Purpose

Removes all previously created arbitrary waveforms, sequences, and scripts from the signal generator memory and invalidates all waveform handles, sequence handles, and waveform names.

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.

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