nctGetProperty
Purpose
Gets a property for the task, or a single channel within the task.
Format
| nctTypeStatus | nctGetProperty(
|
Inputs
TaskRef
Task reference from the previous NI-CAN function. The task reference is originally returned from nctInitStart, nctInitialize, or nctCreateMessage.
ChannelName
Specifies an individual channel within the task. If you pass empty-string to ChannelName, this means the property applies to the entire task, not a specific channel.
Properties that begin with the word Channel or Message do not apply to the entire task, but an individual channel or message within the task. For these channel-specific properties, you must pass the name of a channel from channel list into the ChannelName input.
For properties that do not begin with the word Channel or Message, you must pass empty-string ("") into ChannelName. You must not pass NULL into ChannelName.
PropertyId
Selects the property to get.
For a description of each property, including its data type and PropertyId, refer to the Properties section.
SizeofValue
Number of bytes allocated for the Value output. This size normally depends on the data type listed in the description of the property.
Outputs
Value
Returns the property value. PropertyId determines the data type of the returned value.
Return Value
The return value indicates the status of the function call as a signed 32-bit integer. Zero means the function executed successfully. A negative value specifies an error, which means the function did not perform the expected behavior. A positive value specifies a warning, which means the function performed as expected, but a condition arose that may require attention.
Use the ncStatusToString function of the Frame API to obtain a descriptive string for the return value. The ncStatusToString and ncGetHardwareInfo functions are the only Frame API functions that can be called within a Channel API application.
Properties
u32 nctPropBehavAfterFinalOut
Returns the nctPropBehavAfterFinalOut property, which is used with some output task configurations. For more information, refer to the nctPropBehavAfterFinalOut property in nctSetProperty.
u32 nctPropChanByteOrder
Returns the byte order of the channel in the message. Values are nctOrderIntel (little-endian), and nctOrderMotorola (big-endian).
The value of this property is originally set within MAX or the CAN database and cannot be changed using nctSetProperty.
u32 nctPropChanDataType
Returns the data type of the channel in the message. Values are nctDataSigned, nctDataUnsigned, and nctDataFloat.
The value of this property is originally set within MAX or the CAN database and cannot be changed using nctSetProperty.
f64 nctPropChanDefaultValue
Returns the default value of the channel in scaled floating-point units.
For information on how nctPropChanDefaultValue is used, refer to the nctRead and nctWrite functions.
The value of this property is originally set within MAX. If the channel is initialized directly from a CAN database, the value is 0.0 by default, but it can be changed using nctSetProperty.
u32 nctPropChanIsModeDependent
Returns if a channel is mode dependent (1) or not (0).
f64 nctPropChanMaxValue
Returns the maximum value of the channel in scaled floating-point units.
The nctRead and nctWrite functions do not coerce samples when converting to/from CAN messages. You can use this value with the user-interface functions of the development environment to set the range of front-panel controls and indicators.
The value of this property is originally set within MAX or the CAN database and cannot be changed using nctSetProperty.
f64 nctPropChanMinValue
Returns the minimum value of the channel in scaled floating-point units.
The nctRead and nctWrite functions do not coerce samples when converting to/from CAN messages. You can use this value with the user-interface functions of the development environment to set the range of front-panel controls and indicators.
The value of this property is originally set within MAX or the CAN database and cannot be changed using nctSetProperty.
u32 nctPropChanModeValue
Returns the value of the mode channel associated to this channel. This property applies only to mode dependent channels. For more information, refer to Mode Dependent Channels.
u32 nctPropChanNumBits
Returns the number of bits in the channel. The range is 0 to 64.
The value of this property is originally set within MAX or the CAN database and cannot be changed using nctSetProperty.
f64 nctPropChanScalFactor
Returns the scaling factor used to convert raw bits of the message to/from scaled floating-point units. The scaling factor is the A in the linear scaling formula AX+B, where X is the raw data, and B is the scaling offset.
CAN messages use the raw data, and the nctRead and nctWrite functions provide access to samples in floating-point units.
The value of this property is originally set within MAX or the CAN database and cannot be changed using nctSetProperty.
f64 nctPropChanScalOffset
Returns the scaling offset used to convert raw bits of the message to/from scaled floating-point units. The scaling offset is the B in the linear scaling formula AX+B, where X is the raw data, and A is the scaling factor.
CAN messages use the raw data, and the nctRead and nctWrite functions provide access to samples in floating-point units.
The value of this property is originally set within MAX or the CAN database and cannot be changed using nctSetProperty.
u32 nctPropChanStartBit
Returns the starting bit position in the message. The range is 0 (lowest bit in first byte), to 63 (highest bit in last byte).
The value of this property is originally set within MAX or the CAN database and cannot be changed using nctSetProperty.
str nctPropChanUnitString
Returns the unit string of the channel. The string is no more than 80 characters in length.
You can use this value to display units (such as volts or RPM) along with the samples of the channel.
The value of this property is originally set within MAX or the CAN database and cannot be changed using nctSetProperty.
u32 nctPropHwFormFactor
Returns the hardware form factor for the NI-CAN hardware that contains Interface. Values are nctHwFormFactorPCI, nctHwFormFactorPXI, nctHwFormFactorPCMCIA, and nctHwFormFactorAT.
u32 nctPropHwMasterTimebaseRate
Returns the present Hardware Master Timebase Rate in MHz, programmed into the CAN hardware. For PCMCIA, this property will always return 10 MHz.
u32 nctPropHwSerialNum
Returns the hardware serial number for the NI-CAN hardware that contains Interface.
u32 nctPropHwSeries
Returns the hardware series for the NI CAN hardware that contains Interface. Values are nctHwSeries1 and nctHwSeries2.
Newer hardware series are often capable of more features, so the application may need to determine which is installed.
Returns the present Timestamp Format programmed into the CAN hardware. This property applies to the entire card.
u32 nctPropInterface
Returns the Interface initialized for the task, such as with the nctInitStart function.
u32 nctPropIntfBaudRate
Returns the baud rate in use by the Interface.
Basic baud rates such as 125000 and 500000 are specified as the numeric rate.
Advanced baud rates are specified as 8000XXYY hex, where YY is the value of Bit Timing Register 0 (BTR0), and XX is the value of Bit Timing Register 1 (BTR1). For more information, refer to the Port Properties dialog in MAX.
The value of this property is originally set within MAX, but it can be changed using nctSetProperty.
u32 nctPropIntfListenOnly
Returns a Boolean value that indicates whether the listen only feature of the Philips SJA1000 CAN controller is enabled (true) or disabled (false). For more information, refer to the nctPropIntfListenOnly property in nctSetProperty.
Since the listen only feature requires the Philips SJA1000 CAN controller, this property is supported on Series 2 NI CAN hardware only.
u32 nctPropIntfRxErrorCounter
Returns the Receive Error Counter as described in the CAN specification.
Since the error count requires the Philips SJA1000 CAN controller, this property is supported on Series 2 NI CAN hardware only. If you are using Series 1 NI CAN hardware, this property returns an error.
u32 nctPropIntfSelfReception
Returns the nctPropIntfSelfReception property as configured with nctSetProperty. This property is supported on Series 2 NI CAN hardware only (returns error for Series 1).
u32 nctPropIntfSeries2ErrArbCapture
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 property. After you get this property, 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 property. After you get this property, 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 property is commonly used with the nctPropIntfSingleShotTx property. When nctWrite is used to transmit the single frame, you can get this property to determine if the transmit was successful. If the single shot transmit was not successful, this property provides detailed information for the failure.
This property is supported for Series 2 hardware only (Series 1 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 property on future hardware series. When using this property in the application, it is best to get the nctPropHwSeries property to verify that the CAN hardware is Series 2.
For information regarding the format of the bits in this property, refer to the NC_ATTR_SERIES2_ERR_ARB_CAPTURE attribute in the ncGetAttribute function of the Frame API.
u32 nctPropIntfSeries2Comp
Returns the value of the nctPropIntfSeries2Comp property (refer to nctSetProperty).
u32 nctPropIntfSeries2FilterMode
Returns the value of the nctPropIntfSeries2FilterMode property (refer to nctSetProperty).
u32 nctPropIntfSeries2Mask
Returns the value of the nctPropIntfSeries2Mask property (refer to nctSetProperty).
Returns the value of the nctPropIntfSingleShotTx property (refer to nctSetProperty).
u32 nctPropIntfTransceiverExternalIn
Returns the transceiver external inputs for the interface that was initialized for the task.
Series 2 XS cards enable connection of an external transceiver. For an external transceiver, this property 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 property is supported for Series 2 XS cards only.
This property uses a bit mask. When using the property, use bitwise AND operations to check for values, not equality checks (equal, greater than, and so on).
nctTransceiverInStatus (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.
u32 nctPropIntfTransceiverExternalOut
Returns the transceiver external outputs for the interface that was initialized for the task.
Series 2 XS cards enable connection of an external transceiver. For an external transceiver, this property 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 property, refer to the description of nctPropIntfTransceiverExternalOut in nctSetProperty.
This property is supported for Series 2 XS cards only.
u32 nctPropIntfTransceiverMode
Returns the transceiver mode for the interface that was initialized for the task. 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 nctSetProperty.
This property is supported for Series 2 cards only.
This property uses the following values:
nctTransceiverModeNormal
Transceiver is awake in Normal communication mode.
nctTransceiverModeSleep
Transceiver and the CAN controller chip are both in Sleep mode.
nctTransceiverModeSWWakeup
Single Wire transceiver is in Wakeup Transmission mode.
nctTransceiverModeSWHighSpeed
Single Wire transceiver is in High-Speed Transmission mode.
u32 nctPropIntfTransceiverType
Returns the type of transceiver for the interface that was initialized for the task. 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 nctSetProperty.
This property is not supported on the PCMCIA form factor.
This property uses the following values:
nctTransceiverTypeHS
Transceiver type is High-Speed (HS).
nctTransceiverTypeLS
Transceiver type is Low-Speed/Fault-Tolerant (LS).
nctTransceiverTypeSW
Transceiver type is Single Wire (SW).
nctTransceiverTypeExternal
Transceiver type is External. This transceiver type is available on Series 2 XS cards only. For more information, refer to nctSetProperty.
nctTransceiverTypeDisconnect
Transceiver type is Disconnect. This transceiver type is available on Series 2 XS cards only. For more information, refer to nctSetProperty.
u32 nctPropIntfTxErrorCounter
Returns the Transmit Error Counter as described in the CAN specification.
Since the error count requires the Philips SJA1000 CAN controller, this property is supported on Series 2 NI CAN hardware only. If you are using Series 1 NI CAN hardware, this property returns an error.
u32 nctPropIntfVirtualBusTiming
Returns a Boolean value of True or False to indicate whether Virtual Bus Timing has been set or not for the specified virtual task. This property is applicable to all tasks opened on the virtual interface.
If this property is selected on real hardware, an error will be returned.
u32 nctPropMode
Returns the Mode initialized for the task, such as with the nctInitStart function.
u32 nctPropMsgArbitrationId
Returns the arbitration ID of the channel message.
To determine whether the ID is standard (11-bit) or extended (29-bit), get the nctPropMsgIsExtended property.
The value of this property is originally set within MAX or the CAN database and cannot be changed using nctSetProperty.
u32 nctPropMsgByteLength
Returns the number of data bytes in the channel message. The range is 0 to 8.
The value of this property is originally set within MAX or the CAN database and cannot be changed using nctSetProperty.
u32 nctPropMsgIsExtended
Returns a Boolean value that indicates whether the arbitrationID of the channel message is standard 11-bit format (0) or extended 29-bit format (1).
The value of this property is originally set within MAX or the CAN database and cannot be changed using nctSetProperty.
str nctPropMsgName
Returns the name of the channel message. The string is no more than 80 characters in length.
The value of this property is originally set within MAX or the CAN database and cannot be changed using nctSetProperty.
u32 nctPropMsgDistribution
Returns the nctPropMsgDistribution which is used to determine if the CAN frames associated to a group of mode dependent channels are sent even spaced or in burst mode. This property applies only for mode dependent channels that are transmitted periodically. For more information, refer to Mode Dependent Channels.
f64 nctPropNoValue
Returns the value that is returned on timestamped read for mode dependent channels that have not been received with the most recent CAN frame associated with the CAN message. This Property applies only to mode dependent channels that are read with the timestamped read operation. For more information, refer to Mode Dependent Channels.
u32 nctPropNumChannels
Returns the number of channels initialized in channel list. This is the number of array entries required when using nctRead or nctWrite.
f64 nctPropSampleRate
Returns the SampleRate initialized for the task, such as with the nctInitStart function.
u32 nctPropSamplesPending
Returns the number of samples available to be read using nctRead. If you set the NumberOfSamplesToRead input of nctRead to this value, nctRead returns immediately without waiting.
This property applies only to tasks initialized with Mode of NctModeInput, and SampleRate greater than zero. For all other configurations, it returns an error.
f64 nctPropTimeout
Returns the nctPropTimeout property, which is used with some task configurations. For more information, refer to the nctPropTimeout property in nctSetProperty.
u32 nctPropVersionBuild
Returns the build number of the NI-CAN software. This number applies to nctPhaseDevelopment, nctPhaseAlpha, and nctPhaseBeta phase only, and should be ignored for nctPhaseRelease phase.
str nctPropVersionComment
Returns a comment string for the NI-CAN software. If you received a custom release of NI-CAN from National Instruments, this comment often describes special features of the release.
u32 nctPropVersionMajor
Returns the major version of the NI-CAN software, such as the 2 in version 2.1.5.
u32 nctPropVersionMinor
Returns the minor version of the NI-CAN software, such as the 1 in version 2.1.5.
u32 nctPropVersionPhase
Returns the phase of the NI-CAN software. Values are nctPhaseDevelopment, nctPhaseAlpha, nctPhaseBeta, and nctPhaseRelease. Versions of NI-CAN in hardware kits or on ni.com will always be nctPhaseRelease.
u32 nctPropVersionUpdate
Returns the update version of the NI-CAN software, such as the 5 in version 2.1.5.