ncStatusToString
Purpose
Convert status code into a descriptive string.
Format
| void | ncStatusToString(
|
Input
Status
Nonzero status code returned from NI-CAN function.
SizeofString
Size of String buffer (in bytes).
Output
String
ASCII string that describes Status.
Description
When the status code returned from an NI-CAN function is nonzero, an error or warning is indicated. This function is used to obtain a description of the error/warning for debugging purposes.
If you want to avoid displaying error messages while debugging the application, you can use the Explain.exe utility. This console application is located in the Utilities subfolder of the NI-CAN installation folder, which is typically \Program Files\National Instruments\NI-CAN\Utilities. You enter an NI-CAN status code in the command line, Explain 0XBFF62201 for example, and the utility displays the description.
The return code is passed into the Status parameter. The SizeofString parameter indicates the number of bytes available in String for the description. The description will be truncated to size SizeofString if needed, but a size of 2048 characters is large enough to hold any description. The text returned in String is null-terminated, so it can be used with ANSI C functions such as printf.
For applications written in C or C++, each NI-CAN function returns a status code as a signed 32-bit integer. The following table summarizes the NI-CAN use of this status.
NI-CAN 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 attention. |
| Zero | Success—Function completed successfully. |
The application code should check the status returned from every NI-CAN function. If an error is detected, you should close all NI-CAN handles, then exit the application. If a warning is detected, you can display a message for debugging purposes, or simply ignore the warning.
The following piece of code shows an example of handling NI-CAN status during application debugging.
status= ncOpenObject ("CAN0", &MyObjHandle);
PrintStat (status, "ncOpenObject CAN0");
where the function PrintStat has been defined at the top of the program as:
void PrintStat(NCTYPE_STATUS status,char *source)
{
char statusString[2048];
if(status !=0)
{
ncStatusToString(status, size of (statusString), statusString);
printf("\n%s\nSource = %s\n", statusString, source);
if (status < 0)
{
ncCloseObject(MyObjHandle);
exit(1);
}
}
}
In some situations, you may want to check for specific errors in the code. For example, when ncWaitForState times out, you may want to continue communication, rather than exit the application. To check for specific errors, use the constants defined in nican.h. These constants have the same names as described in this help file. For example, to check for a function timeout:
if (status ==CanErrFunctionTimeout)
The function ncStatusToString returns the string results as an array of char (* char). VB is not able to convert this array to a string automatically. Therefore, VB users should call the wrapper function ncStatToStr.