Skip to content

NI RFSG Utility Functions

Jump to bottom
Greg Stoll edited this page Nov 11, 2021 · 2 revisions

Utility Functions

niRFSG_InitWithOptions

C Function Prototype

ViStatus niRFSG_InitWithOptions (ViRsrc resourceName, ViBoolean idQuery, ViBoolean resetDevice, ViConstString optionString, ViSession* vi);

Purpose

Opens a session to the device you specify as the resourceName and returns a ViSession handle that you use to identify the NI-RFSG device in all subsequent NI-RFSG function calls. This function also configures the device through the optionString input.

Supported Devices: PXI-5610, PXIe-5611, PXIe-5644/5645/5646, PXI/PXIe-5650/5651/5652, PXIe-5653/5654/5654 with PXIe-5696, PXI-5670/5671, PXIe-5672/5673/5673E, PXIe-5820/5830/5831/5832/5840/5841

Related Topics

Driver Setup Options

Simulating an NI RF Signal Generator

Parameters

Input
Name Type Description
resourceName ViRsrc Specifies the resource name of the device to initialize.

For NI-DAQmx devices, the syntax is the device name specified in MAX. Typical default names for NI-DAQmx devices in MAX are Dev2 or PXISlot2. You can rename an NI-DAQmx device in MAX.

You can also specify the name of an IVI logical name configured with the IVI Configuration utility. Refer to the IVI topic of the Measurement & Automation Explorer Help for more information.
Note Note  NI-RFSG device names are not case-sensitive. However, all IVI names, such as logical names, are case-sensitive. If you use an IVI logical name, make sure the name is identical to the name shown in the IVI Configuration Utility.

| :- | :- | :- | |idQuery|ViBoolean|Specifies whether you want NI-RFSG to perform an ID query.

Defined Values: |

VI_TRUE (1) Perform ID query.
VI_FALSE (0) Do not perform ID query.

| :- | :- | :- | |reset|ViBoolean|Specifies whether you want to reset the NI-RFSG device during the initialization procedure.

Defined Values:|

VI_TRUE (1) Reset device.
VI_FALSE (0) Do not reset device.

| :- | :- | :- | |optionString|ViConstString|Specifies the initial value of certain attributes for the session. The following table lists the attributes and the name you pass in this parameter to identify the attribute.|

Name Attribute Name
RangeCheck NIRFSG_ATTR_RANGE_CHECK
QueryInstrStatus NIRFSG_ATTR_QUERY_INSTRUMENT_STATUS
Cache NIRFSG_ATTR_CACHE
RecordCoercions NIRFSG_ATTR_RECORD_COERCIONS
DriverSetup NIRFSG_ATTR_DRIVER_SETUP
Simulate NIRFSG_ATTR_SIMULATE


The format of this string consists of the following relations:
"AttributeName=Value"

where
AttributeName is the name of the attribute and Value is the value to which the attribute is set. To set multiple attributes, separate their assignments with a comma, as shown in the following option string:

"RangeCheck=1,QueryInstrStatus=0,Cache=1,DriverSetup=AWG:pxi1slot4"

The DriverSetup string is required in order to simulate a specific device.
Output
Name Type Description
vi ViSession* Returns a ViSession handle that you use to identify the NI-RFSG device in all subsequent NI-RFSG function calls.

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 instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

niRFSG_Commit

C Function Prototype

ViStatus niRFSG_Commit (ViSession vi);

Purpose

Programs the device with the correct settings. Calling this function moves the NI-RFSG device from the Configuration state to the Committed state. After this function executes, a change to any attribute reverts the NI-RFSG device to the Configuration state.

Supported devices: PXI-5610, PXIe-5611, PXIe-5644/5645/5646, PXI/PXIe-5650/5651/5652, PXIe-5653/5654/5654 with PXIe-5696, PXI-5670/5671, PXIe-5672/5673/5673E, PXIe-5820/5830/5831/5832/5840/5841

Related Topics

NI-RFSG Programming State Model

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function 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. Examine the status code from each call to an instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

niRFSG_WaitUntilSettled

C Function Prototype

ViStatus niRFSG_WaitUntilSettled (ViSession vi, ViInt32 maxTimeMilliseconds);

Purpose

Waits until the RF output signal has settled. This function is useful for devices that support changes while in the Generation state. Call this function after making a dynamic change to wait for the output signal to settle.

You can also call this function after calling the niRFSG_Commit function to wait for changes to settle. The niRFSG_WaitUntilSettled function is not required after calling the niRFSG_Initiate function because the niRFSG_Initiate automatically waits for the output to settle.

Supported Devices: PXI-5610, PXIe-5611, PXIe-5644/5645/5646, PXI/PXIe-5650/5651/5652, PXIe-5653/5654/5654 with PXIe-5696, PXI-5670/5671, PXIe-5672/5673/5673E, PXIe-5820/5830/5831/5832/5840/5841

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function and identifies a particular instrument session.
maxTimeMilliseconds ViInt32 Specifies the maximum time the function waits for the output to settle. If the maximum time is exceeded, this function returns an error. The units are expressed in milliseconds.

Default Value: 10000

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 instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

niRFSG_self_test

C Function Prototype

ViStatus niRFSG_self_test (ViSession vi, ViInt16* selfTestResult, ViChar[] selfTestMessage);

Purpose

Performs a self-test on the NI-RFSG device and returns the test results. This function performs a simple series of tests to ensure that the NI-RFSG device is powered up and responding.

This function does not affect external I/O connections or connections between devices. Complete functional testing and calibration are not performed by this function. The NI-RFSG device must be in the Configuration state before you call this function.

Supported Devices: PXI-5610, PXIe-5611, PXI/PXIe-5650/5651/5652, PXIe-5653/5654/5654 with PXIe-5696, PXI-5670/5671, PXIe-5672/5673/5673E, PXIe-5820/5830/5831/5832/5840/5841

Related Topics

Device Warm-Up

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function and identifies a particular instrument session.
Output
Name Type Description
selfTestResult ViInt16* This parameter contains the value returned from the NI-RFSG device self test.
Self-Test Code Description
0 Self test passed
1 Self test failed

| :- | :- | :- | |selfTestMessage|ViChar[]|Returns the self-test response string from the NI-RFSG device. For an explanation of the string contents, refer to the status parameter of this function.

You must pass a ViChar array with at least 256 bytes.|

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 instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

niRFSG_reset

C Function Prototype

ViStatus niRFSG_reset (ViSession vi);

Purpose

Resets all attributes to their default values and moves the NI-RFSG device to the Configuration state. This function aborts the generation, deletes all de-embedding tables, clears all routes, and resets session attributes to their initial values. During a reset, routes of signals between this and other devices are released, regardless of which device created the route.

Generally, calling this function instead of the niRFSG_ResetDevice function is acceptable. The niRFSG_reset function executes faster than the niRFSG_ResetDevice function.

To avoid resetting routes on the PXIe-5644/5645/5646 and PXIe-5820/5830/5831/5832/5840/5841 that are in use by NI-RFSA sessions, NI recommends using the niRFSG_ResetWithOptions function, with stepsToOmit set to NIRFSG_VAL_RESET_WITH_OPTIONS_ROUTES.

Note Note  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.
Supported Devices: PXI-5610, PXIe-5611, PXIe-5644/5645/5646, PXI/PXIe-5650/5651/5652, PXIe-5653/5654/5654 with PXIe-5696, PXI-5670/5671, PXIe-5672/5673/5673E, PXIe-5820/5830/5831/5832/5840/5841

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function 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. Examine the status code from each call to an instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

niRFSG_ResetWithDefaults

C Function Prototype

ViStatus niRFSG_ResetWithDefaults (ViSession vi);

Purpose

Performs a software reset of the device, returning it to the default state and applying any initial default settings from the IVI Configuration Store.

Supported Devices: PXI-5610, PXIe-5611, PXI/PXIe-5650/5651/5652, PXIe-5653/5654/5654 with PXIe-5696,PXI-5670/5671, PXIe-5672/5673/5673E

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function 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. Examine the status code from each call to an instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

niRFSG_ResetWithOptions

C Function Prototype

ViStatus niRFSG_ResetWithOptions (ViSession vi, ViUInt64, stepsToOmit);

Purpose

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

By default, this function exhibits the same behavior as niRFSG_reset. You can specify steps to omit using the steps to omit parameter. For example, if you specify NIRFSG_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-RFSA sessions, NI recommends using this function instead of [niRFSG_reset](javascript:LaunchMergedHelp('RFSG.chm', 'cvirfsg.chm', 'cviniRFSG_reset.html')), with stepsToOmit set to NIRFSG_VAL_RESET_WITH_OPTIONS_ROUTES.

Supported Devices: PXIe-5644/5645/5646, PXIe-5820/5830/5831/5832/5840/5841

Related Topics

Triggers

Events

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function and identifies a particular instrument session.
stepsToOmit ViUInt64 Specifies a list of steps to skip during the reset process. The default value is NIRFSG_VAL_RESET_WITH_OPTIONS_NONE, which specifies that no step is omitted during reset.
NIRFSG_VAL_RESET_WITH_OPTIONS_NONE No step is omitted during reset.
NIRFSG_VAL_RESET_WITH_OPTIONS_WAVEFORMS Omits clearing waveforms.
NIRFSG_VAL_RESET_WITH_OPTIONS_SCRIPTS Omits clearing scripts.
NIRFSG_VAL_RESET_WITH_OPTIONS_ROUTES 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.
NIRFSG_VAL_RESET_WITH_OPTIONS_DEEMBEDDING_TABLES Omits deleting de-embedding tables. This step is valid only for the PXIe-5830/5831/5832/5840.

| :- | :- | :- |

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

| :- | :- | :- |

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 instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

niRFSG_ResetDevice

C Function Prototype

ViStatus niRFSG_ResetDevice (ViSession vi);

Purpose

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

  • Signal generation 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.

  • PXI-5610, PXI-5670/5671, PXIe-5672— After calling this function, the device requires 25 seconds before returning to full functionality. NI-RFSG enforces this condition by adding a wait, if needed, the next time you try to access the device.
Note Note  You must call the niRFSG_ResetDevice function if the NI-RFSG device has shut down because of a high-temperature condition.
Supported Devices: PXI-5610, PXIe-5611, PXI/PXIe-5650/5651/5652, PXIe-5653/5654/5654 with PXIe-5696, PXI-5670/5671, PXIe-5672/5673/5673E

Related Topics

Thermal Shutdown

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function 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. Examine the status code from each call to an instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

niRFSG_SaveConfigurationsToFile

C Function Prototype

ViStatus niRFSG_SaveConfigurationsToFile (ViSession vi, ViConstString channelName, ViConstString filePath);

Purpose

Saves the configurations of the session to the specified file.

Supported Devices: PXIe-5820/5830/5831/5832/5840/5841

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function and identifies a particular instrument session.
channelName ViConstString

Specifies the waveform name and the marker name.

Example:

"waveform::waveform0/marker0"
filePath ViInt32 Specifies the absolute path of the file to which the NI-RFSG saves the configurations.

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 instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

niRFSG_LoadConfigurationsFromFile

C Function Prototype

ViStatus niRFSG_LoadConfigurationsFromFile (ViSession vi, ViConstString channelName, ViConstString filePath);

Purpose

Loads the configurations from the specified file to the NI-RFSG driver session. The VI does an implicit reset before loading the configurations from the file.

Supported Devices: PXIe-5820/5830/5831/5832/5840/5841

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function and identifies a particular instrument session.
channelName ViConstString

Specifies the waveform name and the marker name.

Example:

"waveform::waveform0/marker0"
filePath ViInt32 Specifies the absolute path of the file from which the NI-RFSG loads the configurations.

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 instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

niRFSG_PerformPowerSearch

C Function Prototype

ViStatus niRFSG_PerformPowerSearch (ViSession vi);

Purpose

Performs a power search if the NIRFSG_ATTR_ALC_CONTROL attribute is disabled. Calling this function disables modulation for a short time while the device levels the output signal.

Note Note  Power search temporarily enables the ALC, so ensure the appropriate included cable is connected between the PXIe-5654 ALC IN connector and the PXIe-5696 ALC OUT connector to successfully perform a power search.
Supported Devices: PXIe-5654 with PXIe-5696

Related Topics

Power Search

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function 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. Examine the status code from each call to an instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

niRFSG_GetChannelName

C Function Prototype

ViStatus niRFSG_GetChannelName (ViSession vi, ViInt32 Index, ViInt32 BufferSize, ViChar Channel_Name[]);

Purpose

Returns the channel string that is in the channel table at an index you specify.

Supported Devices: PXI-5670/5671, PXIe-5672/5673/5673E

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function and identifies a particular instrument session.
Index ViInt32 Specifies a one-based index into the channel table.
BufferSize ViInt32 Specifies the size of the buffer for the channel string.
Output
Name Type Description
Channel_Name ViChar[] Returns a channel string from the channel table at the index you specify in the Index parameter. Do not modify the contents of the channel string.

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 instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

niRFSG_revision_query

C Function Prototype

ViStatus niRFSG_revision_query (ViSession vi, ViChar[] instrumentDriverRevision, ViChar[] firmwareRevision);

Purpose

Returns the revision numbers of the NI-RFSG driver and the instrument firmware.

Supported Devices: PXI-5610, PXIe-5611, PXIe-5644/5645/5646, PXI/PXIe-5650/5651/5652, PXIe-5653/5654/5654 with PXIe-5696, PXI-5670/5671, PXIe-5672/5673/5673E, PXIe-5820/5830/5831/5832/5840/5841

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function and identifies a particular instrument session.
Output
Name Type Description
instrumentDriverRevision ViChar[] Returns the value of the NIRFSG_ATTR_SPECIFIC_DRIVER_REVISION attribute in the form of a string.

You must pass a ViChar array with at least 256 bytes.
firmwareRevision ViChar[] Returns the value of the NIRFSG_ATTR_INSTRUMENT_FIRMWARE_REVISION attribute in the form of a string.

You must pass a ViChar array with at least 256 bytes.

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 instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

niRFSG_QueryArbWaveformCapabilities

C Function Prototype

ViStatus niRFSG_QueryArbWaveformCapabilities (ViSession vi, ViInt32* maxNumberWaveforms, ViInt32* waveformQuantum, ViInt32* minWaveformSize, ViInt32* maxWaveformSize);

Purpose

Queries and returns the waveform capabilities of the NI-RFSG device. These capabilities are related to the current device configuration. The NI-RFSG device must be in the Configuration or the Generation state before calling this function.

Supported Devices: PXIe-5644/5645/5646, PXI-5670/5671, PXIe-5672/5673/5673E, PXIe-5820/5830/5831/5832/5840/5841

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function and identifies a particular instrument session.
Output
Name Type Description
maxNumberWaveforms ViInt32* Returns the value of the NIRFSG_ATTR_ARB_MAX_NUMBER_WAVEFORMS attribute. This value is the maximum number of waveforms you can write.
waveformQuantum ViInt32* Returns the value of the NIRFSG_ATTR_ARB_WAVEFORM_QUANTUM attribute. If the waveform quantum is q, then the size of the waveform that you write should be a multiple of q. The units are expressed in samples.
minWaveformSize ViInt32* Returns the value of the NIRFSG_ATTR_ARB_WAVEFORM_SIZE_MIN attribute. The number of samples of the waveform that you write must be greater than or equal to this value.
maxWaveformSize ViInt32* Returns the value of the NIRFSG_ATTR_ARB_WAVEFORM_SIZE_MAX attribute. The number of samples of the waveform that you write must be less than or equal to this value.

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 instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

niRFSG_PerformThermalCorrection

C Function Prototype

ViStatus niRFSG_PerformThermalCorrection (ViSession vi);

Purpose

Corrects for any signal drift due to environmental temperature variation when generating the same signal for extended periods of time without a parameter change. Under normal circumstances of short-term signal generation, NI-RFSG performs thermal correction automatically by ensuring stable power levels, and you do not need to call this function.

Use this function when generating the same signal for an extended period of time in a temperature-fluctuating environment. The NI-RFSG device must be in the Generation state before calling this function.

Supported Devices: PXIe-5611, PXI/PXIe-5650/5651/5652, PXIe-5653/5654/5654 with PXIe-5696, PXI-5670/5671, PXIe-5672/5673/5673E, PXIe-5830/5831/5832/5840/5841

Related Topics

Thermal Management

Impairment Calibration

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function 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. Examine the status code from each call to an instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

niRFSG_Disable

C Function Prototype

ViStatus niRFSG_Disable (ViSession vi);

Purpose

Places the instrument in a quiescent state where it has minimal or no impact on the system to which it is connected.

Supported Devices: PXI-5610, PXIe-5611, PXI/PXIe-5650/5651/5652, PXI-5670/5671, PXIe-5672/5673/5673E

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function 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. Examine the status code from each call to an instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

Error Info

niRFSG_error_query

C Function Prototype

ViStatus niRFSG_error_query (ViSession vi, ViInt32 *Error_Code, ViChar Error_Message[]);

Purpose

Reads an error code and an error message from the instrument error queue.

Supported Devices: PXI-5610, PXIe-5611, PXI/PXIe-5650/5651/5652, PXIe-5653, PXI-5670/5671, PXIe-5672/5673/5673E, PXIe-5820/5840/5841

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function and identifies a particular instrument session.
Output
Name Type Description
Error_Code ViInt32* Returns the error code read from the instrument error queue.
Error_Message ViChar[]

Returns the error message string read from the instrument error message queue.

You must pass a ViChar array with at least 256 bytes.

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 instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

niRFSG_error_message

C Function Prototype

ViStatus niRFSG_error_message (ViSession vi, ViStatus errorCode, ViChar[] errorMessage);

Purpose

Converts an error code returned by an NI-RFSG function into a user-readable string.

Supported Devices: PXI-5610, PXIe-5611, PXIe-5644/5645/5646, PXI/PXIe-5650/5651/5652, PXIe-5653/5654/5654 with PXIe-5696, PXI-5670/5671, PXIe-5672/5673/5673E, PXIe-5820/5830/5831/5832/5840/5841

Parameters

Input
Name Type Description
vi ViSession The ViSession handle that you obtain from niRFSG_init or niRFSG_InitWithOptions. The handle identifies a particular instrument session.

You can pass VI_NULL for this parameter. Passing VI_NULL is useful when niRFSG_init or niRFSG_InitWithOptions fails.

Default Value: VI_NULL
errorCode ViStatus Pass the status parameter that is returned from any NI-RFSG function.

Default Value: 0 (VI_SUCCESS)
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 at least 256 bytes 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 instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

niRFSG_GetError

C Function Prototype

ViStatus niRFSG_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 bufferSize parameter is 0, this function does not clear the error information. By passing 0 to the bufferSize parameter, you can determine the buffer size required to obtain 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 clears the error information for the session. If you pass VI_NULL for the vi parameter, this function retrieves and clears the error information for the current execution thread. If the vi parameter is an invalid session, this function does nothing and returns an error. Normally, the error information describes the first error that occurred since the user last called this function or the niRFSG_ClearError function.
Supported Devices: PXI-5610, PXIe-5611, PXIe-5644/5645/5646, PXI/PXIe-5650/5651/5652, PXIe-5653/5654/5654 with PXIe-5696, PXI-5670/5671, PXIe-5672/5673/5673E, PXIe-5820/5840/5841

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function and identifies a particular instrument session.
buffersize ViInt32 Pass the number of bytes in the ViChar array you specify for the description parameter.

If the error description, including the terminating NULL byte, contains more bytes than you indicate in this parameter, the function copies bufferSize - 1 bytes into the buffer, places an ASCII NULL byte at the end of the buffer, and returns the buffer size 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 description parameter.

Default Value: None
Output
Name Type Description
errorCode ViStatus* Returns the error code for the session or execution thread. If you pass 0 for the BufferSize parameter, you can pass VI_NULL for this parameter.
description ViChar[] Returns the error description for the IVI session or execution thread.

If there is no description, the function returns an empty string. The buffer must contain at least as many elements as the value you specify with the bufferSize parameter. If the error description, including the terminating NULL byte, contains more bytes than you indicate with the bufferSize parameter, the function copies bufferSize - 1 bytes into the buffer, places an ASCII NULL byte at the end of the buffer, and returns the buffer size 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 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 instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

niRFSG_ClearError

C Function Prototype

ViStatus niRFSG_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 niRFSG_GetError function clears the error information after it is retrieved. A call to the niRFSG_ClearError function is necessary only when you do not use a call to the niRFSG_GetError function to retrieve error information.
The IVI Engine also maintains this error information separately for each thread. This feature of the IVI Engine is useful if you do not have a session handle to pass to the niRFSG_ClearError function or the niRFSG_GetError function, which occurs when a call to the niRFSG_init function or the niRFSG_InitWithOptions function fails.

Supported Devices: PXI-5610, PXIe-5611, PXIe-5644/5645/5646, PXI/PXIe-5650/5651/5652, PXIe-5653/5654/5654 with PXIe-5696, PXI-5670/5671, PXIe-5672/5673/5673E, PXIe-5820/5840/5841

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function 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. Examine the status code from each call to an instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

Locking

niRFSG_LockSession

C Function Prototype

ViStatus niRFSG_LockSession (ViSession vi, ViBoolean* callerHasLock);

Purpose

Obtains a multithread lock on the instrument session. Before doing so, this function waits until all other execution threads have released their locks on the instrument session.

Other threads might have obtained a lock on this session in the following ways:

  • Your application already called the niRFSG_LockSession function.
  • A call to NI-RFSG locked the session.

After the call to this function returns successfully, no other threads can access the instrument session until you call the niRFSG_UnlockSession function. Use the niRFSG_LockSession function and the niRFSG_UnlockSession function around a sequence of calls to NI-RFSG functions if you require that the NI-RFSG device retain its settings through the end of the sequence.

You can safely make nested calls to the niRFSG_LockSession function within the same thread. To completely unlock the session, balance each call to the niRFSG_LockSession function with a call to the niRFSG_UnlockSession function. If, however, you use the callerHasLock parameter in all calls to the niRFSG_LockSession function and the niRFSG_UnlockSession function within a function, the IVI Library locks the session only once within the function regardless of the number of calls you make to the niRFSG_LockSession function. Locking the session only once allows you to call niRFSG_UnlockSession just once at the end of the function.

Supported Devices: PXI-5610, PXIe-5611, PXIe-5644/5645/5646, PXI/PXIe-5650/5651/5652, PXIe-5654/5654 with PXIe-5696, PXI-5670/5671, PXIe-5672/5673/5673E, PXIe-5820/5840/5841

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function and identifies a particular instrument session.
Output
Name Type Description
callerHasLock ViBoolean*

Keeps track of whether you obtain a lock and therefore need to unlock the session. Pass the address of a local ViBoolean variable. In the declaration of the local variable, initialize it to VI_FALSE. Pass the address of the same local variable to any other calls you make to the niRFSG_LockSession function or the niRFSG_UnlockSession function in the same function.



This parameter serves as a convenience. If you do not want to use this parameter, pass VI_NULL.

The parameter is an input/output parameter. The niRFSG_LockSession function and the niRFSG_UnlockSession each inspect the current value and take the following actions:

- If the value is VI_TRUE, the niRFSG_LockSession function does not lock the session again. If the value is VI_FALSE, the niRFSG_LockSession function obtains the lock and sets the value of the parameter to VI_TRUE.

- If the value is VI_FALSE, the niRFSG_UnlockSession function does not attempt to unlock the session. If the value is VI_TRUE, the niRFSG_UnlockSession function releases the lock and sets the value of the parameter to VI_FALSE.

Thus, you can call the niRFSG_UnlockSession function at the end of your function without worrying about whether you have the lock.

Example:

ViStatus TestFunc (ViSession vi, ViInt32 flags)
{
   ViStatus error = VI_SUCCESS;
   ViBoolean haveLock = VI_FALSE;

   if (flags & BIT_1)
   {
      viCheckErr( niRFSG_LockSession(vi, &haveLock));
      viCheckErr( TakeAction1(vi));
      if (flags & BIT_2)
      {
         viCheckErr( niRFSG_UnlockSession(vi, &haveLock));
         viCheckErr( TakeAction2(vi));
         viCheckErr( niRFSG_LockSession(vi, &haveLock);
      }
      if (flags & BIT_3)
      viCheckErr( TakeAction3(vi));
    }

Error:
   /*
   At this point, you cannot really be sure that you have the lock.
   Fortunately, the haveLock variable takes care of that for you.
   */
   niRFSG_UnlockSession(vi, &haveLock);
   return error;
}

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 instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError function.

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

| :- | :- | :- |

niRFSG_UnlockSession

C Function Prototype

ViStatus niRFSG_UnlockSession (ViSession vi, ViBoolean* callerHasLock);

Purpose

Releases a lock obtained on an NI-RFSG device session by calling the niRFSG_LockSession function.

Supported Devices: PXI-5610, PXIe-5611, PXIe-5644/5645/5646, PXI/PXIe-5650/5651/5652, PXIe-5654/5654 with PXIe-5696, PXI-5670/5671, PXIe-5672/5673/5673E, PXIe-5820/5840/5841

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function and identifies a particular instrument session.
Output
Name Type Description
callerHasLock ViBoolean*

Keeps track of whether you obtain a lock and therefore need to unlock the session. Pass the address of a local ViBoolean variable. In the declaration of the local variable, initialize it to VI_FALSE. Pass the address of the same local variable to any other calls you make to the niRFSG_LockSession function or the niRFSG_UnlockSession function in the same function.



This parameter serves as a convenience. If you do not want to use this parameter, pass VI_NULL.

The parameter is an input/output parameter. The niRFSG_LockSession function and the niRFSG_UnlockSession each inspect the current value and take the following actions:

- If the value is VI_TRUE, the niRFSG_LockSession function does not lock the session again. If the value is VI_FALSE, the niRFSG_LockSession function obtains the lock and sets the value of the parameter to VI_TRUE.

- If the value is VI_FALSE, the niRFSG_UnlockSession function does not attempt to unlock the session. If the value is VI_TRUE, the niRFSG_UnlockSession function releases the lock and sets the value of the parameter to VI_FALSE.

Thus, you can call the niRFSG_UnlockSession function at the end of your function without worrying about whether you have the lock.

Example:

ViStatus TestFunc (ViSession vi, ViInt32 flags)
{
   ViStatus error = VI_SUCCESS;
   ViBoolean haveLock = VI_FALSE;

   if (flags & BIT_1)
   {
      viCheckErr( niRFSG_LockSession(vi, &haveLock));
      viCheckErr( TakeAction1(vi));
      if (flags & BIT_2)
      {
         viCheckErr( niRFSG_UnlockSession(vi, &haveLock));
         viCheckErr( TakeAction2(vi));
         viCheckErr( niRFSG_LockSession(vi, &haveLock);
      }
      if (flags & BIT_3)
      viCheckErr( TakeAction3(vi));
    }

Error:
   /*
   At this point, you cannot really be sure that you have the lock.
   Fortunately, the haveLock variable takes care of that for you.
   */
   niRFSG_UnlockSession(vi, &haveLock);
   return error;
}

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 instrument driver function to determine if an error occurred.

To obtain a text description of the error code, call the niRFSG_GetError 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