NI RFmx NR General Functions
- RFmxNR_Initialize
- RFmxNR_InitializeFromNIRFSASession
- RFmxNR_SelectMeasurements
- RFmxNR_Initiate
- RFmxNR_GetError
- RFmxNR_GetErrorString
- RFmxNR_Close
int32 __stdcall RFmxNR_Initialize (char resourceName[], char optionString[], niRFmxInstrHandle *handleOut, int32 *isNewSession);
Creates an RFmx session to the device you specify through the resourceName parameter, and returns a handleOut that identifies this device in all subsequent RFmx functions.
This function is a wrapper over the RFmx Instruments API, and calls the RFmxInstr_Initialize) function.
| Input | ||
|---|---|---|
| Name | Type | Description |
| resourceName | char[] | Specifies the resource name of the device to initialize. The following table shows examples of how to specify the resource name. |
| Example # | Device Type | Syntax |
|---|---|---|
| 1 | myRFmxDevice | RFmx device, device name is "myRFmxDevice" |
| 2 | myLogicalName | IVI logical name or virtual instrument, name is "myLogicalName" |
|
For NI-DAQmx devices, the syntax is the device name specified in MAX, as shown in Example 1. Typical default names for NI-DAQmx devices in MAX are Dev1 or PXI1Slot2. You can rename an NI-DAQmx device by right-clicking the name in MAX, selecting Rename from the pull-down menu, and entering a new name. You can also pass the name of an IVI logical name configured with the IVI Configuration utility. For additional information about IVI, refer to the IVI section of the Measurement & Automation Explorer Help. |
||
|---|---|---|
| optionString | char[] |
Sets the initial value of certain attributes for the session. - RFmxSetup - Simulate - AnalysisOnly
To use FPGA extensions, specify the custom LabVIEW FPGA bitfile to use with the bitfile specifier within the RFmxSetup string. For example, "RFmxSetup=bitfile:yourbitfile.lvbitx" specifies that RFmx uses yourbitfile.lvbitx as the LabVIEW FPGA bitfile for the session. To use AnalysisOnly mode, specify the string as "AnalysisOnly=1". In this mode, user is responsible for waveform acquisition and RFmx driver will perform analysis on user specified IQ waveform or Spectrum. Use personality specific Analyze functions to perform measurements. |
 |
Note To simulate a device using the NI 5622 (25 MHz) digitizer, set the Digitizer field to 5622_25MHz_DDC and the Simulate field to 1. You can set the Digitizer field to 5622_25MHz_DDC only when using the NI 5665. |
|---|
| isNewSession | int32* | Returns RFMXNR_VAL_TRUE if the function created a new session, or RFMXNR_VAL_FALSE if the function returned a reference to an existing session. |
| Output | ||
| Name | Type | Description |
| handleOut | niRFmxInstrHandle* | Identifies your instrument session. |
| Name | Type | Description |
|---|---|---|
| status | int32 | Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. Examine the status code from each call to an RFmx function to determine if an error has occurred. To obtain a text description of the status code and additional information about the error condition, call the RFmxNR_GetError) function. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
int32 __stdcall RFmxNR_InitializeFromNIRFSASession (uInt32 NIRFSASession, niRFmxInstrHandle *handleOut);
Creates an RFmx session from an existing NI-RFSA session. This function resets all the NI-RFSA attributes to their default values and stops export of all external signals and events. This function takes in an active NI-RFSA instrument handle and returns an RFmx Handle Out that identifies the device in all the subsequent RFmx functions. This function is a wrapper over the RFmx Instruments API, and calls the RFmxInstr_InitializeFromNIRFSASession) function.
| Input | ||
|---|---|---|
| Name | Type | Description |
| NIRFSASession | uInt32 | Specifies the NIRFSA session handle of the device to initialize. |
| Output | ||
| Name | Type | Description |
| handleOut | niRFmxInstrHandle* | Returns an RFmx instrument session. |
| Name | Type | Description |
|---|---|---|
| status | int32 | Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. Examine the status code from each call to an RFmx function to determine if an error has occurred. To obtain a text description of the status code and additional information about the error condition, call the RFmxNR_GetError) function. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
int32 __stdcall RFmxNR_SelectMeasurements (niRFmxInstrHandle instrumentHandle, char selectorString[], uInt32 measurements, int32 enableAllTraces);
Enables all the measurements that you specify in the measurement parameter and disables all other measurements.
| Input | ||
|---|---|---|
| Name | Type | Description |
| instrumentHandle | niRFmxInstrHandle | Specifies the instrument session. The RFmx driver obtains this parameter from the RFmxNR_Initialize) function. |
| selectorString | char[] | Specifies a selector string) comprising of the signal name. If you do not specify the signal name, the default signal instance is used. Example: "signal::sig1" You can use the RFmxNR_BuildSignalString) function to build the selector string. |
| measurements | uInt32 | Specifies the measurements to perform. You can specify one or more of the following measurements. |
| enableAllTraces | int32 | Specifies whether to enable all traces for the selected measurement. |
| Name | Type | Description |
|---|---|---|
| status | int32 | Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. Examine the status code from each call to an RFmx function to determine if an error has occurred. To obtain a text description of the status code and additional information about the error condition, call the RFmxNR_GetError) function. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
int32 __stdcall RFmxNR_Initiate (niRFmxInstrHandle instrumentHandle, char selectorString[], char resultName[]);
Initiates all enabled measurements. Call this function after configuring the signal and measurement. This function asynchronously launches measurements in the background and immediately returns to the caller program. You can fetch measurement results using the Fetch functions or result attributes in the attribute node. To get the status of measurements, use the RFmxNR_WaitforMeasurementComplete) function or RFmxNR_CheckMeasurementStatus) function.
| Input | ||
|---|---|---|
| Name | Type | Description |
| instrumentHandle | niRFmxInstrHandle | Specifies the instrument session. The RFmx driver obtains this parameter from the RFmxNR_Initialize) function. |
| selectorString | char[] | Specifies the signal name and result name. The result name can either be specified through this input or the resultName parameter. If you do not specify the signal name, the default signal instance is used. If you do not specify the result name in this parameter, either the result name specified by the resultName parameter or the default result instance is used. Example: "" "signal::sig1" "result::r1" "signal::sig1/result::r1" You can use the RFmxNR_BuildSignalString) function to build the selector string). |
| resultName | char[] | Specifies the name to be associated with measurement results. Provide a unique name, such as "r1" to enable fetching of multiple measurement results and traces. This input accepts the result name with or without the "result::" prefix. Example: "result::r1" "r1" |
| Name | Type | Description |
|---|---|---|
| status | int32 | Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. Examine the status code from each call to an RFmx function to determine if an error has occurred. To obtain a text description of the status code and additional information about the error condition, call the RFmxNR_GetError) function. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
int32 __stdcall RFmxNR_GetError (niRFmxInstrHandle instrumentHandle, int32* errorCode, int32 errorDescriptionBufferSize, char errorDescription[]);
Retrieves and then clears the error information for the session or the current execution thread. You must provide a char array to serve as a buffer for the value. Pass the number of bytes in the buffer as the errorDescriptionBufferSize parameter.
If the error description, including the terminating NULL byte, is larger than the size you indicate in the errorDescriptionBufferSize parameter, the function copies buffer size - 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 want to call this function just to get the required buffer size, you must pass 0 for errorDescriptionBufferSize and NULL for the errorDescription buffer.
|
Note Use the RFmxNR_GetErrorString) function if the RFmxNR_GetError function does not return an error message. |
|---|
| Input | ||
|---|---|---|
| Name | Type | Description |
| instrumentHandle | niRFmxInstrHandle | Specifies the RFmx session. If a valid session handle is passed, the last error stored in that session is retrieved. You can pass NULL to retrieve the last error stored in the current execution thread. |
| errorCode | int32* | Returns the error code for the session or execution thread. If you pass 0 for the errorDescriptionBufferSize parameter, you can pass NULL for the errorCode parameter. |
| errorDescriptionBufferSize | int32 | Passes the number of bytes in the char array you specify in the errorDescription 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 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. |
| errorDescription | char[] | Returns the error description for the 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. |
| Name | Type | Description |
|---|
int32 __stdcall RFmxNR_GetErrorString (niRFmxInstrHandle instrumentHandle, int32 errorCode, int32 errorDescriptionBufferSize, char errorDescription[]);
Converts a status code returned by an RFmxNR function into a user-readable string. You must provide a char array to serve as a buffer for the value. Pass the number of bytes in the buffer as the errorDescriptionBufferSize parameter.
If the error description, including the terminating NULL byte, is larger than the size you indicate in the errorDescriptionBufferSize parameter, the function copies buffer size - 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 want to call this function just to get the required buffer size, you must pass 0 for errorDescriptionBufferSize and NULL for the errorDescription buffer.
| Input | ||
|---|---|---|
| Name | Type | Description |
| instrumentHandle | niRFmxInstrHandle | Specifies the instrument session. The RFmx driver obtains this parameter from the RFmxNR_Initialize) function. |
| errorCode | int32* | Returns the error code for the session or execution thread. If you pass 0 for the errorDescriptionBufferSize parameter, you can pass NULL for the errorCode parameter. |
| errorDescriptionBufferSize | int32 | Passes the number of bytes in the char array you specify in the errorDescription 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 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. |
| errorDescription | char[] | Returns the error description for the 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. |
| Name | Type | Description |
|---|---|---|
| statusOrRequiredSize | int32 | Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. Examine the status code from each call to an RFmx function to determine if an error has occurred. When the statusOrRequiredSize 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 RFmxNR_GetError) function. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
int32 __stdcall RFmxNR_Close (niRFmxInstrHandle instrumentHandle, int32 forceDestroy);
Closes the RFmx session.
This function is a wrapper over the RFmx Instruments API, and calls the RFmxInstr_Close) function.
| Input | ||
|---|---|---|
| Name | Type | Description |
| instrumentHandle | niRFmxInstrHandle | Specifies the instrument session. The RFmx driver obtains this parameter from the RFmxNR_Initialize) function. |
| forceDestroy | int32 | Specifies whether to destroy the RFmx session. |
| RFMXNR_VAL_FALSE (0) | Destroys the RFmx session. Call the RFmxNR_Close function a number of times equal to the number of times you obtained a reference to the RFmx session. |
|---|---|
| RFMXNR_VAL_TRUE (1) | Destroys the RFmx session. You do not have to call the RFmxNR_Close function multiple times. Destroying the RFmx session invalidates all references to the session. |
| Name | Type | Description |
|---|---|---|
| status | int32 | Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. Examine the status code from each call to an RFmx function to determine if an error has occurred. To obtain a text description of the status code and additional information about the error condition, call the RFmxNR_GetError) function. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |