ncSetDnetAttribute (Set DeviceNet Attribute)
Purpose
Set an attribute value for a DeviceNet device using an Explicit Messaging Object.
Format
LabVIEW
C
| NCTYPE_STATUS | ncSetDnetAttribute(
NCTYPE_OBJH ObjHandle,
NCTYPE_UINT16 ClassId,
NCTYPE_UINT16 InstanceId,
NCTYPE_UINT8 AttributeId,
NCTYPE_DURATION Timeout,
NCTYPE_UINT16 AttrDataLength,
NCTYPE_ANY_P AttrData
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 set |
| Timeout | Maximum time to wait for response from device |
| AttrDataLength | Number of attribute data bytes to set |
| AttrData | Attribute value to set in device |
Output
| DeviceError | Error codes from device's error response |
Function Description
ncSetDnetAttribute sets the value of an attribute for a DeviceNet device using an Explicit Messaging Object.
ncSetDnetAttribute executes the Set Attribute Single service on a remote DeviceNet device.
The DeviceNet data type in the attribute's description defines the format of the data provided in AttrData. When using LabVIEW, the ncConvertForDnetWrite function can convert this DeviceNet data type from 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. You can find descriptions and identifiers for each standard DeviceNet class in the DeviceNet Specification (Volume 2, Chapter 6, The DeviceNet Object Library). The device vendor documents vendor-specific classes. Although the DeviceNet Specification allows 16-bit class IDs, most class IDs are 8-bit. NI-DNET automatically used 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 sets an attribute in 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 set. The class and instance descriptions list attribute IDs. 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 set the attribute in the device, an explicit message request for the Set Attribute Single service is sent to the device. After sending the service request, this function must wait for the explicit message response for Set 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) |
AttrDataLength
| Description | Number of attribute data bytes to set. This length also specifies the number of bytes provided in AttrData. |
| Values | 0 to 239 |
AttrData
| Description | Attribute value to set in device. The DeviceNet data type in the attribute's description defines the format of the data provided in AttrData. When using LabVIEW, the ncConvertForDnetWrite function can convert this DeviceNet data type from 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 AttrDataLength parameter specifies the number of attribute data bytes to set. |
| Values | Attribute value to set in device. |
DeviceError
| Description | Error codes from device's error response. If the remote device responds successfully to the Set Attribute Single service, the return status is 0 (DnetSuccess), and DeviceError returns 0. If the remote device returns an error response for the Set 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. The DeviceNet Specification documents values for the General Error Code and Additional Code. You can find common error code values in Appendix H, DeviceNet Error Codes, in the DeviceNet Specification. The object description lists object-specific error codes. Your device's documentation lists vendor-specific error codes. |
| Values | Error codes from the device's error response. |
Examples
LabVIEW
Set the Input Range attribute of an Analog Input Object. The Input Range is contained in instance 3 of an Analog Input Object (class ID 0A hex, instance ID 3, attribute ID 7). The DeviceNet data type for Input Range is USINT, for which the LabVIEW data type U8 should be used. The Timeout is 40 ms.
C
Set the MAC ID attribute of a remote DeviceNet device using the Explicit Messaging Object referenced by objh. The MAC ID is contained in the DeviceNet Object (class ID 3, instance ID 1, attribute ID 1). The DeviceNet data type for Device Type is USINT, for which the NI-DNET data type NCTYPE_UINT8 should be used.
NCTYPE_STATUS status;
NCTYPE_OBJH objh;
NCTYPE_UINT8 mac_id;
NCTYPE_UINT16 device_error;
mac_id = 12;
status = ncSetDnetAttribute(objh, 0x03, 0x01, 0x01, 100, 1, &mac_id, &device_error);