ncGetAttribute

Purpose

Get the value of an object attribute.

Format

Input

ObjHandle

Object handle.

AttrId

Identifier of the attribute to get.

AttrSize

Size of the attribute in bytes.

Output

AttrPtr

Pointer used to return an attribute value.

Return Value

Status of the function call, returned as a signed 32-bit integer. Zero means the function executed successfully. Negative specifies an error, meaning the function did not perform expected behavior. Positive specifies a warning, meaning the function performed as expected, but a condition arose that might require attention. For more information, refer to ncStatusToString.

Description

ncGetAttribute gets the value of the attribute specified by AttrId from the object specified by ObjHandle. Within NI-CAN Objects, you use attributes to access configuration settings, status, and other information about the object, but not data.

AttrPtr points to the variable used to receive the attribute value. Its type is undefined so that you can use the appropriate host data type for AttrId. AttrSize indicates the size of the variable that AttrPtr points to. AttrSize is typically 4, and AttrPtr references a 32-bit unsigned integer.

You can get any of the AttrId mentioned in ncConfig using ncGetAttribute. The following list describes other AttrId you can get using ncGetAttribute:

NC_ATTR_ABS_TIME (Absolute Timestamp)

Returns the absolute timestamp value. The timestamp format is a 64-bit unsigned integer compatible with the Win32 FILETIME type (NCTYPE_ABS_TIME). This absolute time is kept in a Coordinated Universal Time (UTC) format. UTC time is loosely defined as the current date and time of day in Greenwich, England. Microsoft defines its UTC time (FILETIME) as a 64-bit counter of 100 ns intervals that have elapsed since 12:00 a.m., January 1, 1601.

Since the timestamp returned by ncRead (and this attribute) is compatible with Win32 FILETIME, you can pass it into the Win32 FileTimeToLocalFileTime function to convert it to the local time zone, then pass the resulting local time to the Win32FileTimeToSystemTime function to convert to the Win32 SYSTEMTIME type. SYSTEMTIME is a struct with fields for year, month, day, and so on. For more information on Win32 time types and functions, refer to the Microsoft Win32 documentation.

Since the absolute timestamp type is 64 bits (NCTYPE_ABS_TIME), you must use AttrSize of 8.

NC_ATTR_BAUD_RATE (Baud Rate)

Returns the value of the NC_ATTR_BAUD_RATE as configured with ncConfig or ncSetAttribute.

NC_ATTR_HW_FORMFACTOR (Form Factor)

NC_ATTR_BAUD_RATE (Baud Rate)

Returns the form factor of the card on which the Network Interface or CAN Object is located.

The returned Form Factor is an enumeration.

NC_HW_FORMFACTOR_PCI PCI

NC_HW_FORMFACTOR_PXI PXI

NC_HW_FORMFACTOR_PCMCIA PCMCIA

NC_HW_FORMFACTOR_AT AT

NC_HW_FORMFACTOR_USB USB

NC_ATTR_HW_SERIAL_NUM (Serial Number)

Returns the serial number of the card on which the Network Interface or CAN Object is located.

NC_ATTR_HW_SERIES (Series)

Returns the series of the card on which the Network Interface or CAN Object is located.

Series 1 hardware products use the Intel 82527 CAN controller.

Series 2 hardware products use the Philips SJA1000 CAN controller, plus improved RTSI synchronization features.

The 847x and 847x with Sync series CAN hardware products use the Philips SJA1000 CAN controller. The 847x and 847x with Sync series LIN hardware products use the AMTEL ATA6620 LIN controller.

The 847x with Sync series hardware products add synchronization features to the 847x hardware products.

The returned Series is an enumeration.

NC_HW_SERIES_1 Series 1

NC_HW_SERIES_2 Series 2

NC_HW_SERIES_847x 847x

NC_HW_SERIES_847x_with_Sync 847x with Sync

NC_ATTR_INTERFACE_NUM (Interface Number)

Returns the interface number of the port on which the Network Interface or CAN Object is located.

This is the same number that you used in the ObjName string of the previous ncConfig and ncOpenObject functions.

NC_ATTR_LIN_CHECKSUM_TYPE (LIN Checksum Type)

Returns the value of the NC_ATTR_LIN_CHECKSUM_TYPE attribute as configured with ncSetAttribute.

NC_ATTR_LIN_ENABLE_DLC_CHECK (LIN Enable DLC Check)

Returns the value of the NC_ATTR_LIN_ENABLE_DLC_CHECK as configured with ncSetAttribute.

NC_ATTR_LIN_LOG_WAKEUP (LIN Log Wakeup)

Returns the value of the NC_ATTR_LIN_LOG_WAKEUP attribute as configured with ncSetAttribute.

NC_ATTR_LIN_RESPONSE_TIMEOUT (LIN Response Timeout)

Returns the value of the NC_ATTR_LIN_RESPONSE_TIMEOUT attribute as configured with ncSetAttribute.

NC_ATTR_LIN_SLEEP (LIN Sleep)

Returns the value of the NC_ATTR_LIN_SLEEP attribute. This attribute may be updated by the user with ncSetAttribute or by the reception of a wakeup signal on the LIN bus.

NC_ATTR_LISTEN_ONLY (Listen Only)

Returns the NC_ATTR_LISTEN_ONLY attribute as configured with ncConfig.

NC_ATTR_LOG_BUS_ERRORS (Log Bus Errors?)

Returns the value of the NC_ATTR_LOG_BUS_ERRORS attribute as configured with ncSetAttribute.

NC_ATTR_LOG_COMM_ERRS (Log Comm Warnings)

Returns TRUE or FALSE depending on whether communication warnings (including transceiver faults) were logged to the Network Interface read queue. For more information, refer to this attribute in ncConfig.

NC_ATTR_LOG_START_TRIGGER (Log Start Trigger)

Returns the NC_ATTR_LOG_START_TRIGGER attribute as configured with ncSetAttribute.

NC_ATTR_MASTER_TIMEBASE_RATE (Master Timebase Rate)

Returns the present Master Timebase Rate in MHz, programmed into the CAN Series 1 or Series 2 hardware. For PCMCIA, this attribute will always return 10 MHz.

For the 847x with Sync series CAN and LIN hardware, this attribute returns the value that was automatically detected.

NC_ATTR_NOTIFY_MULT_LEN (ReadMult Size for Notification)

Returns the number of frames used as a threshold for the Read Multiple state. For more information, refer to this attribute in ncSetAttribute.

NC_ATTR_PROTOCOL_VERSION (Protocol Version)

For NI-CAN, this returns 02000200 hex, which corresponds to version 2.0B of the Bosch CAN specifications. For more information on the encoding of the version, refer to the NC_ATTR_SOFTWARE_VERSION (Software Version) attribute.

This attribute is available only from the Network Interface, not CAN Objects.

NC_ATTR_READ_PENDING (Read Entries Pending)

Returns the number of frames available in the read queue. Polling the available frames with this attribute can be used as an alternative to the ncWaitForState and ncCreateNotification functions.

NC_ATTR_RTSI_FRAME (RTSI Frame)

Returns the RTSI Frame attribute as configured with ncConfig.

NC_ATTR_RX_ERROR_COUNTER (Receive Error Counter)

Returns the Receive Error Counter from the Philips SJA1000 CAN controller. This Receive Error Counter is specified in the Bosch CAN standard as well as ISO CAN standards.

This attribute is unsupported for Series 1 CAN interfaces (returns error).

This attribute is available only from the Network Interface, not CAN Objects.

NC_ATTR_SELF_RECEPTION (Self Reception)

Returns the NC_ATTR_SELF_RECEPTION attribute as configured with ncConfig.

NC_ATTR_SERIES2_COMP (Series 2 Comparator)

Returns the NC_ATTR_SERIES2_COMP attribute as configured with ncConfig.

This attribute is available only from the Network Interface, not CAN Objects.

This attribute is not supported for Series 1 CAN, 847x LIN, or 847x with Sync LIN interfaces (returns error).

NC_ATTR_SERIES2_ERR_ARB_CAPTURE (Series 2 Error/Arb Capture)

Returns the current values of the Error Code Capture register and Arbitration Lost Capture register from the Philips SJA1000 CAN controller chip.

The Error Code Capture register provides information on bus errors that occur according to the CAN standard. A bus error increments either the Transmit Error Counter or the Receive Error Counter. When communication starts on the interface, the first bus error is captured into the Error Code Capture register, and retained until you get this attribute. After you get this attribute, the Error Code Capture register is again enabled to capture information for the next bus error.

The Arbitration Lost Capture register provides information on a loss of arbitration during transmits. Loss of arbitration is not considered an error. When communication starts on the interface, the first arbitration loss is captured into the Arbitration Lost Capture register, and retained until you get this attribute. After you get this attribute, the Arbitration Lost Capture register is again enabled to capture information for the next arbitration loss.

For each of the capture registers, a single-bit New flag indicates whether a new error has occurred since the last Get. If the New flag of a register is set, the associated fields contain new information. If the New flag of a register is clear, the associated fields are the same as the previous Get.

This attribute is commonly used with the NC_ATTR_SINGLE_SHOT_TX attribute. When a Write function is used to transmit the single frame, you can get this attribute to determine if the transmit was successful. If the single shot transmit was not successful, this attribute provides detailed information regarding the failure.

This attribute is not supported for Series 1 CAN, 847x LIN, or 847x with Sync LIN interfaces (returns error). Since the information and bit format is very specific to the Philips SJA1000 CAN controller on Series 2 hardware, National Instruments cannot guarantee compatibility for this attribute on future hardware series. When using this attribute in the application, it is best to get the NC_ATTR_HW_SERIES attribute to verify that the CAN hardware is Series 2, 847x, or 847x with Sync.

The following figure and the associated tables describe the format of bit fields in this attribute. The lowest byte (bits 0-7) corresponds to the Error Code Capture register. The next byte (bits 8-15) corresponds to the Arbitration Lost Capture register. Bit 16 (00010000 hex) is the New flag for the Error Code Capture fields. Bit 17 (00020000 hex) is the New flag for the Arbitration Lost Capture field. Bits marked as "X" are reserved, and should be ignored by the application.

The C/C++ header file nican.h provides the following macros to accept the attribute value as input and return a value as listed in the tables:

• NC_GET_ERRARB_SEG(value)

• NC_GET_ERRARB_DIR(value)

• NC_GET_ERRARB_ERRC(value)

• NC_GET_ERRARB_ALC(value)

• NC_GET_ERRARB_NEWECC(value)

• NC_GET_ERRARB_NEWALC(value)

Series 2 Error/Arb Capture Format

SEG Field of the Error Code Capture Register

DIR Field of the Error Code Capture Register

ERRC Field of the Error Code Capture Register

ALC Field Contains the Arbitration Lost Capture Register

NEWECC Field is the New Flag for the Error Code Capture Register

NEWALC Field is the New Flag for the Arbitration Lost Capture Register

NC_ATTR_SERIES2_FILTER_MODE (Series 2 Filter Mode)

Returns the NC_ATTR_SERIES2_FILTER_MODE attribute as configured with ncConfig.

This attribute is available only from the Network Interface, not CAN Objects.

This attribute is not supported for Series 1 CAN, 847x LIN, or 847x with Sync LIN interfaces (returns error).

NC_ATTR_SERIES2_MASK (Series 2 Mask)

Returns the NC_ATTR_SERIES2_MASK attribute as configured with ncConfig.

This attribute is available only from the Network Interface, not CAN Objects.

This attribute is not supported for Series 1 CAN, 847x LIN, or 847x with Sync LIN interfaces (returns error).

NC_ATTR_SINGLE_SHOT_TX (Single Shot Transmit)

Returns the NC_ATTR_SINGLE_SHOT_TX attribute as configured with ncConfig.

This attribute is not supported for Series 1 CAN, 847x LIN, or 847x with Sync LIN interfaces (returns error).

NC_ATTR_SOFTWARE_VERSION (Software Version)

Version of the NI-CAN software, with major, minor, update, and beta build numbers encoded in the U32 from high to low bytes. For example, 2.0.1 would be 02000100 hex, and 2.1 beta5 would be 02010005 hex.

This attribute is provided for backward compatibility. ncGetHardwareInfo provides more complete version information.

NC_ATTR_STATE (Object State)

Returns the current state bit mask of the object. Polling with ncGetAttr provides an alternative method of state detection than ncWaitForState or ncCreateNotification. For more information on the states returned from this attribute, refer to the DesiredState input of ncWaitForState.

NC_ATTR_TERMINATION (Termination)

Returns the value of the Termination attribute as configured with ncSetAttribute.

NC_ATTR_TIMELINE_RECOVERY (Timeline Recovery)

Returns the Timeline Recovery attribute for the CAN Network Interface Object.

NC_ATTR_TIMESTAMP_FORMAT (Timestamp Format)

Returns the present Timestamp Format programmed into the CAN or LIN hardware. This property applies to the entire card.

NC_ATTR_TRANSCEIVER_EXTERNAL_IN (Transceiver External Inputs)

Returns the transceiver external inputs for the Network Interface.

This attribute is available only for the Network Interface, not CAN Objects. Nevertheless, the attribute applies to communication by CAN Objects as well as the associated Network Interface.

Series 2 XS cards enable connection of an external transceiver. For an external transceiver, this attribute allows you to determine the input voltage on the STATUS pin of the CAN port.

For many models of CAN transceiver, an NERR pin is provided for detection of faults and other status. For such transceivers, you can wire the NERR pin to the STATUS pin of the CAN port.

This attribute is supported for Series 2 XS cards only (returns error for non-XS).

This attribute uses a bit mask. When using the attribute, use bitwise AND operations to check for values, not equality checks (equal, greater than, and so on).

NC_TRANSCEIVER_IN_STATUS (00000001 hex, STATUS pin)

This bit is set when 5 V exists on the STATUS pin.

This bit is clear when 0 V exists on the STATUS pin.

NC_ATTR_TRANSCEIVER_EXTERNAL_OUT (Transceiver External Outputs)

Returns the transceiver external outputs for the Network Interface.

This attribute is available only for the Network Interface, not CAN Objects. Nevertheless, the attribute applies to communication by CAN Objects as well as the associated Network Interface.

Series 2 XS cards enable connection of an external transceiver. For an external transceiver, this attribute allows you to determine the output voltage on the MODE0 and MODE1 pins of the CAN port, and it allows you to determine if the CAN controller chip is sleeping.

For more information on the format of the value returned in this attribute, refer to the description of NC_ATTR_TRANSCEIVER_EXTERNAL_OUT in ncSetAttribute.

This attribute is supported for Series 2 XS cards only (returns error for non-XS).

NC_ATTR_TRANSCEIVER_MODE (Transceiver Mode)

Returns the transceiver mode for the Network Interface.

This attribute is available only for the Network Interface, not CAN Objects. Nevertheless, the attribute applies to communication by CAN Objects as well as the associated Network Interface.

This attribute is not supported for Series 1 CAN, 847x LIN, or 847x with Sync LIN interfaces (returns error).

For Series 2 cards for the PCMCIA form factor, this property requires a corresponding Series 2 cable (dongle). For information on how to identify the series of the PCMCIA cable, refer to the Series 2 Vs. Series 1

The transceiver mode changes when you set the mode within the application, or when a remote wakeup transitions the interface from Sleep to Normal mode. For more information, refer to ncSetAttribute.

This property uses the following values:

NC_TRANSCEIVER_MODE_NORMAL (Normal)

Transceiver is awake in normal communication mode.

NC_TRANSCEIVER_MODE_SLEEP (Sleep)

Transceiver and the CAN controller chip are both in sleep mode.

NC_TRANSCEIVER_MODE_SW_WAKEUP (Single Wire Wakeup)

Single Wire transceiver is in Wakeup Transmission mode.

NC_TRANSCEIVER_MODE_SW_HIGHSPEED (Single Wire High-Speed)

Single Wire transceiver is in High-Speed Transmission mode.

NC_ATTR_TRANSCEIVER_TYPE (Transceiver Type)

Returns the type of transceiver for the Network Interface. For hardware other than Series 2 XS cards, the transceiver type is fixed. For Series 2 XS cards, the transceiver type reflects the most recent value specified by MAX or ncSetAttribute.

This attribute is available only for the Network Interface, not CAN Objects. Nevertheless, the attribute applies to communication by CAN Objects as well as the associated Network Interface.

This attribute is not supported on the PCMCIA form factor.

This attribute uses the following values:

NC_TRANSCEIVER_TYPE_DISC (Disconnect)

Transceiver type is Disconnect. This transceiver type is available on Series 2 XS cards only. For more information, refer to ncSetAttribute.

NC_TRANSCEIVER_TYPE_EXT (External)

Transceiver type is External. This transceiver type is available on Series 2 XS cards only. For more information, refer to ncSetAttribute.

NC_TRANSCEIVER_TYPE_HS (High-Speed)

Transceiver type is High-Speed (HS).

NC_TRANSCEIVER_TYPE_LIN (LIN)

Transceiver type is LIN

NC_TRANSCEIVER_TYPE_LS (Low-Speed/Fault-Tolerant)

Transceiver type is Low-Speed/Fault-Tolerant (LS).

NC_TRANSCEIVER_TYPE_SW (Single Wire)

Transceiver type is Single Wire (SW).

NC_ATTR_TRANSMIT_MODE (Transmit Mode)

Returns the Transmit Mode for which the CAN Network Interface Object is presently configured.

The returned Transmit Mode is a Boolean value.

0 Immediate Transmit

1 Timestamped Transmit

NC_ATTR_TX_ERROR_COUNTER (Transmit Error Counter)

Returns the Transmit Error Counter from the Philips SJA1000 CAN controller. This Transmit Error Counter is specified in the Bosch CAN standard as well as ISO CAN standards.

This attribute is unsupported for Series 1 hardware (returns error).

This attribute is available only from the Network Interface, not CAN Objects.

NC_ATTR_VIRTUAL_BUS_TIMING (Virtual Bus Timing)

Returns a Boolean value of TRUE or FALSE to indicate whether Virtual Bus Timing has been set or not for the specified virtual interface. This attribute is applicable to all CAN objects opened on the virtual interface.

NC_ATTR_WRITE_ENTRIES_FREE (Write Entries Free)

Returns the number of frames that can be accepted for a CAN or LIN Network Interface Object or CAN Object to write without causing overflow error.

NC_ATTR_WRITE_PENDING (Write Entries Pending)

Returns the number of frames pending transmission in the write queue. If the intent is to verify that all pending frames have been transmitted successfully, waiting for the Write Success state is preferable to this attribute.

The Write Entries Pending attribute for 847x series CAN and LIN interfaces does not return the number of frames pending transmission in the write queue because the number does not take into account the frames in transit over the USB or waiting to be transmitted to the interface over the USB.

Description

ncGetAttribute gets the value of the attribute specified by AttrId from the object specified by ObjHandle. Within NI-CAN Objects, you use attributes to access configuration settings, status, and other information about the object, but not data.