dpDirectRead()
The function reads values from datapoints directly from the PLC
Synopsis
int dpDirectRead(uint timeout, string dp1, <type1> &var1 [, string dp2, <type2> &var2, ...]);Parameters
| Parameter | Meaning |
|---|---|
| timeout | The optional timeout parameter is specified in milliseconds. The
default is 10,000 ms (10 s).
The default timeout is defined by the config entry IOTransitionTimeout, whose default value is 10 s. If IOTransitionTimeout is set to 0, or the timeout parameter is explicitly set to 0, a minimum timeout of approximately 1 s is applied. Other parameters also determine how long the driver waits for a request to complete. In the case of the OPC UA driver, there is a config entry for the timeout for OPC UA service calls: uaCallTimeout, whose default value is 10,000 ms (10 s). If the function timeout is higher than the timeout for OPC UA service calls, the OPC UA service-call timeout takes precedence and the request expires at the protocol level. Setting the function timeout to 0 results in a minimal timeout of approximately 1 s. If the timeout is reached (for example, no response from the PLC), an error is returned—see the section errors below. |
| dp1 | Datapoint configs (attributes) to be read. |
| var1 | The queried datapoint values are written to the variables &var1, &var2 etc. |
Return Value
The dpDirectRead() returns the error code (-1) in case of an error.
The success code is only returned if for dpDirectRead the value has been
successfully read directly from the hardware.
There is a difference to the other dp*() functions that return 0 if the request was successfully sent to the Event manager. Any errors that occur at a later point in time are only reported via getLastError().
Errors
Errors of the related (CTRL) manager or errors issued by other mangers (EVENT) can be
retrieved with getLastError()
(e.g.: error is issued if datapoints or configs do not exists or if the address is
not existing in the PLC). All potential errors that can be caught are defined in the
message catalog directRead.cat
You can iterate over the dyn_errClass and use the available
functions to retrieve further details about the error:
getErrorCode(): Returns the error code. This can be interpreted usingdirectRead.cat.getErrorDpName(): Indicates which DPE (datapoint element) caused the error.getErrorManId(): Indicates which manager set the error (e.g., DRV, EVENT, etc.).getErrorText(): Returns the error text. Additional information may be included.getErrorUserData: If it is a protocol-specific error code, it is set here by the driver.
Example: getErrorCode() returns 0004 (Direct write
to $DP failed: The read request returned the following error:
12345).
In getErrorUserData(), the exact protocol error code is then set, so
the error text does not need to be parsed, e.g.: 12345.
Details
dpDirectRead() function reads values directly from datapoints in
the PLC and assigns them to variables such as var1,
var2, etc. Simply use the address config, which
defines the connection to the PLC. You can read any number of pairs consisting of a
datapoint attribute and its value. The value returned by the function indicates that
a successful read request updates the value in the process image and that the
returned value has the status bit _from_SI set.
_original.._value
and _original.._userBits/status64 configs can be read.
Attempting to read any other configs will fail and return an error code.