ncStatusToString (Status To String)
Purpose
Convert status returned from an NI-DNET function into a descriptive string.
Format
LabVIEW
Not applicable
For LabVIEW, NI-DNET functions use the standard error in and error out clusters for status information. You can view error descriptions using built-in LabVIEW features such as Explain Error in the Help menu, or the Simple Error Handler VI in your diagram.
C
| void | ncStatustoString(
NCTYPE_STATUS Status,
NCTYPE_UINT32 SizeofString,
NCTYPE_STRING String); |
Input
| Status | Status returned from a previous function call |
| SizeofString | Size of String buffer in bytes |
Output
| String | Textual string which describes the function status |
Function Description
For applications written in C, C++, or Visual Basic, each NI-DNET function returns a status code as a signed 32-bit integer. The following table summarizes the NI-DNET use of this status:
NI-DNET Status Codes
| Status Code | Meaning |
|---|---|
| Negative | Error—Function did not perform expected behavior. |
| Positive | Warning—Function performed as expected, but a condition arose that may require your attention. |
| Zero | Success—Function completed successfully. |
ncStatusToString converts a status value returned from an NI-DNET function into a descriptive string. By displaying this string when an error or warning is detected, you can avoid interpretation of the numeric code to debug the problem.
The ncStatustoString function is not applicable to LabVIEW programming. For LabVIEW, NI-DNET functions use the standard error in and error out clusters for status information. You can view error descriptions using built-in LabVIEW features such as Explain Error in the Help menu, or the Simple Error Handler VI in your diagram.
If you want to avoid displaying error messages while debugging your application, you can use the Explain.exe utility. This console application is in the Utilities subfolder of the NI-DNET installation folder, which is typically \Program Files\National Instruments\NI-DNET\Utilities. You enter an NI-DNET status code in the command line (such as Explain 0xBFF62001), and the utility displays the description.
Your application code should check the status returned from every NI-DNET function. If an error is detected, you should close all NI-DNET handles, then exit the application. If a warning is detected, you can display a message for debugging purposes, or simply ignore the warning.
Parameter Descriptions
Status
| Description | Status must contain a status value returned from a previous call to an NI-DNET function. You normally call ncStatustoString only when the status is nonzero, indicating an error or warning condition. |
| Values | Value of data type NCTYPE_STATUS, returned from an NI-DNET function call |
SizeofString
| Description | SizeofString is the size of the buffer referenced by String. The ncStatustoString function copies at most SizeofString bytes into the string and cuts off the text as needed. You can normally obtain this size using the C language sizeof function. Although you can often obtain an adequate description with fewer bytes, a 512-byte buffer is large enough to hold any NI-DNET status description. |
| Values | sizeof (buffer referenced by String) |
String
| Description | Textual string which describes the function status. The string is NULL terminated like any other C language string. The number of bytes returned is the smaller of SizeofString and the number of bytes contained in the actual description. |
| Values | Textual string which describes the function status |
Example
C
Check the status returned from the ncOpenDnetIntf function, and if not success, print a descriptive string.
NCTYPE_STATUS status;
NCTYPE_OBJH objh;
char descr[1024];
status = ncOpenDnetIntf("DNET0", 0, 125000, NC_POLL_AUTO, &objh);
if (status != DnetSuccess) {
ncStatustoString(status, sizeof(descr), descr);
printf("ncOpenDnetIntf: %s\n", descr);
}