IviSpecAn_ReadYTrace
IviSpecAnBase Capability Group
C Function Prototype
ViStatus IviSpecAn_ReadYTrace (ViSession vi, ViConstString traceName, ViInt32 maximumTime_ms, ViInt32 arrayLength, ViInt32* actualPoints, ViReal64[] amplitude);
Purpose
This function initiates a signal acquisition based on the present instrument configuration. It then waits for the acquisition to complete, and returns the trace as an array of amplitude values. The amplitude array returns data that represent 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). This function resets the sweep count.
Notes:
(1) If the spectrum analyzer did not complete the acquisition within the time specified in the Maximum Time parameter, this function returns the Max Time Exceeded (0xBFFA2003) error.
(2) If the data was captured in an uncalibrated spectrum analyzer mode, this function returns a Measure Uncalibrated (0x3FFA2001) warning.
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. |
| maximumTime_ms | ViInt32 | Pass the maximum length of time in which to allow the read trace operation to complete. If the operation does not complete within this time interval, the function returns the IVISPECAN_ERROR_MAX_TIME_EXCEEDED (0xBFFA2003) error code. When this occurs, call IviSpecAn_Abort to cancel the read trace operation and return the spectrum analyzer to the Idle state. Units: milliseconds. Defined Values: IVISPECAN_VAL_MAX_TIME_INFINITE (-1) IVISPECAN_VAL_MAX_TIME_IMMEDIATE (0) Default Value: 5000 (ms) Notes: (1) The Maximum Time parameter applies only to this function. It has no effect on other timeout parameters or attributes. |
| 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. Notes: (1) The IviSpecAn_QueryTraceSize function returns the number of points the spectrum analyzer acquires. Pass a ViReal64 array with at least this many elements. |