IviSpecAn_FetchYTrace

CVI/LabWindows IVI Class Driver

IviSpecAn_FetchYTrace

IviSpecAnBase Capability Group

C Function Prototype

ViStatus IviSpecAn_FetchYTrace (ViSession vi, ViConstString traceName, ViInt32 arrayLength, ViInt32* actualPoints, ViReal64[] amplitude);

Purpose

This function returns the trace the spectrum analyzer acquires. The trace is from a previously initiated acquisition. Call the IviSpecAn_Initiate function to start an acquisition. Call the IviSpecAn_AcquisitionStatus function to determine when the acquisition is complete. Once the acquisition is complete, call the Fetch Y Trace function to return the trace.

You may call the IviSpecAn_ReadYTrace function instead of the IviSpecAn_Initiate function. The IviSpecAn_ReadYTrace function starts an acquisition, waits for the acquisition to complete, and returns the trace in one function call.

Use the IviSpecAn_FetchYTrace function when acquiring multiple traces. Use a different trace name for each IviSpecAn_FetchYTrace call. You may also call IviSpecAn_FetchYTrace after calling IviSpecAn_ReadYTrace to acquire subsequent traces.

The array returns data that represents the amplitude of the signals of the sweep from the start frequency to the stop frequency (in frequency domain, in time domain the amplitude array is ordered from beginning of sweep to end). The IVISPECAN_ATTR_AMPLITUDE_UNITS attribute determines the units of the points in the amplitude array.

Note:

This function does not check the instrument status. Typically, you call this function only in a sequence of calls to other low-level driver functions. The sequence performs one operation. You use the low-level functions to optimize one or more aspects of interaction with the instrument. If you want to check the instrument status, call the IviSpecAn_error_query function at the conclusion of the sequence.

Parameters

Name Type Description
vi ViSession The ViSession handle that you obtain from the IviSpecAn_init or IviSpecAn_InitWithOptions function. The handle identifies a particular instrument session.

Default Value: None

traceName ViConstString Pass the name of the trace for the desired amplitude array.

This control accepts either a virtual repeated capability name or an instrument-specific trace name.

Virtual repeated capability names are aliases for instrument-specific trace strings. The instrument-specific trace strings can differ from one instrument to another. Virtual repeated capability names allow you to use and swap instruments without having to change the trace names in your source code. You specify virtual repeated capability names in MAX.


Default Value: ""

Note:

You can specify the trace name as a string variable or as a literal enclosed in double quotes.

arrayLength ViInt32 Pass the number of Amplitude array points requested.

Default Value: None

actualPoints ViInt32 Indicates the number of points the function places in the Amplitude array.

amplitude ViReal64[] Returns the amplitude waveform that the spectrum analyzer acquires.

Units: The units are determined by setting the Amplitude Units parameter of the IviSpecAn_ConfigureLevel function or by setting IVISPECAN_ATTR_AMPLITUDE_UNITS attribute.

Note:

The IviSpecAn_QueryTraceSize function returns the number of points the spectrum analyzer acquires. Pass a ViReal64 array with at least this many elements.

Return Values