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