NI RFmx SpecAn Read Functions

Read Functions

• ACP
  • RFmxSpecAn_ACPRead
• CCDF
  • RFmxSpecAn_CCDFRead
• CHP
  • RFmxSpecAn_CHPRead
• Fcnt
  • RFmxSpecAn_FCntRead
• Harmonics
  • RFmxSpecAn_HarmRead
• OBW
  • RFmxSpecAn_OBWRead
• Spectrum
  • RFmxSpecAn_SpectrumRead
• TXP
  • RFmxSpecAn_TXPRead

ACP Read

RFmxSpecAn_ACPRead

int32 __stdcall RFmxSpecAn_ACPRead (niRFmxInstrHandle instrumentHandle, char selectorString[], float64 timeout, float64* carrierAbsolutePower, float64* offsetCh0LowerRelativePower, float64* offsetCh0UpperRelativePower, float64* offsetCh1LowerRelativePower, float64* offsetCh1UpperRelativePower);

Purpose

Configures hardware for acquisition, performs measurement on acquired data, and returns the adjacent channel power (ACP) measurement results.

Parameters

Input
Name	Type	Description
instrumentHandle	niRFmxInstrHandle	Identifies the RFmx session. You can obtain this parameter from the RFmxSpecAn_Initialize) function.
selectorString	char[]	Comprises the signal name. If you do not specify the signal name, the default signal instance is used. Example: "" "signal::sig1" You can use the RFmxSpecAn_BuildSignalString) function to build the selector string).
timeout	float64	Specifies the timeout, in seconds, for fetching the specified measurement. Set this value to an appropriate time, longer than expected for fetching the measurement. A value of -1 specifies that the function waits until the measurement is complete.
Output
Name	Type	Description
carrierAbsolutePower	float64*	Returns the power measured in carrier 0. The carrier power is reported in dBm or dBm/Hz based on the value of the RFMXSPECAN_ATTR_ACP_POWER_UNITS) attribute.
offsetCh0LowerRelativePower	float64*	Returns the power measured in offset 0 in the negative band, relative to the power measured in the reference carrier specified using the RFMXSPECAN_ATTR_ACP_RESULTS_LOWER_OFFSET_POWER_REFERENCE_CARRIER) attribute.
offsetCh0UpperRelativePower	float64*	Returns the power measured in offset 0 in the positive band, relative to the power measured in the reference carrier specified using the RFMXSPECAN_ATTR_ACP_RESULTS_UPPER_OFFSET_POWER_REFERENCE_CARRIER) attribute.
offsetCh1LowerRelativePower	float64*	Returns the power measured in offset 1 in the negative band, relative to the power measured in the reference carrier specified using the RFMXSPECAN_ATTR_ACP_RESULTS_LOWER_OFFSET_POWER_REFERENCE_CARRIER attribute.
offsetCh1UpperRelativePower	float64*	Returns the power measured in offset 1 in the positive band, relative to the power measured in the reference carrier specified using the RFMXSPECAN_ATTR_ACP_RESULTS_UPPER_OFFSET_POWER_REFERENCE_CARRIER attribute.

Return Value

Name	Type	Description
status	int32	Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. Examine the status code from each call to an RFmx function to determine if an error has occurred. To obtain a text description of the status code and additional information about the error condition, call the RFmxSpecAn_GetError) function. The general meaning of the status code is as follows:

Value	Meaning
0	Success
Positive Values	Warnings
Negative Values	Errors

CCDF Read

RFmxSpecAn_CCDFRead

int32 __stdcall RFmxSpecAn_CCDFRead (niRFmxInstrHandle instrumentHandle, char selectorString[], float64 timeout, float64* meanPower, float64* meanPowerPercentile, float64* peakPower, int32* measuredSamplesCount);

Purpose

Configures hardware for acquisition, performs measurement on acquired data, and returns complementary cumulative distribution function (CCDF) measurement results.

Parameters

Input
Name	Type	Description
instrumentHandle	niRFmxInstrHandle	Identifies the RFmx session. You can obtain this parameter from the RFmxSpecAn_Initialize) function.
selectorString	char[]	Comprises the signal name. If you do not specify the signal name, the default signal instance is used. Example: "" "signal::sig1" You can use the RFmxSpecAn_BuildSignalString) function to build the selector string).
timeout	float64	Specifies the timeout, in seconds, for fetching the specified measurement. Set this value to an appropriate time, longer than expected for fetching the measurement. A value of -1 specifies that the function waits until the measurement is complete.
Output
Name	Type	Description
meanPower	float64*	Returns the average power, in dBm, of all the samples. If you set the RFMXSPECAN_ATTR_CCDF_THRESHOLD_ENABLED) attribute to RFMXSPECAN_VAL_CCDF_THRESHOLD_ENABLED_TRUE, samples above the threshold are measured.
meanPowerPercentile	float64*	Returns the percentage of samples that have more power than the mean power.
peakPower	float64*	Returns the peak power of the acquired signal, relative to the mean power.
measuredSamplesCount	int32*	Returns the total number of samples measured.

Return Value

Name	Type	Description
status	int32	Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. Examine the status code from each call to an RFmx function to determine if an error has occurred. To obtain a text description of the status code and additional information about the error condition, call the RFmxSpecAn_GetError) function. The general meaning of the status code is as follows:

Value	Meaning
0	Success
Positive Values	Warnings
Negative Values	Errors

CHP Read

RFmxSpecAn_CHPRead

int32 __stdcall RFmxSpecAn_CHPRead (niRFmxInstrHandle instrumentHandle, char selectorString[], float64 timeout, float64* absolutePower, float64* PSD);

Purpose

Configures hardware for acquisition, performs measurement on acquired data, and returns the channel power (CHP) measurement results.

Parameters

Input
Name	Type	Description
instrumentHandle	niRFmxInstrHandle	Identifies the RFmx session. You can obtain this parameter from the RFmxSpecAn_Initialize) function.
selectorString	char[]	Comprises the signal name. If you do not specify the signal name, the default signal instance is used. Example: "" "signal::sig1" You can use the RFmxSpecAn_BuildSignalString) function to build the selector string).
timeout	float64	Specifies the timeout, in seconds, for fetching the specified measurement. Set this value to an appropriate time, longer than expected for fetching the measurement. A value of -1 specifies that the function waits until the measurement is complete.
Output
Name	Type	Description
absolutePower	float64*	Returns the averaged CHP, in dBm, measured in the specified integration bandwidth.
PSD	float64*	Returns the power spectral density of the channel, in dBm/Hz.

Return Value

Name	Type	Description
status	int32	Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. Examine the status code from each call to an RFmx function to determine if an error has occurred. To obtain a text description of the status code and additional information about the error condition, call the RFmxSpecAn_GetError) function. The general meaning of the status code is as follows:

Value	Meaning
0	Success
Positive Values	Warnings
Negative Values	Errors

Fcnt Read

RFmxSpecAn_FCntRead

int32 __stdcall RFmxSpecAn_FCntRead (niRFmxInstrHandle instrumentHandle, char selectorString[], float64 timeout, float64* averageRelativeFrequency, float64* averageAbsoluteFrequency, float64* meanPhase);

Purpose

Configures hardware for acquisition, performs measurement on acquired data, and returns the frequency count (FCnt) measurement results.

Parameters

Input
Name	Type	Description
instrumentHandle	niRFmxInstrHandle	Identifies the RFmx session. You can obtain this parameter from the RFmxSpecAn_Initialize) function.
selectorString	char[]	Comprises the signal name. If you do not specify the signal name, the default signal instance is used. Example: "" "signal::sig1" You can use the RFmxSpecAn_BuildSignalString) function to build the selector string).
timeout	float64	Specifies the timeout, in seconds, for fetching the specified measurement. Set this value to an appropriate time, longer than expected for fetching the measurement. A value of -1 specifies that the function waits until the measurement is complete.
Output
Name	Type	Description
averageRelativeFrequency	float64*	Returns the signal frequency relative to the RF center frequency. Only samples above the threshold are used when you set the RFMXSPECAN_ATTR_FCNT_THRESHOLD_ENABLED) attribute to RFMXSPECAN_VAL_FCNT_THRESHOLD_ENABLED_TRUE.
averageAbsoluteFrequency	float64*	Returns the RF signal frequency. Only samples above the threshold are used when you set the RFMXSPECAN_ATTR_FCNT_THRESHOLD_ENABLED attribute to RFMXSPECAN_VAL_FCNT_THRESHOLD_ENABLED_TRUE.
meanPhase	float64*	Returns the net phase of the vector sum of the I/Q samples used for frequency measurement.

Return Value

Name	Type	Description
status	int32	Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. Examine the status code from each call to an RFmx function to determine if an error has occurred. To obtain a text description of the status code and additional information about the error condition, call the RFmxSpecAn_GetError) function. The general meaning of the status code is as follows:

Value	Meaning
0	Success
Positive Values	Warnings
Negative Values	Errors

Harmonics Read

RFmxSpecAn_HarmRead

int32 __stdcall RFmxSpecAn_HarmRead (niRFmxInstrHandle instrumentHandle, char selectorString[], float64 timeout, float64* totalHarmonicDistortion, float64* averageFundamentalPower);

Purpose

Configures hardware for acquisition, performs measurement on acquired data, and returns Harmonics measurement results.

Parameters

Input
Name	Type	Description
instrumentHandle	niRFmxInstrHandle	Identifies the RFmx session. You can obtain this parameter from the RFmxSpecAn_Initialize) function.
selectorString	char[]	Comprises the signal name. If you do not specify the signal name, the default signal instance is used. Example: "" "signal::sig1" You can use the RFmxSpecAn_BuildSignalString) function to build the selector string).
timeout	float64	Specifies the timeout, in seconds, for fetching the specified measurement. Set this value to an appropriate time, longer than expected for fetching the measurement. A value of -1 specifies that the function waits until the measurement is complete.
Output
Name	Type	Description
totalHarmonicDistortion	float64*	Returns the total harmonics distortion (THD), measured as a percentage of the power in the fundamental signal. THD calculation involves only the harmonics that are enabled. THD (%) = SQRT (Total power of all enabled harmonics - Power in fundamental) * 100 / Power in fundamental.
averageFundamentalPower	float64*	Returns the average power, in dBm, measured at the fundamental frequency.

Return Value

Name	Type	Description
status	int32	Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. Examine the status code from each call to an RFmx function to determine if an error has occurred. To obtain a text description of the status code and additional information about the error condition, call the RFmxSpecAn_GetError) function. The general meaning of the status code is as follows:

Value	Meaning
0	Success
Positive Values	Warnings
Negative Values	Errors

OBW Read

RFmxSpecAn_OBWRead

int32 __stdcall RFmxSpecAn_OBWRead (niRFmxInstrHandle instrumentHandle, char selectorString[], float64 timeout, float64* occupiedBandwidth, float64* averagePower, float64* frequencyResolution, float64* startFrequency, float64* stopFrequency);

Purpose

Configures hardware for acquisition, performs measurement on acquired data, and returns occupied bandwidth (OBW) measurement results.

Parameters

Input
Name	Type	Description
instrumentHandle	niRFmxInstrHandle	Identifies the RFmx session. You can obtain this parameter from the RFmxSpecAn_Initialize) function.
selectorString	char[]	Comprises the signal name. If you do not specify the signal name, the default signal instance is used. Example: "" "signal::sig1" You can use the RFmxSpecAn_BuildSignalString) function to build the selector string).
timeout	float64	Specifies the timeout, in seconds, for fetching the specified measurement. Set this value to an appropriate time, longer than expected for fetching the measurement. A value of -1 specifies that the function waits until the measurement is complete.
Output
Name	Type	Description
occupiedBandwidth	float64*	Returns the occupied bandwidth, in hertz (Hz).
averagePower	float64*	Returns the total integrated power of the averaged spectrum acquired by the OBW measurement when you set the RFMXSPECAN_ATTR_OBW_POWER_UNITS) attribute to RFMXSPECAN_VAL_OBW_POWER_UNITS_DBM. This function returns the power spectral density when you set the RFMXSPECAN_ATTR_OBW_POWER_UNITS attribute to RFMXSPECAN_VAL_OBW_POWER_UNITS_DBM_PER_HZ.
frequencyResolution	float64*	Returns the frequency bin spacing, in Hz, of the spectrum acquired by the OBW measurement.
startFrequency	float64*	Returns the start frequency, in Hz, of the OBW. The OBW is calculated using the following formula: OBW = stop frequency - start frequency.
stopFrequency	float64*	Returns the stop frequency, in hertz (Hz), of the OBW.

Return Value

Name	Type	Description
status	int32	Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. Examine the status code from each call to an RFmx function to determine if an error has occurred. To obtain a text description of the status code and additional information about the error condition, call the RFmxSpecAn_GetError) function. The general meaning of the status code is as follows:

Value	Meaning
0	Success
Positive Values	Warnings
Negative Values	Errors

Spectrum Read

RFmxSpecAn_SpectrumRead

int32 __stdcall RFmxSpecAn_SpectrumRead (niRFmxInstrHandle instrumentHandle, char selectorString[], float64 timeout, float64* x0, float64* dx, float32 spectrum[], int32 arraySize, int32* actualArraySize);

Purpose

Configures hardware for acquisition, performs measurement on acquired data, and returns Spectrum measurement results.

Parameters

Input
Name	Type	Description
instrumentHandle	niRFmxInstrHandle	Identifies the RFmx session. You can obtain this parameter from the RFmxSpecAn_Initialize) function.
selectorString	char[]	Comprises the signal name. If you do not specify the signal name, the default signal instance is used. Example: "" "signal::sig1" You can use the RFmxSpecAn_BuildSignalString) function to build the selector string).
timeout	float64	Specifies the timeout, in seconds, for fetching the specified measurement. Set this value to an appropriate time, longer than expected for fetching the measurement. A value of -1 specifies that the function waits until the measurement is complete.
arraySize	int32	Specifies the size of the array.
Output
Name	Type	Description
x0	float64*	Returns the start frequency, in hertz (Hz). When you set the RFMXSPECAN_ATTR_SPECTRUM_SPAN) attribute to 0, x0 returns the start time, in seconds.
dx	float64*	Returns the frequency bin spacing, in Hz. When you set the RFMXSPECAN_ATTR_SPECTRUM_SPAN attribute to 0, dx returns the sample duration, in seconds.
spectrum	float32[]	Returns the averaged power, measured at each frequency bin. When you set the RFMXSPECAN_ATTR_SPECTRUM_SPAN attribute to 0, the averaged power is measured at each sample instance in time. The units of power is as specified using the RFMXSPECAN_ATTR_SPECTRUM_POWER_UNITS) attribute.
actualArraySize	int32*	Returns the actual size of the array, if you pass NULL to all output array parameters, and set the arraySize parameter to 0.

Return Value

Name	Type	Description
status	int32	Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. Examine the status code from each call to an RFmx function to determine if an error has occurred. To obtain a text description of the status code and additional information about the error condition, call the RFmxSpecAn_GetError) function. The general meaning of the status code is as follows:

Value	Meaning
0	Success
Positive Values	Warnings
Negative Values	Errors

TXP Read

RFmxSpecAn_TXPRead

int32 __stdcall RFmxSpecAn_TXPRead (niRFmxInstrHandle instrumentHandle, char selectorString[], float64 timeout, float64* averageMeanPower, float64* peakToAverageRatio, float64* maximumPower, float64* minimumPower);

Purpose

Configures hardware for acquisition, performs measurement on acquired data, and returns the transmit power (TXP) measurement results.

Parameters

Input
Name	Type	Description
instrumentHandle	niRFmxInstrHandle	Identifies the RFmx session. You can obtain this parameter from the RFmxSpecAn_Initialize) function.
selectorString	char[]	Comprises the signal name. If you do not specify the signal name, the default signal instance is used. Example: "" "signal::sig1" You can use the RFmxSpecAn_BuildSignalString) function to build the selector string).
timeout	float64	Specifies the timeout, in seconds, for fetching the specified measurement. Set this value to an appropriate time, longer than expected for fetching the measurement. A value of -1 specifies that the function waits until the measurement is complete.
Output
Name	Type	Description
averageMeanPower	float64*	Returns the mean power, in dBm, of the signal. Only the samples above the threshold are used by the measurement when you set the RFMXSPECAN_ATTR_TXP_THRESHOLD_ENABLED) attribute to RFMXSPECAN_VAL_TXP_THRESHOLD_ENABLED_TRUE. When you set the RFMXSPECAN_ATTR_TXP_AVERAGING_ENABLED) attribute to RFMXSPECAN_VAL_TXP_AVERAGING_ENABLED_TRUE, the mean power is measured on the power trace averaged over multiple acquisitions.
peakToAverageRatio	float64*	Returns the ratio of the peak power of the signal to the mean power. Only the samples above the threshold are used by the measurement when you set the RFMXSPECAN_ATTR_TXP_THRESHOLD_ENABLED) attribute to RFMXSPECAN_VAL_TXP_THRESHOLD_ENABLED_TRUE. When you set the RFMXSPECAN_ATTR_TXP_AVERAGING_ENABLED) attribute to RFMXSPECAN_VAL_TXP_AVERAGING_ENABLED_TRUE, the peak and mean powers are measured on the power trace averaged over multiple acquisitions.
maximumPower	float64*	Returns the maximum power, in dBm, of the averaged power trace.
minimumPower	float64*	Returns the minimum power, in dBm, of the averaged power trace.

Return Value

Name	Type	Description
status	int32	Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. Examine the status code from each call to an RFmx function to determine if an error has occurred. To obtain a text description of the status code and additional information about the error condition, call the RFmxSpecAn_GetError) function. The general meaning of the status code is as follows:

Value	Meaning
0	Success
Positive Values	Warnings
Negative Values	Errors