ncGetDnetAttribute (Get DeviceNet Attribute)
Purpose
Get an attribute value from a DeviceNet device using an Explicit Messaging Object.
Format
LabVIEW
C
| NCTYPE_STATUS | ncGetDnetAttribute(
NCTYPE_OBJH ObjHandle,
NCTYPE_UINT16 ClassId,
NCTYPE_UINT16 InstanceId,
NCTYPE_UINT8 AttributeId,
NCTYPE_DURATION Timeout,
NCTYPE_UINT16 SizeofAttrData,
NCTYPE_ANY_P AttrData,
NCTYPE_UINT16_P ActualAttrDataLength
NCTYPE_UINT16_P DeviceError); |
Input
| ObjHandle | Object handle of an open Explicit Messaging Object |
| ClassId | Identifies the class which contains the attribute |
| InstanceId | Identifies the instance which contains the attribute |
| AttributeId | Identifies the attribute to get |
| Timeout | Maximum time to wait for response from device |
| SizeofAttrData | Size of AttrData buffer in bytes (C only) |
Output
| AttrData | Attribute value received from device |
| ActualAttrDataLength | Actual number of attribute data bytes returned |
| DeviceError | Error codes from device error response |
Function Description
ncGetDnetAttribute gets the value of an attribute from a DeviceNet device using an Explicit Messaging Object.
ncGetDnetAttribute executes the Get Attribute Single service on a remote DeviceNet device.
The format of the data returned in AttrData is defined by the DeviceNet data type in the attribute's description. When using LabVIEW, the ncConvertFromDnetRead function can convert this DeviceNet data type into an appropriate LabVIEW data type. When using C, AttrData can point to a variable of the appropriate data type as specified in NI-DNET Data Types.
Parameter Descriptions
ObjHandle
| Description | ObjHandle must contain an object handle returned from the ncOpenDnetExplMsg function. In LabVIEW, ObjHandle passes through the VI as an output so that it can be used for subsequent function calls for the object. |
| Values | The encoding of ObjHandle is internal to NI-DNET. |
ClassId
| Description | Identifies the class which contains the attribute. For descriptions and identifiers for each standard DeviceNet class, refer to the DeviceNet Specification (Volume 2, Chapter 6, The DeviceNet Object Library). Vendor-specific classes are documented by the device vendor. Although the DeviceNet Specification allows 16-bit class IDs, most class IDs are 8-bit. NI-DNET automatically uses the class ID size (16-bit or 8-bit) that is appropriate for your device. |
| Values | 00 to FFFF hex |
InstanceId
| Description | Identifies the instance which contains the attribute. Instance ID 0 is used to get an attribute from the class itself. Other instance IDs typically are numbered starting at 1. For example, the primary Identity Object in a device uses instance ID 1. Although the DeviceNet Specification allows 16-bit instance IDs, most instance IDs are 8-bit. NI-DNET automatically uses the instance ID size (16-bit or 8-bit) that is appropriate for your device. |
| Values | 00 to FFFF hex |
AttributeId
| Description | Identifies the attribute to get. Attribute IDs are listed in the class and instance descriptions in the DeviceNet Specification. The attribute's description also lists the DeviceNet data type for the attribute's value. |
| Values | 00 to FF hex |
Timeout
| Description | Maximum time to wait for response from device. To get the attribute from the device, an explicit message request for the Get Attribute Single service is sent to the device. After sending the service request, this function must wait for the explicit message response for Get Attribute Single. Timeout specifies the maximum number of milliseconds to wait for the response before giving up. If the timeout expires before the response is received, this function returns a status of BFF62001 hex (CanErrFunctionTimeout). For most DeviceNet devices, a Timeout of 100 ms is appropriate. The special timeout value of FFFFFFFF hex is used to wait indefinitely. |
| Values | 1 to 1000 or FFFFFFFF hex (infinite duration, constant NC_DURATION_INFINITE) |
SizeofAttrData
| Description | For C, this is the size of the buffer referenced by AttrData. It is used to verify that you have enough bytes available to store the attribute data. This size is normally obtained using the C language sizeof function and has no direct relation to the number of bytes received on the network. For LabVIEW, since the buffer for AttrData is allocated automatically by NI-DNET, this size is not needed. The number of bytes allocated for AttrData should be large enough to hold the maximum number of data bytes defined for the attribute. |
| Values | sizeof (buffer referenced by AttrData) |
AttrData
| Description | Attribute value received from device. The format of the data returned in AttrData is defined by the DeviceNet data type in the attribute's description. When using LabVIEW, the ncConvertFromDnetRead function can convert this DeviceNet data type into an appropriate LabVIEW data type. When using C, AttrData can point to a variable of the appropriate data type as specified in NI-DNET Data Types. The number of attribute data bytes returned is the smaller of SizeofAttrData and ActualAttrDataLength. |
| Values | Attribute data bytes |
ActualAttrDataLength
| Description | Actual number of attribute data bytes returned. This length is obtained from the actual Get Attribute Single response message. If this length is greater than SizeofAttrData, only SizeofAttrData bytes are returned in AttrData. If this length is less than or equal to SizeofAttrData, ActualAttrDataLength bytes are valid in AttrData. |
| Values | 0 to 240 |
DeviceError
| Description | Error codes from device's error response. If the remote device responds successfully to the Get Attribute Single service, the return status is 0 (DnetSuccess), and DeviceError returns 0. If the remote device returns an error response for the Get Attribute Single service, the return status is BFF62014 hex (DnetErrErrorResponse), and DeviceError returns the error codes from the response. The General Error Code from the device's error response is returned in the low byte of DeviceError. Common values for General Error Code include Attribute Not Supported (14 hex), Object Does Not Exist (16 hex), and Invalid Attribute Value (09 hex). The Additional Code from the device's error response is returned in the high byte of DeviceError. The Additional Code provides additional information that further describes the error. If no additional information is needed, the value FF hex is placed into this field. Values for the General Error Code and Additional Code are documented in the DeviceNet Specification. Common error code values are found in Appendix H, DeviceNet Error Codes, in the DeviceNet Specification. Object-specific error codes are listed in the object description. Vendor-specific error codes are listed in your device's documentation. |
| Values | Error codes from the device's error response. |
Examples
LabVIEW
Get the Serial Number attribute using an Explicit Messaging Object. The Serial Number is contained in the Identity Object (class ID 1, instance ID 1, attribute ID 6). The DeviceNet data type for Device Type is UDINT, for which the LabVIEW data type U32 should be used. The Timeout is 100 ms.
C
Get the Device Type attribute using the Explicit Messaging Object referenced by objh. The Device Type is contained in the Identity Object (class ID 1, instance ID 1, attribute ID 2). The DeviceNet data type for Device Type is UINT, for which the NI-DNET data type NCTYPE_UINT16 should be used.
NCTYPE_STATUS status;
NCTYPE_OBJH objh;
NCTYPE_UINT16 device_type;
NCTYPE_UINT16 actual_length;
NCTYPE_UINT16 device_error;
status = ncGetDnetAttribute(objh, 0x01, 0x01, 0x02, 100,
sizeof(device_type), &device_type,
&actual_length, &device_error);