NI-CAN Legacy Error Descriptions
As of version 1.5 of NI-CAN, the encoding of error codes returned from all functions
was changed.
The new error encoding provides the following benefits:
- NI-CAN errors are now included in the scheme used for all National Instruments
products, and therefore the standard error-handling functions of LabVIEW and
Measurement Studio now recognize and describe NI-CAN errors.
- In LabVIEW, you no longer need to write down a numeric error value in order to
look it up in the NI-CAN Programmer Reference Manual. LabVIEW's standard
Simple Error Handler.vi now provides complete information on the NI-CAN error.
- In Visual C/C++ and Borland C/C++, you no longer need to use a long CheckStat()
function in order to obtain a description of the NI-CAN error. A new
ncStatusToString function returns a complete description.
- The new encoding allows us to provide a more precise description to assist debugging.
Although the new encoding provides many benefits, you may need to make changes to your
existing NI-CAN application.
If you have already deployed executable applications to your customers, and you
are concerned that possible upgrades of NI-CAN in the field will break the error
handling in your application, refer to nican.h for information regarding the
StatusEx utility. This utility can be used to force the NI-CAN driver to return
the legacy (prior to 1.5) error codes. This special feature is not guaranteed to be
supported in future releases of NI-CAN, so we strongly recommend that when possible,
you upgrade your application code to use the new error scheme.
The following instructions detail the steps required to change NI-CAN error handling
in your application:
LabVIEW
-------
1. No change is required regarding your handling of error clusters.
The status, code, and source fields of the NI-CAN error cluster still
operate in the same manner as previous versions.
2. If you wish to display a dialog box whenever an error occurs, wire the
error output of the last NI-CAN Close VI into LabVIEW's Simple Error Handler.vi.
When an error occurs, the resulting dialog will describe the error, and recommend
possible solutions.
3. If you use the Simple Error Handler.vi, you may be able to remove error clusters
that you previously displayed on your front panel for NI-CAN debugging.
4. Check to see if your diagram uses the code field of the NI-CAN error cluster.
If you do comparisons or other operations in which you have entered constants
for the code, those constants must change. Refer to Table 2 below for assistance
in converting legacy status values into new status values.
5. If you use the NI-CAN Get Attribute VI to get the Object Status, you must
change any constants used for error/warning comparisons as in Step 4 above.
C/C++
-----
1. You are no longer required to include a large switch statement in a special
NI-CAN status handler such as CheckStat(). In previous versions of NI-CAN,
this switch statement was used to convert a status value into a descriptive
string. If you use such a switch statement in your code, delete the switch
statement, and replace it with the new ncStatusToString function. For
examples of this change, refer to the NI-CAN examples for C/C++.
2. If you do comparisons of NI-CAN status in your code, the constant names
must change. If you used constant names from NICAN.H for such comparisions,
refer to Table 1 below for assistance in converting legacy names into new
status names. If you used numeric constants for such comparisions, refer to
Table 2 below.
3. If you use the NI-CAN ncGetAttribute function to get the NC_ATTR_STATUS
attribute, you must change any constants used for error/warning comparisons
as in Step 2 above.
-----------------------------------------------
TABLE 1: CONVERT LEGACY C/C++ NAMES TO NEW NAME
-----------------------------------------------
The original error encoding of NI-CAN (prior to 1.5) used three different
bit fields. This use of bit fields was often confusing to interpret.
Each error code now consists of a single, simple numeric value (no bit fields).
The following constants were previously used to access bit fields. These
constants are no longer required. Expressions that use these constants
should be replaced with a single error constant from the table below.
NC_MK_SEVERITY
NC_MK_QUALIFIER
NC_MK_CODE
NC_STATSEV
NC_STATQUAL
NC_STATCODE
NC_SEV_SUCCESS
NC_SEV_WARNING
NC_SEV_ERROR
The following table is alphabetized according to the name of the legacy code field.
Legacy names New name
------------------------------------------------------------------------------------------------
NC_ERR_ALREADY_OPEN | NC_SEV_ERROR CanErrAlreadyOpen
NC_ERR_BAD_ATTR_VALUE | (0 to 0x7FFF0000) | NC_SEV_ERROR CanErrBadAttributeValue
NC_ERR_BAD_NAME | 0x00000000 | NC_SEV_ERROR CanErrBadNameSyntax
NC_ERR_BAD_NAME | 0x00010000 | NC_SEV_ERROR CanErrBadIntfName
NC_ERR_BAD_NAME | 0x00020000 | NC_SEV_ERROR CanErrBadCanObjName
NC_ERR_BAD_PARAM | 0x00000000 | NC_SEV_ERROR CanErrBadParam
NC_ERR_BAD_PARAM | 0x00010000 | NC_SEV_ERROR CanErrBadHandle
NC_ERR_BAD_PARAM | 0x01000000 | NC_SEV_ERROR CanErrBadHandle
NC_ERR_BAD_PARAM | 0x00020000 | NC_SEV_ERROR CanErrBadParam
NC_ERR_BAD_PARAM | 0x00030000 | NC_SEV_ERROR CanErrBadParam
NC_ERR_BAD_VALUE | (0 to 0x7FFF0000) | NC_SEV_ERROR CanErrBadAttributeValue
NC_ERR_CAN_BUS_OFF (same as NC_ERR_CAN_COMM) (see NC_ERR_CAN_COMM)
NC_ERR_CAN_COMM | 0x00000000 | NC_SEV_ERROR CanErrComm
NC_ERR_CAN_COMM | NC_QUAL_CAN_STUFF | NC_SEV_ERROR CanErrCommStuff
NC_ERR_CAN_COMM | NC_QUAL_CAN_FORM | NC_SEV_ERROR CanErrCommFormat
NC_ERR_CAN_COMM | NC_QUAL_CAN_ACK | NC_SEV_ERROR CanErrCommNoAck
NC_ERR_CAN_COMM | NC_QUAL_CAN_BIT1 | NC_SEV_ERROR CanErrCommTx1Rx0
NC_ERR_CAN_COMM | NC_QUAL_CAN_BIT0 | NC_SEV_ERROR CanErrCommTx0Rx1
NC_ERR_CAN_COMM | NC_QUAL_CAN_CRC | NC_SEV_ERROR CanErrCommBadCRC
NC_ERR_CAN_COMM | 0x00000000 | NC_SEV_WARNING CanWarnComm
NC_ERR_CAN_COMM | NC_QUAL_CAN_STUFF | NC_SEV_WARNING CanWarnCommStuff
NC_ERR_CAN_COMM | NC_QUAL_CAN_FORM | NC_SEV_WARNING CanWarnCommFormat
NC_ERR_CAN_COMM | NC_QUAL_CAN_ACK | NC_SEV_WARNING CanWarnCommNoAck
NC_ERR_CAN_COMM | NC_QUAL_CAN_BIT1 | NC_SEV_WARNING CanWarnCommTx1Rx0
NC_ERR_CAN_COMM | NC_QUAL_CAN_BIT0 | NC_SEV_WARNING CanWarnCommTx0Rx1
NC_ERR_CAN_COMM | NC_QUAL_CAN_CRC | NC_SEV_WARNING CanWarnCommBadCRC
NC_ERR_CAN_XCVR | NC_SEV_ERROR CanWarnLowSpeedXcvr
NC_ERR_CONFIG_ONLY | NC_SEV_ERROR CanErrConfigOnly
NC_ERR_DRIVER | (0x00000000 to 0x7FFF0000) | NC_SEV_ERROR CanErrDriver
NC_ERR_NOT_STOPPED | NC_SEV_ERROR CanErrNotStopped
NC_ERR_NOT_SUPPORTED | NC_SEV_ERROR CanErrNotSupported
NC_ERR_NOTIF_PENDING | NC_SEV_WARNING CanWarnNotificationPending
NC_ERR_OBJ_CLOSED | NC_SEV_ERROR CanErrBadHandle
NC_ERR_OLD_DATA | NC_SEV_WARNING CanWarnOldData
NC_ERR_OVERFLOW | NC_QUAL_OVFL_WRITE | NC_SEV_ERROR CanErrOverflowWrite
NC_ERR_OVERFLOW | NC_QUAL_OVFL_READ | NC_SEV_ERROR CanErrOverflowRead
NC_ERR_OVERFLOW | NC_QUAL_OVFL_CHIP | NC_SEV_ERROR CanErrOverflowChip
NC_ERR_OVERFLOW | NC_QUAL_OVFL_RX_Q | NC_SEV_ERROR CanErrOverflowRxQueue
NC_ERR_RSRC_LIMITS | NC_QUAL_RSRC_QUEUE_LEN | NC_SEV_ERROR CanErrRsrcLimitQueues
NC_ERR_RSRC_LIMITS | NC_QUAL_RSRC_RTSI | NC_SEV_ERROR CanErrRsrcLimitRtsi
NC_ERR_TIMEOUT | NC_QUAL_TIMO_FUNCTION | NC_SEV_ERROR CanErrFunctionTimeout
NC_ERR_TIMEOUT | NC_QUAL_TIMO_WATCHDOG | NC_SEV_ERROR CanErrWatchdogTimeout
NC_ERR_TIMEOUT | NC_QUAL_TIMO_SCHEDULE | NC_SEV_ERROR CanErrScheduleTimeout
NC_ERR_TIMEOUT | NC_QUAL_TIMO_PERIODIC_TX | NC_SEV_ERROR CanErrScheduleTimeout
NC_SUCCESS CanSuccess
------------------------------------------
TABLE 2: CONVERT LEGACY VALUE TO NEW VALUE
------------------------------------------
The following table is sorted according to the value of the legacy code field (low 16 bits).
Legacy value New name New value
----------------------------------------------------------------------------------
0 CanSuccess 0 (same)
0x80000001 CanErrFunctionTimeout 0xBFF62001
0x80010001 CanErrWatchdogTimeout 0xBFF62021
0x80050001 CanErrScheduleTimeout 0xBFF620A1
0x80000002 | (0 to 0x7FFF000) CanErrDriver 0xBFF62002
0x80000003 CanErrBadNameSyntax 0xBFF62003
0x80010003 CanErrBadIntfName 0xBFF62023
0x80020003 CanErrBadCanObjName 0xBFF62043
0x80000004 CanErrBadParam 0xBFF62004
0x80010004 CanErrBadHandle 0xBFF62024
0x81000004 CanErrBadHandle 0xBFF62024
0x80020004 CanErrBadParam 0xBFF62004
0x80030004 CanErrBadParam 0xBFF62004
0x80000005 | (0 to 0x7FFF000) CanErrBadAttributeValue 0xBFF62005
0x80000006 CanErrAlreadyOpen 0xBFF62006
0x80000007 CanErrNotStopped 0xBFF62007
0x80000008 CanErrOverflowWrite 0xBFF62008
0x80010008 CanErrOverflowRead 0xBFF62028
0x80020008 CanErrOverflowChip 0xBFF62048
0x80030008 CanErrOverflowRxQueue 0xBFF62068
0x40000009 CanWarnOldData 0x3FF62009
0x8000000A CanErrNotSupported 0xBFF6200A
0x4000000B CanWarnComm 0x3FF6200B
0x8000000B CanErrComm 0xBFF6200B
0x4001000B CanWarnCommStuff 0x3FF6202B
0x8001000B CanErrCommStuff 0xBFF6202B
0x4002000B CanWarnCommFormat 0x3FF6204B
0x8002000B CanErrCommFormat 0xBFF6204B
0x4003000B CanWarnCommNoAck 0x3FF6206B
0x8003000B CanErrCommNoAck 0xBFF6206B
0x4004000B CanWarnCommTx1Rx0 0x3FF6208B
0x8004000B CanErrCommTx1Rx0 0xBFF6208B
0x4005000B CanWarnCommTx0Rx1 0x3FF620AB
0x8005000B CanErrCommTx0Rx1 0xBFF620AB
0x4006000B CanWarnCommBadCRC 0x3FF620CB
0x8006000B CanErrCommBadCRC 0xBFF620CB
0x8000000C CanWarnLowSpeedXcvr 0x3FF6200C
0x4001000D CanWarnRsrcLimitQueues 0x3FF6202D
0x8001000D CanErrRsrcLimitQueues 0xBFF6202D
0x80000015 CanWarnNotificationPending 0x3FF62015
0x80000017 CanErrConfigOnly 0xBFF62017