NI FGEN Error Functions

Error Functions

• niFgen_error_query
• niFgen_ErrorHandler
• niFgen_error_message
• niFgen_GetError
• niFgen_ClearError

niFgen_error_query

ViStatus niFgen_error_query (ViSession vi, ViInt32* errorCode, ViChar[] Error_Message);

Purpose

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

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
errorCode	ViInt32*	Returns the error code read from the instrument error queue.
errorMessage	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. 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 the niFgen_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_ErrorHandler

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

Purpose

Converts a status code returned by an NI-FGEN function into a user-readable string and returns any error elaborations.

Parameters

Input
Name	Type	Description
vi	ViSession	Identifies your instrument session. vi is obtained from the niFgen_init, niFgen_InitWithOptions functions and identifies a particular instrument session. You can pass VI_NULL for this parameter. Passing VI_NULL is useful when one of the initialize functions fails. Default Value: VI_NULL
errorCode	ViStatus	Specifies the status parameter that is returned from any of the NI-FGEN functions. Default Value: 0 (VI_SUCCESS)
Output
Name	Type	Description
errorMessage	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. 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 the niFgen_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_error_message

ViStatus niFgen_error_message (ViSession vi, ViStatus errorCode, ViChar[] Error_Message);

Purpose

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

Parameters

Input
Name	Type	Description
vi	ViSession	Identifies your instrument session. vi is obtained from the niFgen_init, niFgen_InitWithOptions functions and identifies a particular instrument session. You can pass VI_NULL for this parameter. Passing VI_NULL is useful when one of the initialize functions fails. Default Value: VI_NULL
errorCode	ViStatus	Specifies the status parameter that is returned from any of the NI-FGEN functions. Default Value: 0 (VI_SUCCESS)
Output
Name	Type	Description
errorMessage	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. 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 the niFgen_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_GetError

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

Purpose

Returns the error information associated with an IVI session or with the current execution thread. If you specify a valid IVI session for the vi parameter, this function retrieves and then clears the error information for the session. If you pass VI_NULL for the vi parameter, this function retrieves and then clears the error information for the current execution thread.

The IVI Engine also maintains this error information separately for each thread. This feature is useful if you do not have a session handle to pass to the niFgen_GetError or niFgen_ClearError functions. This situation occurs when a call to the niFgen_init, niFgen_InitWithOptions function fails.

Parameters

Input
Name	Type	Description
vi	ViSession	Identifies your instrument session. vi is obtained from the niFgen_init, niFgen_InitWithOptions functions and identifies a particular instrument session. You can pass VI_NULL for this parameter. Passing VI_NULL is useful when one of the initialize functions fail. Default Value: VI_NULL
errorDescriptionBufferSize	ViInt32	Specifies the size of the errorDescription array. You can determine the array size needed to store the entire error description by setting this parameter to 0. The function then ignores the errorDescription buffer, which may be set to VI_NULL, and gives as its return value the required buffer size. You can then call the function a second time using the correct buffer size.
Output
Name	Type	Description
errorCode	ViStatus*	The error code for the session or execution thread. A value of VI_SUCCESS (0) indicates that no error occurred. A positive value indicates a warning. A negative value indicates an error. You can call niFgen_error_message to get a text description of the value. If you are not interested in this value, you can pass VI_NULL.
errorDescription	ViChar[]	The error description string for the session or execution thread. If the error code is nonzero, the description string can further describe the error or warning condition. If you are not interested in this value, you can pass VI_NULL. Otherwise, you must pass a ViChar array of a size specified with the errorDescriptionBufferSize 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. 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 the niFgen_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_ClearError

ViStatus niFgen_ClearError (ViSession vi);

Purpose

Clears the error information for the current execution thread and the IVI session you specify. If you pass VI_NULL for the vi parameter, this function clears the error information only for the current execution thread.

This function sets the error code to VI_SUCCESS (0), and sets the error description string to "" (empty string).

The IVI Engine also maintains this error information separately for each thread. This feature is useful if you do not have a session handle to pass to the niFgen_ClearError or the niFgen_GetError function. This situation occurs when a call to the niFgen_init, niFgen_InitWithOptions function fails.

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 the niFgen_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