NI FGEN Utility Functions

Utility Functions

• 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

niFgen_Commit

ViStatus niFgen_Commit (ViSession vi);

Purpose

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.

Parameters

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.

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. 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

niFgen_reset

ViStatus niFgen_reset (ViSession vi);

Purpose

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.

Parameters

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.

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. 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

niFgen_GetHardwareState

ViStatus niFgen_GetHardwareState (ViSession vi, ViInt32* state);

Purpose

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.

Parameters

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.

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. 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

niFgen_WaitUntilDone

ViStatus niFgen_WaitUntilDone (ViSession vi, ViInt32 maxtime);

Purpose

Waits until the device is done generating or until the maximum time has expired.

Parameters

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.

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. 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

niFgen_IsDone

ViStatus niFgen_IsDone (ViSession vi, ViBoolean* done);

Purpose

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.

Parameters

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.

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. 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

niFgen_ResetWithDefaults

ViStatus niFgen_ResetWithDefaults (ViSession vi);

Purpose

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.

Parameters

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.

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. 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

niFgen_ResetDevice

ViStatus niFgen_ResetDevice (ViSession vi);

Purpose

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.

Parameters

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.

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. 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

niFgen_Disable

ViStatus niFgen_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. The analog output and all exported signals are disabled.

Parameters

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.

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. 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

niFgen_self_test

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

Purpose

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.

Parameters

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.

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. 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

niFgen_revision_query

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

Purpose

Returns the revision numbers of the NI-FGEN and instrument firmware.

Parameters

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.

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. 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

niFgen_GetNextCoercionRecord

ViStatus niFgen_GetNextCoercionRecord (ViSession vi, ViInt32 bufferSize, ViChar[] coercionRecord);

Purpose

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.

Parameters

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.

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. 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

niFgen_LockSession

ViStatus niFgen_LockSession (ViSession vi, ViBoolean* callerHasLock);

Purpose

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.

Parameters

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; ViBoolean haveLock = VI_FALSE; if (flags & BIT_1) { viCheckErr( niFgen_LockSession(vi, &haveLock)); viCheckErr( TakeAction1(vi)); if (flags & BIT_2) { viCheckErr( niFgen_UnlockSession(vi, &haveLock)); viCheckErr( TakeAction2(vi)); viCheckErr( niFgen_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. */ niFgen_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. 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

niFgen_UnlockSession

ViStatus niFgen_UnlockSession (ViSession vi, ViBoolean* callerHasLock);

Purpose

Releases a lock that you acquired on an instrument session using the niFgen_LockSession function.

Parameters

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; ViBoolean haveLock = VI_FALSE; if (flags & BIT_1) { viCheckErr(niFgen_LockSession(vi, &haveLock)); viCheckErr( TakeAction1(vi)); if (flags & BIT_2) { viCheckErr( niFgen_UnlockSession(vi, &haveLock)); viCheckErr( TakeAction2(vi)); viCheckErr( niFgen_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. */ niFgen_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. 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