Skip to content

NI SCOPE Error Handling Functions

Kevin Reimnitz edited this page Mar 24, 2021 · 1 revision

Error Handling Functions

niScope_errorHandler

C Function Prototype

ViStatus niScope_errorHandler (ViSession vi, ViInt32 errorCode, ViChar errorSource[MAX_FUNCTION_NAME_SIZE], ViChar errorDescription[MAX_ERROR_DESCRIPTION]);

Purpose

Takes the error code returned by NI-SCOPE functions and returns the interpretation as a user-readable string.

Note  You can pass VI_NULL as the instrument handle, which is useful to interpret errors after niScope_init has failed.

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
errorCode ViStatus The error code that is returned from any of the instrument driver functions.
errorSource[] ViChar

Specifies the function in which the error occurred. You can pass in a string no longer than MAX_FUNCTION_NAME_SIZE. If you pass in a valid string, this source is included in the errorDescription string. For example:

"Error <errorCode> at <errorSource>"

If you pass in NULL or an empty string, this parameter is ignored.

Output
Name Type Description
errorDescription[] ViChar Returns the interpreted error code as a user readable message string; you must pass a ViChar array at least MAX_ERROR_DESCRIPTION bytes in length.

Return Value

Name Type Description
Status ViStatus Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors


niScope_GetError

C Function Prototype

ViStatus niScope_GetError (ViSession vi, ViStatus* errorCode, ViInt32 bufferSize, ViChar[] description);

Purpose

Note   This function is included for compliance with the IviScope Class Specification.
Reads an error code and message from the error queue. National Instruments digitizers do not contain an error queue. Errors are reported as they occur. Therefore, this function does not detect errors.

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
errorCode ViStatus* Pass the Error Code that is returned from any of the instrument driver functions.
Output
Name Type Description
bufferSize ViInt32

Passes 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 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 description 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 Buffer Size parameter.

If you pass 0 for the bufferSize, you can pass VI_NULL for this parameter.

Return Value

Name Type Description
Status ViStatus Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors


niScope_GetErrorMessage

C Function Prototype

ViStatus niScope_GetErrorMessage (ViSession vi, ViStatus errorCode, ViInt32 bufferSize, ViChar errorMessage[]);

Purpose

Returns the error code from an NI-SCOPE function as a user-readable string. Use VI_NULL as the default instrument handle.

You must call this function twice. For the first call, set bufferSize to 0 to prevent the function from populating the error message. Instead, the function returns the size of the error string. Use the returned size to create a buffer, then call the function again, passing in the new buffer and setting bufferSize equal to the size that was returned in the first function call.

Parameters

Input
Name Type Description
vi ViSession The instrument handle you obtain from niScope_init that identifies a particular instrument session.
errorCode ViStatus The error code that is returned from any of the instrument driver functions.
bufferSize The number of characters you specify for the errorMessage parameter.
Output
Name Type Description
errorMessage[] ViChar Returns a char buffer that will be populated with the error message. It should be at least as large as the buffer size.

Return Value

Name Type Description
Status ViStatus Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors


Table of Contents

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