Skip to content

NI RFSA Utility Functions

Jump to bottom
Greg Stoll edited this page Nov 11, 2021 · 1 revision

Utility Functions

niRFSA_CheckAcquisitionStatus

ViStatus niRFSA_CheckAcquisitionStatus(ViSession vi, ViBoolean* isDone);

Purpose

Checks the status of the acquisition. Use this function to check for any errors that may occur during signal acquisition or to check whether the device has completed the acquisition operation.

Supported Devices: PXIe-5644/5645/5646, PXI-5661, PXIe-5663/5663E/5665/5667/5668, PXIe-5694/5698, PXIe-5820/5830/5831/5832/5840/5841

Related Topics

[NI RF Vector Signal Analyzer State Diagram](javascript:LaunchMergedHelp('nirfsa.chm', 'PXIe-5668.chm', 'hardware-state-diagram.html'))

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. vi is obtained from the [niRFSA_init](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_init.html')) or [niRFSA_InitWithOptions](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_initWithOptions.html')) function.
Output
Name Type Description
isDone ViBoolean* Returns signal acquisition status.
VI_TRUE Signal acquisition is complete.
VI_FALSE Signal acquisition is not complete.

| :- | :- | :- |

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. Examine the status code from each call to an NI-RFSA 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 [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function. To clear the error information from NI-RFSA, call the [niRFSA_ClearError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ClearError.html')) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

| :- | :- | :- |

niRFSA_reset

ViStatus niRFSA_reset(ViSession vi);

Purpose

Resets all properties to default values, deletes all de-embedding tables, and stops the export of all external signals and events.

For the PXI-5600, this function does not reset the PXI Clock signal that is driven by devices installed in the Trigger Controller Slot, also known as the System Timing Slot.

This function resets all configured routes for the PXIe-5644/5645/5646 and PXIe-5820/5830/5831/5832/5840/5841 in NI-RFSA and NI-RFSG. To avoid resetting routes on the device that are in use by NI-RFSG sessions, NI recommends using the [niRFSA_ResetWithOptions](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ResetWithOptions.html')) function, with stepsToOmit set to NIRFSA_VAL_RESET_WITH_OPTIONS_ROUTES.

Supported Devices: PXI-5600, PXIe-5601/5603/5605/5606 (external digitizer mode), PXIe-5644/5645/5646, PXI-5661, PXIe-5663/5663E/5665/5667/5668, PXIe-5693/5694/5698, PXIe-5820/5830/5831/5832/5840/5841

Related Topics

Triggers

Events

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. vi is obtained from the [niRFSA_init](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_init.html')) or [niRFSA_InitWithOptions](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_initWithOptions.html')) function.

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. Examine the status code from each call to an NI-RFSA 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 [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function. To clear the error information from NI-RFSA, call the [niRFSA_ClearError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ClearError.html')) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

| :- | :- | :- |

niRFSA_ResetDevice

ViStatus niRFSA_resetDevice(ViSession vi);

Purpose

Performs a hard reset on the device. A hard reset consists of the following actions:

  • Signal acquisition is stopped.
  • All routes are released.
  • External bidirectional terminals are tristated.
  • FPGAs are reset.
  • Hardware is configured to its default state.
  • All session attributes are reset to their default states.

During a device reset, routes of signals between this and other devices are released, regardless of which device created the route. For example, a trigger signal exported to a PXI trigger line that is used by another device is no longer exported.

On the PXI-5600, if you are driving the PXI_CLK10 line, you continue to drive the clock even after a device reset. To stop driving the PXI_CLK10 line, use the [niRFSA_ConfigurePXIChassisClk10](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ConfigurePXIChassisClk10.html')) function and set the pxiClk10Source parameter to NIRFSA_VAL_NONE_STR or set the [NIRFSA_ATTR_PXI_CHASSIS_CLK10_SOURCE](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'NIRFSA_ATTR_PXI_CHASSIS_CLK10_SOURCE.html')) attribute to NIRFSA_VAL_NONE_STR.

Supported Devices: PXI-5600, PXIe-5601/5603/5605/5606 (external digitizer mode), PXI-5661, PXIe-5663/5663E/5665/5667/5668, PXIe-5693/5694/5698

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. vi is obtained from the [niRFSA_init](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_init.html')) or [niRFSA_InitWithOptions](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_initWithOptions.html')) function.

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. Examine the status code from each call to an NI-RFSA 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 [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function. To clear the error information from NI-RFSA, call the [niRFSA_ClearError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ClearError.html')) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

| :- | :- | :- |

niRFSA_ResetWithOptions

ViStatus niRFSA_ResetWithOptions(ViSession vi, ViInt64 stepsToOmit);

Purpose

Resets all properties to default values and specifies steps to omit during the reset process, such as signal routes.

For the PXI-5600, this function does not reset the PXI Clock signal that is driven by devices installed in the Star Trigger Controller Slot, also known as the System Timing Slot.

By default, this function resets all properties to their default values, deletes all de-embedding tables, aborts generation, clears all routes, and resets session properties to initial values. You can specify steps to omit using the steps to omit parameter. For example, if you specify NIRFSA_VAL_RESET_WITH_OPTIONS_ROUTES for the stepsToOmit parameter, this function does not release signal routes during the reset process.

When routes of signals between two devices are released, they are released regardless of which device created the route.

To avoid resetting routes on the PXIe-5644/5645/5646 and PXIe-5820/5830/5831/5832/5840/5841 that are in use by NI-RFSG sessions, NI recommends using this function instead of [niRFSA_Reset](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_Reset.html')), with stepsToOmit set to NIRFSA_VAL_RESET_WITH_OPTIONS_ROUTES.

Supported Devices: PXI-5600, PXIe-5601/5603/5605/5606 (external digitizer mode), PXIe-5644/5645/5646, PXI-5661, PXIe-5663/5663E/5665/5667/5668, PXIe-5693/5694, PXIe-5820/5830/5831/5832/5840/5841

Related Topics

Triggers

Events

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. vi is obtained from the [niRFSA_init](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_init.html')) or [niRFSA_InitWithOptions](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_initWithOptions.html')) function.
stepsToOmit ViUInt64 Specifies a list of steps to skip during the reset process. The default value is NIRFSA_VAL_RESET_WITH_OPTIONS_NONE, which specifies that no step is omitted during reset.
NIRFSA_VAL_RESET_WITH_OPTIONS_NONE (0) No step is omitted during reset.
NIRFSA_VAL_RESET_WITH_OPTIONS_ROUTES (1) Omits the routing reset step. Routing is preserved after a reset. However, routing related properties are reset to default, and routing is released if the default properties are committed after a reset.
NIRFSA_VAL_RESET_WITH_OPTIONS_DEEMBEDDING_TABLES (2) Omits deleting de-embedding tables. This step is valid only for the PXIe-5830/5831/5832/5840.

| :- | :- | :- |

Note Note  NIRFSA_VAL_RESET_WITH_OPTIONS_ROUTES is not supported in external calibration or alignment sessions.

| :- | :- | :- |

Note Note  NIRFSA_VAL_RESET_WITH_OPTIONS_ROUTES is not supported for the PXI-5600/5661.

| :- | :- | :- |

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. Examine the status code from each call to an NI-RFSA 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 [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function. To clear the error information from NI-RFSA, call the [niRFSA_ClearError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ClearError.html')) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

| :- | :- | :- |

niRFSA_Commit

ViStatus niRFSA_Commit(ViSession vi);

Purpose

Commits settings to hardware. Calling this function is optional. Settings are automatically committed to hardware when you call the [niRFSA_Initiate](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_Initiate.html')) function, the [niRFSA_ReadIQSingleRecordComplexF64](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ReadIQSingleRecordComplexF64.html')) function, or the [niRFSA_ReadPowerSpectrumF64](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ReadPowerSpectrumF64.html')) function.

Note  This function does not wait for settling time, unlike the niRFSA_Initiate function.
Supported Devices: PXI-5600, PXIe-5601/5603/5605/5606 (external digitizer mode), PXIe-5644/5645/5646, PXI-5661, PXIe-5663/5663E/5665/5667/5668, PXIe-5693/5694/5698, PXIe-5820/5830/5831/5832/5840/5841

Related Topics

[NI RF Vector Signal Analyzer State Diagram](javascript:LaunchMergedHelp('nirfsa.chm', 'PXIe-5668.chm', 'hardware-state-diagram.html'))

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. vi is obtained from the [niRFSA_init](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_init.html')) or [niRFSA_InitWithOptions](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_initWithOptions.html')) function.

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. Examine the status code from each call to an NI-RFSA 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 [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function. To clear the error information from NI-RFSA, call the [niRFSA_ClearError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ClearError.html')) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

| :- | :- | :- |

niRFSA_self_test

ViStatus niRFSA_self_test(ViSession vi, ViInt16 *testResult, ViChar testMessage[]);

Purpose

Performs a self-test on the NI-RFSA device and returns the test result. This function performs a simple series of tests verifying that the NI-RFSA device is powered on and responding.

Note  This function calls the niRFSA_reset function, which resets the software state.
Supported Devices: PXI-5600, PXIe-5601/5603/5605/5606 (external digitizer mode), PXI-5661, PXIe-5663/5663E/5665/5667/5668, PXIe-5693/5694/5698, PXIe-5820/5830/5831/5832/5840/5841

Related Topics

Running a Self-Test on an NI-RFSA Device

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. vi is obtained from the [niRFSA_init](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_init.html')) or [niRFSA_InitWithOptions](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_initWithOptions.html')) function.
Output
Name Type Description
testResult ViInt16* Returns the value from the device self-test. A value of 0 means success. All other values indicate failure.

You must pass a ViChar array with 1024 bytes or more to this parameter. Only the first 1024 bytes of the array are used.
testMessage ViChar[] Returns the self-test response string from the NI-RFSA device.

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. Examine the status code from each call to an NI-RFSA 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 [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function. To clear the error information from NI-RFSA, call the [niRFSA_ClearError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ClearError.html')) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

| :- | :- | :- |

niRFSA_PerformThermalCorrection

ViStatus niRFSA_PerformThermalCorrection(ViSession vi);

Purpose

Corrects for temperature variations while acquiring the same signal for an extended period of time in a continuous acquisition.

NI-RFSA internally acquires the temperature every time you initiate an acquisition. If you are performing a continuous acquisition, National Instruments recommends calling this function once every 10 minutes in a stable temperature environment to periodically update temperature calibration. If the ambient temperature varies, call this function more frequently.

Note Note  You cannot call this function if your device is operating in RF list mode.
Refer to the Thermal Management section for your device for more information about typical operating temperatures.

Supported Devices: PXI-5661, PXIe-5663/5663E/5665/5667/5668, PXIe-5693/5694, PXIe-5830/5831/5832/5840/5841

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. vi is obtained from the [niRFSA_init](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_init.html')) or [niRFSA_InitWithOptions](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_initWithOptions.html')) function.

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. Examine the status code from each call to an NI-RFSA 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 [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function. To clear the error information from NI-RFSA, call the [niRFSA_ClearError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ClearError.html')) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

| :- | :- | :- |

niRFSA_GetFetchBacklog

ViStatus niRFSA_GetFetchBacklog(ViSession vi, ViConstString channelList, ViInt64 recordNumber, ViInt64* backlog);

Purpose

Returns the number of points acquired that have not yet been fetched.

Supported Devices: PXIe-5644/5645/5646, PXI-5661, PXIe-5663/5663E/5665/5667/5668, PXIe-5820/5830/5831/5832/5840/5841

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. vi is obtained from the [niRFSA_init](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_init.html')) or [niRFSA_InitWithOptions](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_initWithOptions.html')) function.
channelList ViConstString Identifies which channels to apply settings. Specify an empty string as the value of this parameter.
recordNumber ViInt64 Specifies the record from which to read the backlog. Record numbers are zero-based.
Output
Name Type Description
backlog ViInt64* Returns the number of samples available to read for the requested record.

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. Examine the status code from each call to an NI-RFSA 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 [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function. To clear the error information from NI-RFSA, call the [niRFSA_ClearError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ClearError.html')) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

| :- | :- | :- |

niRFSA_revision_query

ViStatus niRFSA_revision_query(ViSession vi, ViChar driverRev[], ViChar instrRev[]);

Purpose

Returns the revision numbers of the NI-RFSA instrument driver.

Supported Devices: PXI-5600, PXIe-5601/5603/5605/5606 (external digitizer mode), PXIe-5644/5645/5646, PXI-5661, PXIe-5663/5663E/5665/5667/5668, PXIe-5693/5694/5698, PXIe-5820/5830/5831/5832/5840/5841

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. vi is obtained from the [niRFSA_init](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_init.html')) or [niRFSA_InitWithOptions](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_initWithOptions.html')) function.
Output
Name Type Description
driverRev ViChar[] Returns the instrument driver software revision numbers in the form of a string. The value of the [NIRFSA_ATTR_SPECIFIC_DRIVER_REVISION](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'NIRFSA_ATTR_SPECIFIC_DRIVER_REVISION.html')) attribute is returned.

You must pass a ViChar array with 256 bytes or more to this parameter.
instrRev ViChar[] Returns the instrument firmware revision numbers in the form of a string. The value of the [NIRFSA_ATTR_INSTRUMENT_FIRMWARE_REVISION](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'NIRFSA_ATTR_INSTRUMENT_FIRMWARE_REVISION.html')) attribute is returned.

You must pass a ViChar array with 256 bytes or more to this parameter.

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. Examine the status code from each call to an NI-RFSA 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 [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function. To clear the error information from NI-RFSA, call the [niRFSA_ClearError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ClearError.html')) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

| :- | :- | :- |

niRFSA_GetRelayOperationsCount

ViStatus niRFSA_GetRelayOperationsCount(ViSession vi, ViConstString channelList, ViInt32 operationsCount[], ViInt32* bufferSize);

Purpose

Returns an array consisting of all the relay counts for your device. When you call this function and pass a VI_NULL pointer to the operationsCount parameter, bufferSize is populated with the number of relays on the device. When you call this function and specify a value for bufferSize that is greater than or equal to the number of relays, the operationsCount parameter returns the appropriate value.

Supported Devices: PXIe-5603/5605/5606, PXIe-5698

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. vi is obtained from the [niRFSA_init](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_init.html')) or [niRFSA_InitWithOptions](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_initWithOptions.html')) function.
channelList ViConstString Identifies which channels to apply settings. Specify an empty string as the value of this parameter.
Output
Name Type Description
operationsCount ViInt32[] Specifies the operations count array, when used as an input. You can select VI_NULL or a pointer to a ViInt32 array. VI_NULL is the default. When bufferSize is greater than or equal to the number of relays, operationsCount returns the number of relay operations.
bufferSize ViInt32* Functions as an input or an output. bufferSize receives or returns the number of relays that are on the device.

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. Examine the status code from each call to an NI-RFSA 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 [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function. To clear the error information from NI-RFSA, call the [niRFSA_ClearError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ClearError.html')) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

| :- | :- | :- |

niRFSA_GetRelayName

ViStatus niRFSA_GetRelayName(ViSession vi, ViConstString channelList, ViInt32 index, ViChar name[], ViInt32* bufferSize);

Purpose

Returns the name of a relay for your device. When you call this function and pass a VI_NULL pointer to the name parameter, bufferSize is populated with the number of relays on the device. When you call this function and specify a value for bufferSize that is greater than or equal to the name of relay, the name parameter returns the appropriate value.

Supported Devices: PXIe-5603/5605/5606, PXIe-5698

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. vi is obtained from the [niRFSA_init](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_init.html')) or [niRFSA_InitWithOptions](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_initWithOptions.html')) function.
channelList ViConstString Identifies which channels to apply settings. Specify an empty string as the value of this parameter.
indexOfRelay ViInt32 Specifies the index of the relay.
Output
Name Type Description
name ViChar[] Specifies the relay name, when used as an input. You can select VI_NULL or a pointer to a ViInt32 array. VI_NULL is the default. When bufferSize is greater than or equal to the number of relays, name returns the relay name.
bufferSize ViInt32* When a VI_NULL pointer is passed in for the name, bufferSize is populated with the number of relays on the device. When bufferSize equals the size of the name, the relay is identified in the name parameter.

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. Examine the status code from each call to an NI-RFSA 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 [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function. To clear the error information from NI-RFSA, call the [niRFSA_ClearError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ClearError.html')) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

| :- | :- | :- |

niRFSA_GetSpectralInfoForSMT

ViStatus niRFSA_GetSpectralInfoForSMT(ViSession vi, SmtSpectrumInfo* spectrumInfo);

Purpose

Returns information about the power spectrum NI-RFSA computes.

Note  The NI Spectral Measurements Toolkit (SMT) requires this information.
Supported Devices: PXIe-5644/5645/5646, PXI-5661, PXIe-5663/5663E/5665/5667/5668, PXIe-5820/5830/5831/5832/5840/5841

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. vi is obtained from the [niRFSA_init](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_init.html')) or [niRFSA_InitWithOptions](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_initWithOptions.html')) function.
Output
Name Type Description
spectrumInfo SmtSpectrumInfo* Returns returns properties of the computed spectrum such as spectrum type, spectrum scale (linear or logarithmic), the window type the function used to compute the spectrum, window size, and FFT size. Pass this parameter to subsequent functions that contain the spectrumInfo parameter.

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. Examine the status code from each call to an NI-RFSA 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 [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function. To clear the error information from NI-RFSA, call the [niRFSA_ClearError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ClearError.html')) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

| :- | :- | :- |

niRFSA_GetDeviceResponse

ViStatus niRFSA_GetDeviceResponse(ViSession vi, ViConstString channelList, ViInt32 bufferSize, ViInt32 responseType, ViReal64 frequencies[], ViReal64 magnitudeResponse[], ViReal64 phaseResponse[], ViInt32* numberOfFrequencies);

Purpose

Returns the requested response type, based on current NI-RFSA settings. The PXI-5661 and PXIe-5663/5663E/5665/5667/5668 automatically corrects for the IF and RF response when you set the [NIRFSA_ATTR_DIGITAL_IF_EQUALIZATION_ENABLED](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'NIRFSA_ATTR_DIGITAL_IF_EQUALIZATION_ENABLED.html')) attribute to VI_TRUE. If you are using external digitizer mode, you can use information returned from this function to correct your measurement.

Supported Devices: PXI-5600, PXIe-5601/5603/5605/5606 (external digitizer mode), PXI-5661, PXIe-5663/5663E/5665/5667/5668, PXIe-5693/5694/5698

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. vi is obtained from the [niRFSA_init](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_init.html')) or [niRFSA_InitWithOptions](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_initWithOptions.html')) function.
channelList ViConstString Identifies which channels to apply settings. Specify an empty string as the value of this parameter.
responseType ViInt32 Specifies the IF, RF, or combined (IF and RF) response of the downconverter or NI-RFSA device that NI-RFSA returns. The default value is NIRFSA_VAL_DOWNCONVERTER_IF_RESPONSE.
NIRFSA_VAL_DOWNCONVERTER_IF_RESPONSE Returns the IF response of the downconverter.
NIRFSA_VAL_DOWNCONVERTER_RF_RESPONSE Returns the RF response of the downconverter. This value is supported only for the PXIe-5603/5605/5665/5667/5693.
NIRFSA_VAL_DOWNCONVERTER_COMBINED_RESPONSE Returns the combined RF and IF response of the downconverter. The combined response is in terms of IF frequency. This value is supported only for the PXIe-5603/5605/5665/5667.
NIRFSA_VAL_VSA_IF_RESPONSE Returns the IF response of the entire NI-RFSA device. This value is supported only for the PXIe-5665/5667.
NIRFSA_VAL_VSA_COMBINED_RESPONSE Returns the combined IF and RF response of the entire NI-RFSA device. The combined response is in terms of IF frequency. This value is supported only for the PXIe-5665/5667.

| :- | :- | :- | |bufferSize|ViInt32|Specifies the size of the array you specify for the frequencies, magnitudeResponse, and phaseResponse parameters.| |Output||| |Name|Type|Description| |frequencies|ViReal64[]|Returns an array containing the frequencies, in hertz (Hz), that correspond to the response data.

Pass VI_NULL if you do not want to use this parameter.| |magnitudeResponse|ViReal64[]|Returns an array containing the magnitude of the requested response, in decibels (dB). The magnitude response is normalized to the center frequency at each frequency in the frequencies array.

Pass VI_NULL if you do not want to use this parameter.| |phaseResponse|ViReal64[]|Returns an array containing the phase of the requested response, in radians. The phase response is normalized to the center frequency at each frequency entry in the frequencies array.

Pass VI_NULL if you do not want to use this parameter. This array may contain zeros if the device does not contain a stored phase response in its calibration data. | |numberOfFrequencies|ViInt32*|Returns the required number of elements in the frequencies array and the response arrays. If bufferSize is 0, this parameter returns the expected array size. The expected array size depends on which NI-RFSA device you use (PXI-5661, PXIe-5663/5663E/5665) and on the current settings (PXIe-5663/5663E/5665 only).|

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. Examine the status code from each call to an NI-RFSA 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 [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function. To clear the error information from NI-RFSA, call the [niRFSA_ClearError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ClearError.html')) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

| :- | :- | :- |

niRFSA_GetScalingCoefficients

ViStatus niRFSA_GetScalingCoefficients(ViSession vi, ViConstString channelList, ViInt32 arraySize, struct niRFSA_coefficientInfo coefficientInfo[], ViInt32* numberOfCoefficientSets);

Purpose

Returns coefficients you can use to convert unscaled data to scaled I/Q data.

Acquired data may be unscaled when sent by a peer-to-peer stream or fetched as unscaled data. Use this function to obtain niRFSA_coefficientInfo structures in the coefficientInfo array that provide gain and offset values you can use to scale this data into the actual I/Q values. The coefficientInfo array returns one element for each channel specified in the channelList parameter. The element order matches the order specified by the channelList parameter. To get the actual I/Q values, scale the unscaled data from an acquisition by multiplying it by the gain value of the appropriate coefficientInfo element then adding the offset from the same element.

Note Note  The coefficients are calculated by NI-RFSA for the current configuration of the device, so they are only valid for acquisitions obtained with the same device configuration.
To get the required size of the array, call this function with arraySize set to 0 and NULL for the coefficientInfo array. This function returns the required size in the numberOfCoefficientSets parameter.

Supported Devices: PXIe-5663/5663E/5665/5667/5668, PXIe-5820/5830/5831/5832/5840/5841

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. vi is obtained from the [niRFSA_init](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_init.html')) or [niRFSA_InitWithOptions](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_initWithOptions.html')) function.
channelList ViConstString Identifies which channels to apply settings. Specify an empty string as the value of this parameter.
arraySize ViInt32 Specifies the size of the array you specify for the coefficientInfo parameter.
Output
Name Type Description
coefficientInfo niRFSA_coefficientInfo[]

Specifies the array for storing the coefficient info.

- offset is the number that should be added to the data from a peer-to-peer stream after the gain has been applied if you want to scale unscaled data.

- gain returns the multiplier that you should use to scale data obtained from a peer-to-peer stream.
numberOfCoefficientSets ViInt32* Returns the number of valid coefficient sets.

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. Examine the status code from each call to an NI-RFSA 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 [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function. To clear the error information from NI-RFSA, call the [niRFSA_ClearError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ClearError.html')) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

| :- | :- | :- |

niRFSA_GetStreamEndpointHandle

ViStatus niRFSA_GetStreamEndpointHandle( ViSession vi, ViConstString streamEndpoint, VIUint32* writerHandle);

Purpose

Returns a writer endpoint handle that you can use with NI-P2P to configure a peer-to-peer stream with the digitizer as an endpoint.

Supported Devices: PXIe-5663/5663E/5665/5667/5668, PXIe-5820/5830/5831/5832/5840/5841

Related Topics

Configuring An Endpoint

Peer-to-Peer Streaming

Configuring a Peer-to-Peer Stream

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. vi is obtained from the [niRFSA_init](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_init.html')) or [niRFSA_InitWithOptions](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_initWithOptions.html')) function.
streamEndpoint ViConstString Specifies the name of the stream resources you want to use.
Output
Name Type Description
writerHandle ViUInt32* Returns the writer endpoint handle which you use with NI-P2P to create a stream with the digitizer as an endpoint.

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. Examine the status code from each call to an NI-RFSA 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 [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function. To clear the error information from NI-RFSA, call the [niRFSA_ClearError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ClearError.html')) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

| :- | :- | :- |

niRFSA_EnableSessionAccess

ViStatus niRFSA_EnableSessionAccess(ViSession vi, ViBoolean enable);

Purpose

Enables or disables SFP session access for the specified instrument.

SFP session access allows the NI-RFSA Soft Front Panel (SFP) to access a device with an existing open session and can help you debug your code. To enable session access, pass VI_TRUE to the enabled parameter. To disable session access, pass VI_FALSE to the enabled parameter.

Refer to Configuring SFP Session Access using LabWindows/CVI or C for more information about SFP session access.

Supported Devices: PXI-5600, PXIe-5601/5603/5605/5606 (external digitizer mode), PXIe-5644/5645/5646, PXI-5661, PXIe-5663/5663E/5665/5667/5668, PXIe-5693/5694, PXIe-5830/5831/5832/5840/5841

Note Note  NI-RFSA does not support NI-TClk when driver session debugging is enabled.

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. vi is obtained from the [niRFSA_init](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_init.html')) or [niRFSA_InitWithOptions](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_initWithOptions.html')) function.
enable ViBoolean Enables or disables SFP session access for the specified device.
VI_TRUE Enables session access.
VI_FALSE Disables session access.

| :- | :- | :- |

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. Examine the status code from each call to an NI-RFSA 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 [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function. To clear the error information from NI-RFSA, call the [niRFSA_ClearError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ClearError.html')) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

| :- | :- | :- |

Error Info

niRFSA_error_message

ViStatus niRFSA_error_message(ViSession vi, ViStatus statusCode, ViChar message[]);

Purpose

Converts a status code returned by an NI-RFSA function into a user-readable string.

Supported Devices: PXI-5600, PXIe-5601/5603/5605/5606 (external digitizer mode), PXIe-5644/5645/5646, PXI-5661, PXIe-5663/5663E/5665/5667/5668, PXIe-5693/5694/5698, PXIe-5820/5840

Parameters

Input
Name Type Description
vi ViSession

The ViSession handle that you obtain from niRFSA_init or niRFSA_InitWithOptions. The handle identifies a particular instrument session.

You can pass VI_NULL for this parameter. Passing VI_NULL is useful when niRFSA_init or niRFSA_InitWithOptions fails.
errorCode ViStatus Passes the status parameter that is returned from any NI-RFSA function.
Output
Name Type Description
errorMessage ViChar[] Returns the user-readable message string that corresponds to the status code you specify.

You must pass a ViChar array with 1024 bytes or more to this parameter. Only the first 1024 bytes of the array are used.

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. Examine the status code from each call to an NI-RFSA 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 [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function. To clear the error information from NI-RFSA, call the [niRFSA_ClearError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ClearError.html')) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

| :- | :- | :- |

niRFSA_GetError

ViStatus niRFSA_GetError(ViSession vi, ViStatus *errorCode, ViInt32 errorDescriptionBufferSize, ViChar errorDescription[]);

Purpose

Retrieves and then clears the IVI error information for the session or the current execution thread.

Note  If the errorDescriptionBufferSize parameter is 0, this function does not clear the error information. By passing 0 to errorDescriptionBufferSize, you can determine the buffer size required to read the entire error description string. You can then call this function again with a sufficiently large buffer.

If you specify a valid IVI session for the vi parameter, this function retrieves and then clears the error information for the session. If you pass VI_NULL for vi, this function retrieves and then clears the error information for the current execution thread. If vi is an invalid session, this function does nothing and returns an error. Normally, the error information describes the first error that occurred since you last called this function or the [niRFSA_ClearError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ClearError.html')) function.
Supported Devices: PXI-5600, PXIe-5601/5603/5605/5606 (external digitizer mode), PXIe-5644/5645/5646, PXI-5661, PXIe-5663/5663E/5665/5667/5668, PXIe-5693/5694/5698, PXIe-5820/5840

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. vi is obtained from the [niRFSA_init](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_init.html')) or [niRFSA_InitWithOptions](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_initWithOptions.html')) function.
errorDescriptionBufferSize ViInt32 Passes the number of bytes in the ViChar array you specify in description.

If the error description, including the terminating NULL byte, contains more bytes than you indicate in this parameter, the function copies errorDescriptionBufferSize – 1 bytes into the buffer, places an ASCII NULL byte at the end of the buffer, and returns the size of the buffer that you must pass to get the entire value. For example, if the value is "123456" and the buffer size is 4, the function places "123" into the buffer and returns 7.

If you pass 0, you can pass VI_NULL for the errorDescription parameter.
Output
Name Type Description
errorCode ViStatus* Returns the error code for the session or execution thread. If you pass 0 for the errorDescriptionBufferSize parameter, you can pass VI_NULL for this parameter.
errorDescription ViChar[] Returns the error description for the IVI session or execution thread. If there is no description, this function returns an empty string.

The buffer must contain at least as many elements as the value you specify with the errorDescriptionBufferSize parameter. If the error description, including the terminating NULL byte, contains more bytes than you indicate in this parameter, the function copies errorDescriptionBufferSize – 1 bytes into the buffer, places an ASCII NULL byte at the end of the buffer, and returns the size of the buffer, in the status return value, that you must pass to get the entire value. For example, if the value is "123456" and the buffer size is 4, the function places "123" into the buffer and returns 7.

If you pass 0, you can pass VI_NULL for the this parameter.

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. Examine the status code from each call to an NI-RFSA function to determine if an error has occurred.
Note  If you set the errorDescriptionBufferSize parameter to 0, this function returns the size of the buffer that you must pass to get the entire value of the error description string. When the status return value returns the buffer size, the status code is not returned.
To obtain a text description of the status code and additional information about the error condition, call the [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function. To clear the error information from NI-RFSA, call the [niRFSA_ClearError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ClearError.html')) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

| :- | :- | :- |

niRFSA_ClearError

ViStatus niRFSA_ClearError(ViSession vi);

Purpose

Clears the error information associated with the session. If you pass VI_NULL for the vi parameter, this function clears the error information for the current execution thread.

Note  The [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function clears the error information after it is retrieved. A call to the niRFSA_ClearError function is necessary only when a call to the [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function is not used to retrieve error information.
Supported Devices: PXI-5600, PXIe-5601/5603/5605/5606 (external digitizer mode), PXIe-5644/5645/5646, PXI-5661, PXIe-5663/5663E/5665/5667/5668, PXIe-5693/5694/5698, PXIe-5820/5840

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. vi is obtained from the [niRFSA_init](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_init.html')) or [niRFSA_InitWithOptions](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_initWithOptions.html')) function.

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. Examine the status code from each call to an NI-RFSA 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 [niRFSA_GetError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_GetError.html')) function. To clear the error information from NI-RFSA, call the [niRFSA_ClearError](javascript:LaunchMergedHelp('nirfsa.chm', 'rfsacref.chm', 'cviniRFSA_ClearError.html')) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

| :- | :- | :- |

Table of Contents

Home

Internal Development

Creating and Setting Up a gRPC Server

Server Security Support

Creating a gRPC Client

gRPC Client Examples

Session Utilities API Reference

Driver Documentation

gRPC API Differences From C API

Sharing Driver Sessions Between Clients

C API Docs
NI-DAQmx
NI-DCPOWER
NI-DIGITAL PATTERN DRIVER
NI-DMM
NI-FGEN
NI-FPGA
NI-RFmx Bluetooth
NI-RFmx NR
NI-RFmx WCDMA
NI-RFmx GSM
NI-RFmx CDMA2k
NI-RFmx Instr
NI-RFmx LTE
NI-RFmx SpecAn
NI-RFmx TD-SCDMA
NI-RFmx WLAN
NI-RFSA
NI-RFSG
NI-SCOPE
NI-SWITCH
NI-TCLK
NI-XNET
Clone this wiki locally