NI FGEN Utility Functions - ni/grpc-device GitHub Wiki
- niFgen_GetHardwareState
- niFgen_WaitUntilDone
- niFgen_IsDone
- niFgen_ResetWithDefaults
- niFgen_ResetDevice
- niFgen_Disable
- niFgen_self_test
- niFgen_revision_query
- niFgen_GetNextCoercionRecord
- niFgen_LockSession
- niFgen_UnlockSession
- niFgen_Commit
- niFgen_reset
ViStatus niFgen_Commit (ViSession vi);
Causes a transition to the Committed state. This function verifies attribute values, reserves the device, and commits the attribute values to the device. If the attribute values are all valid, NI-FGEN sets the device hardware configuration to match the session configuration. This function does not support the NI 5401/5404/5411/5431 signal generators.
In the Committed state, you can load waveforms, scripts, and sequences into memory. If any attributes are changed, NI-FGEN implicitly transitions back to the Idle state, where you can program all session properties before applying them to the device. This function has no effect if the device is already in the Committed or Generating state and returns a successful status value.
Calling this VI before the niFgen Initiate Generation VI is optional but has the following benefits:
- Routes are committed, so signals are exported or imported.
- Any Reference Clock and external clock circuits are phase-locked.
- A subsequent niFgen_InitiateGeneration function can run faster because the device is already configured.
| Input | ||
|---|---|---|
| Name | Type | Description |
| vi | ViSession | Identifies your instrument session. vi is obtained from the niFgen_init, niFgen_InitWithOptions, or niFgen_InitializeWithChannels functions and identifies a particular instrument session. |
| 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. You can examine the status code from each call to an NI-FGEN function to determine if an error occurred. To obtain a text description of the status code, call theniFgen_error_message function. To obtain additional information about the error condition, call the niFgen_GetError function. To clear the error information from NI-FGEN, call the niFgen_ClearError function. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus niFgen_reset (ViSession vi);
Resets the instrument to a known state. This function aborts the generation, clears all routes, and resets session attributes to the default values. This function does not, however, commit the session properties or configure the device hardware to its default state.
Note: For the NI 5401/5404/5411/5431, this function exhibits the same behavior as the niFgen_ResetDevice function.
| Input | ||
|---|---|---|
| Name | Type | Description |
| vi | ViSession | Identifies your instrument session. vi is obtained from the niFgen_init, niFgen_InitWithOptions, or niFgen_InitializeWithChannels functions and identifies a particular instrument session. |
| 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. You can examine the status code from each call to an NI-FGEN function to determine if an error occurred. To obtain a text description of the status code, call theniFgen_error_message function. To obtain additional information about the error condition, call the niFgen_GetError function. To clear the error information from NI-FGEN, call the niFgen_ClearError function. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus niFgen_GetHardwareState (ViSession vi, ViInt32* state);
Returns the current hardware state of the device and, if the device is in the hardware error state, the current hardware error.
Note: Hardware states do not necessarily correspond to NI-FGEN states.
| Input | ||
|---|---|---|
| Name | Type | Description |
| vi | ViSession | Identifies your instrument session. vi is obtained from the niFgen_init, niFgen_InitWithOptions, or niFgen_InitializeWithChannels functions and identifies a particular instrument session. |
| Output | ||
| Name | Type | Description |
| state | ViInt32* |
Returns the hardware state of the signal generator. Defined Values |
| NIFGEN_VAL_IDLE | The device is in the Idle state. |
|---|---|
| NIFGEN_VAL_WAITING_FOR_START_TRIGGER | The device is waiting for Start Trigger. |
| NIFGEN_VAL_RUNNING | The device is in the Running state. |
| NIFGEN_VAL_DONE | The generation has completed successfully. |
| NIFGEN_VAL_HARDWARE_ERROR | There is a hardware error. |
| 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. You can examine the status code from each call to an NI-FGEN function to determine if an error occurred. To obtain a text description of the status code, call theniFgen_error_message function. To obtain additional information about the error condition, call the niFgen_GetError function. To clear the error information from NI-FGEN, call the niFgen_ClearError function. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus niFgen_WaitUntilDone (ViSession vi, ViInt32 maxtime);
Waits until the device is done generating or until the maximum time has expired.
| Input | ||
|---|---|---|
| Name | Type | Description |
| vi | ViSession | Identifies your instrument session. vi is obtained from the niFgen_init, niFgen_InitWithOptions, or niFgen_InitializeWithChannels functions and identifies a particular instrument session. |
| maxTime | ViInt32 | Specifies the timeout value in milliseconds. |
| 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. You can examine the status code from each call to an NI-FGEN function to determine if an error occurred. To obtain a text description of the status code, call theniFgen_error_message function. To obtain additional information about the error condition, call the niFgen_GetError function. To clear the error information from NI-FGEN, call the niFgen_ClearError function. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus niFgen_IsDone (ViSession vi, ViBoolean* done);
Determines whether the current generation is complete. This function sets the done parameter to VI_TRUE if the session is in the Idle or Committed states.
Note: NI-FGEN only reports the done parameter as VI_TRUE after the current generation is complete in Single trigger mode.
| Input | ||
|---|---|---|
| Name | Type | Description |
| vi | ViSession | Identifies your instrument session. vi is obtained from the niFgen_init, niFgen_InitWithOptions, or niFgen_InitializeWithChannels functions and identifies a particular instrument session. |
| Output | ||
| Name | Type | Description |
| done | ViBoolean* |
Returns information about the completion of waveform generation. Defined Values |
| VI_TRUE | Generation is complete. |
|---|---|
| VI_FALSE | Generation is not complete. |
| 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. You can examine the status code from each call to an NI-FGEN function to determine if an error occurred. To obtain a text description of the status code, call theniFgen_error_message function. To obtain additional information about the error condition, call the niFgen_GetError function. To clear the error information from NI-FGEN, call the niFgen_ClearError function. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus niFgen_ResetWithDefaults (ViSession vi);
Resets the instrument and reapplies initial user–specified settings from the logical name that was used to initialize the session. If the session was created without a logical name, this function is equivalent to the niFgen_reset function.
| Input | ||
|---|---|---|
| Name | Type | Description |
| vi | ViSession | Identifies your instrument session. vi is obtained from the niFgen_init, niFgen_InitWithOptions, or niFgen_InitializeWithChannels functions and identifies a particular instrument session. |
| 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. You can examine the status code from each call to an NI-FGEN function to determine if an error occurred. To obtain a text description of the status code, call theniFgen_error_message function. To obtain additional information about the error condition, call the niFgen_GetError function. To clear the error information from NI-FGEN, call the niFgen_ClearError function. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus niFgen_ResetDevice (ViSession vi);
Performs a hard reset on the device. Generation is stopped, all routes are released, external bidirectional terminals are tristated, FPGAs are reset, hardware is configured to its default state, and all session attributes are reset to their default states.
| Input | ||
|---|---|---|
| Name | Type | Description |
| vi | ViSession | Identifies your instrument session. vi is obtained from the niFgen_init, niFgen_InitWithOptions, or niFgen_InitializeWithChannels functions and identifies a particular instrument session. |
| 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. You can examine the status code from each call to an NI-FGEN function to determine if an error occurred. To obtain a text description of the status code, call theniFgen_error_message function. To obtain additional information about the error condition, call the niFgen_GetError function. To clear the error information from NI-FGEN, call the niFgen_ClearError function. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus niFgen_Disable (ViSession vi);
Places the instrument in a quiescent state where it has minimal or no impact on the system to which it is connected. The analog output and all exported signals are disabled.
| Input | ||
|---|---|---|
| Name | Type | Description |
| vi | ViSession | Identifies your instrument session. vi is obtained from the niFgen_init, niFgen_InitWithOptions, or niFgen_InitializeWithChannels functions and identifies a particular instrument session. |
| 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. You can examine the status code from each call to an NI-FGEN function to determine if an error occurred. To obtain a text description of the status code, call theniFgen_error_message function. To obtain additional information about the error condition, call the niFgen_GetError function. To clear the error information from NI-FGEN, call the niFgen_ClearError function. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus niFgen_self_test (ViSession vi, ViInt16* selfTestResult, ViChar[] selfTestMessage);
Runs the instrument self-test routine and returns the test result(s).
Note: When used on some signal generators, the device is reset after the niFgen_self_test function runs. If you use the niFgen_self_test function, your device may not be in its previously configured state after the function runs.
| Input | ||
|---|---|---|
| Name | Type | Description |
| vi | ViSession | Identifies your instrument session. vi is obtained from the niFgen_init, niFgen_InitWithOptions, or niFgen_InitializeWithChannels functions and identifies a particular instrument session. |
| Output | ||
| Name | Type | Description |
| selfTestResult | ViInt16 | Contains the value returned from the instrument self-test. A value of 0 indicates success. |
| Self-Test Code | Description |
|---|---|
| 0 | Passed self-test |
| 1 | Self-test failed |
| Name | Type | Description |
|---|---|---|
| selfTestMessage | ViChar[] |
Returns the self-test response string from the instrument. You must pass a ViChar array with at least 256 bytes. |
| 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. You can examine the status code from each call to an NI-FGEN function to determine if an error occurred. To obtain a text description of the status code, call theniFgen_error_message function. To obtain additional information about the error condition, call the niFgen_GetError function. To clear the error information from NI-FGEN, call the niFgen_ClearError function. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus niFgen_revision_query (ViSession vi, ViChar[] instrumentDriverRevision, ViChar[] firmwareRevision);
Returns the revision numbers of the NI-FGEN and instrument firmware.
| Input | ||
|---|---|---|
| Name | Type | Description |
| vi | ViSession | Identifies your instrument session. vi is obtained from the niFgen_init, niFgen_InitWithOptions, or niFgen_InitializeWithChannels functions and identifies a particular instrument session. |
| Output | ||
| Name | Type | Description |
| instrumentDriverRevision | ViChar[] |
Returns the NI-FGEN software revision numbers in the form of a string. You must pass a ViChar array with at least 256 bytes. |
| firmwareRevision | ViChar[] |
Returns the instrument firmware revision numbers in the form of a string. You must pass a ViChar array with at least 256 bytes. |
| 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. You can examine the status code from each call to an NI-FGEN function to determine if an error occurred. To obtain a text description of the status code, call theniFgen_error_message function. To obtain additional information about the error condition, call the niFgen_GetError function. To clear the error information from NI-FGEN, call the niFgen_ClearError function. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus niFgen_GetNextCoercionRecord (ViSession vi, ViInt32 bufferSize, ViChar[] coercionRecord);
Returns the coercion information associated with the IVI session. This function retrieves and clears the oldest instance in which the NI-FGEN coerced a value you specified to another value.
If you set the NIFGEN_ATTR_RECORD_COERCIONS attribute to VI_TRUE, NI-FGEN keeps a list of all coercions it makes on ViInt32 or ViReal64 values that you pass to NI-FGEN functions. You use this function to retrieve information from that list.
If the next coercion record string, including the terminating NUL byte, contains more bytes than you indicate in this parameter, the function copies bufferSize – 1 bytes into the buffer, places an ASCII NUL 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 bufferSize is 4, the function places 123 into the buffer and returns 7.
If you pass a negative number, the function copies the value to the buffer regardless of the number of bytes in the value.
If you pass 0, you can pass VI_NULL for the coercionRecord buffer parameter.
The function returns an empty string in the coercionRecord parameter if no coercion records remain for the session.
| Input | ||
|---|---|---|
| Name | Type | Description |
| vi | ViSession | Identifies your instrument session. vi is obtained from the niFgen_init, niFgen_InitWithOptions, or niFgen_InitializeWithChannels functions and identifies a particular instrument session. |
| bufferSize | ViInt32 |
Specifies the number of bytes in the ViChar array you specify for the coercionRecord parameter. If the next coercion record string, including the terminating NUL byte, contains more bytes than you indicate in this parameter, the function copies bufferSize – 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size 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 a negative number, the function copies the value to the buffer regardless of the number of bytes in the value. If you pass 0, you can pass VI_NULL for the coercionRecord buffer parameter. Default Value: None |
| Output | ||
| Name | Type | Description |
| coercionRecord | ViChar[] |
Returns the next coercion record for the IVI session. If there are no coercion records, 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 next coercion record string, including the terminating NUL byte, contains more bytes than you indicate with the bufferSize parameter, the function copies bufferSize – 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size that you must pass to get the entire value. For example, if the value is "123456" and bufferSize is 4, the function places "123" into the buffer and returns 7. This parameter returns an empty string if no coercion records remain for the session. |
| 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. You can examine the status code from each call to an NI-FGEN function to determine if an error occurred. To obtain a text description of the status code, call niFgen_error_message. To obtain additional information about the error condition, call niFgen_GetError. To clear the error information from NI-FGEN, call niFgen_ClearError. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus niFgen_LockSession (ViSession vi, ViBoolean* callerHasLock);
Obtains a multithread lock on the instrument session. Before it does 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 called the niFgen_LockSession function.
- A call to the NI-FGEN locked the session.
- A call to the IVI Engine locked the session.
After your call to the niFgen_LockSession function returns successfully, no other threads can access the instrument session until you call the niFgen_UnlockSession function.
Use the niFgen_LockSession function and the niFgen_UnlockSession function around a sequence of calls to NI-FGEN functions if you require that the instrument retain its settings through the end of the sequence.
You can safely make nested calls to the niFgen_LockSession function within the same thread. To completely unlock the session, you must balance each call to the niFgen_LockSession function with a call to the niFgen_UnlockSession function. If, however, you use the callerHasLock parameter in all calls to the niFgen_LockSession function and the niFgen_UnlockSession function within a function, the IVI Engine locks the session only once within the function regardless of the number of calls you make to the niFgen_LockSession function. This configuration allows you to call the niFgen_UnlockSession function just once at the end of the function.
| Input | ||
|---|---|---|
| Name | Type | Description |
| vi | ViSession | Identifies your instrument session. vi is obtained from the niFgen_init, niFgen_InitWithOptions, or niFgen_InitializeWithChannels functions and identifies a particular instrument session. |
| Output | ||
| Name | Type | Description |
| callerHasLock | ViBoolean* |
Keeps track of whether you obtained 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 niFgen_LockSession function or the niFgen_UnlockSession function in the same function. This parameter serves as a convenience. If you do not want to use this parameter, pass VI_NULL. This parameter is an input/output parameter. The niFgen_LockSession function and the niFgen_UnlockSession function each inspect the current value and take the following actions: - If the value is VI_TRUE, the niFgen_LockSession function does not lock the session again. If the value is VI_FALSE, the niFgen_LockSession function obtains the lock and sets the value of the parameter to VI_TRUE. - If the value is VI_FALSE, the niFgen_UnlockSession function does not attempt to unlock the session. If the value is VI_TRUE, the niFgen_UnlockSession function releases the lock and sets the value of the parameter to VI_FALSE. Thus, you can call the niFgen_UnlockSession function at the end of your function without worrying about whether you actually have the lock. Example: ViStatus TestFunc (ViSession vi, ViInt32 flags) ViStatus error = VI_SUCCESS; viCheckErr( niFgen_LockSession(vi, &haveLock)); viCheckErr( niFgen_UnlockSession(vi, &haveLock)); } viCheckErr( TakeAction3(vi)); } Error: /* } |
| 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. You can examine the status code from each call to an NI-FGEN function to determine if an error occurred. To obtain a text description of the status code, call theniFgen_error_message function. To obtain additional information about the error condition, call the niFgen_GetError function. To clear the error information from NI-FGEN, call the niFgen_ClearError function. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus niFgen_UnlockSession (ViSession vi, ViBoolean* callerHasLock);
Releases a lock that you acquired on an instrument session using the niFgen_LockSession function.
| Input | ||
|---|---|---|
| Name | Type | Description |
| vi | ViSession | Identifies your instrument session. vi is obtained from the niFgen_init, niFgen_InitWithOptions, or niFgen_InitializeWithChannels functions 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. This parameter serves as a convenience. If you do not want to use this parameter, pass VI_NULL. 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 niFgen_LockSession function or the niFgen_UnlockSession function in the same function. The parameter is an input/output parameter. The niFgen_LockSession function and the niFgen_UnlockSession function each inspect the current value and take the following actions: - If the value is VI_TRUE, the niFgen_LockSession function does not lock the session again. If the value is VI_FALSE, the niFgen_LockSession function obtains the lock and sets the value of the parameter to VI_TRUE. - If the value is VI_FALSE, the niFgen_UnlockSession function does not attempt to unlock the session. If the value is VI_TRUE, the niFgen_UnlockSession function releases the lock and sets the value of the parameter to VI_FALSE. Thus, you can, call the niFgen_UnlockSession function at the end of your function without worrying about whether you actually have the lock. Example: ViStatus TestFunc (ViSession vi, ViInt32 flags) ViStatus error = VI_SUCCESS; viCheckErr(niFgen_LockSession(vi, &haveLock)); viCheckErr( niFgen_UnlockSession(vi, &haveLock)); } viCheckErr( TakeAction3(vi)); } Error: /* } |
| 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. You can examine the status code from each call to an NI-FGEN function to determine if an error occurred. To obtain a text description of the status code, call theniFgen_error_message function. To obtain additional information about the error condition, call the niFgen_GetError function. To clear the error information from NI-FGEN, call the niFgen_ClearError function. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |