ncReadDnetExplMsg (Read DeviceNet Explicit Message)
Purpose
Read an explicit message response from an Explicit Messaging Object.
Format
LabVIEW
C
| NCTYPE_STATUS | ncReadDnetExplMsg( NCTYPE_OBJH ObjHandle,
NCTYPE_UINT8_P ServiceCode,
NCTYPE_UINT16 SizeofServData,
NCTYPE_ANY_P ServData,
NCTYPE_UINT16_P ActualServ
DataLength); |
Input
| ObjHandle | Object handle of an open Explicit Messaging Object |
| SizeofServData | Size of ServData buffer in bytes (C only) |
Output
| ServiceCode | DeviceNet service code from response |
| ServData | Service data from response |
| ActualServDataLength | Actual number of service data bytes in response |
Function Description
ncReadDnetExplMsg reads an explicit message response from an Explicit Messaging Object.
The two most commonly used DeviceNet explicit messages are the Get Attribute Single service and the Set Attribute Single service. The easiest way to execute the Get Attribute Single service on a remote device is to use the NI-DNET ncGetDnetAttribute function. The easiest way to execute the Set Attribute Single service on a remote device is to use the NI-DNET ncSetDnetAttribute function.
To execute services other than Get Attribute Single and Set Attribute Single, use the following sequence of function calls: ncWriteDnetExplMsg, ncWaitForState, ncReadDnetExplMsg. The ncWriteDnetExplMsg function sends an explicit message request to a remote DeviceNet device. The ncWaitForState function waits for the explicit message response, and the ncReadDnetExplMsg function reads that response.
Some of the DeviceNet services which use ncReadDnetExplMsg are Reset, Save, Restore, Get Attributes All, and Set Attributes All. Although the DeviceNet Specification defines the overall format of these services, in most cases their meaning and service data are object specific or vendor specific. Unless your device requires such services and documents them in detail, you probably do not need them for your application. For more information, refer to the NI-DNET User Manual.
Parameter Descriptions
ObjHandle
| Description | ObjHandle must contain an object handle returned from ncOpenDnetExplMsg. 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. |
ServiceCode
| Description | Identifies the service response as either success or error. If the response is success, this value is the same as the ServiceCode of the request (ncWriteDnetExplMsg), and the ServData bytes are formatted as defined by the service. If the response is error, this value is 14 hex, ServData[0] contains a General Error Code, and ServData[1] contains an Additional Code. Either the DeviceNet Specification or the object itself define the error codes. Although the DeviceNet Specification requires the high bit of the service code (hex 80) to be set in all explicit message responses, NI-DNET clears this response indicator so that you can compare the actual service code to the value used with ncWriteDnetExplMsg. |
| Values | Same as the ServiceCode of ncWriteDnetExplMsg (success response) or 14 hex (error response) |
SizeofServData
| Description | For C, this is the size of the buffer referenced by ServData. Use it to verify that you have enough bytes available to store the service data from the response. 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 ServData is allocated automatically by NI-DNET, this size is not needed. The number of bytes allocated for ServData should be large enough to hold the maximum number of service data response bytes defined for the service. |
| Values | sizeof (buffer referenced by ServData) |
ServData
| Description | Service data bytes from response. If the response is success, these bytes are formatted as defined by the service. If the response is error, the first byte (ServData[0]) contains a General Error Code, and the second byte (ServData[1]) contains an Additional Code. Either the DeviceNet Specification or the object itself define the error codes. The number of service data bytes returned is the smaller of SizeofServData and ActualServDataLength. |
| Values | Service data bytes from response |
ActualServDataLength
| Description | Actual number of service data bytes in response. This length is obtained from the actual response message. If this length is greater than SizeofServData, only SizeofServData bytes are returned in ServData. If this length is less than or equal to SizeofServData, ActualServDataLength bytes are valid in ServData. |
| Values | 0 to 240 |
Examples
LabVIEW
Read an explicit message response from an Explicit Messaging Object.
C
Read an explicit message response from the Explicit Messaging Object referenced by objh.
NCTYPE_STATUS status;
NCTYPE_OBJH objh;
NCTYPE_UINT8 servcode;
NCTYPE_UINT8 servdata[20];
NCTYPE_UINT16 actual_len;
status = ncReadDnetExplMsg(objh, &servcode, 20, servdata, &actual_len);