dpDirectWrite()
The function writes datapoint values directly to the PLC
Synopsis
int dpDirectWrite(uint timeout, string dp1, <type1> var1 [, string dp2, <type2> var2, ...]);int dpDirectWrite(dyn_string dpnames, dyn_anytype values);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 /dpNames | Datapoints that are written. |
| var1 | The datapoint values that are written to the variables &var1, &var2 etc and sent directly to the PLC. |
Return Value
The dpDirectWrite() returns the error code (-1) in case of an error.
The success code is only returned if for dpDirectWrite the value has been written to
the hardware and a success confirmation has been received.
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 directWrite.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 usingdirectWrite.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 write command resulted in 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
The dpDirectWrite() function tries to write datapoint values from
the variables var1, var2, and so on, directly
to the PLC. Simply use the address config, which defines the connection to the PLC.
You can write any number of pairs consisting of a datapoint attribute and its value. The datapoint attributes are passed as strings, while the value's data type depends on the specific attribute. You can set multiple datapoints at once by using arrays. Make sure that the number of datapoints matches the number of values in the arrays.
The value set with the function call covers the use of status bits in _corr_value to indicate if the direct write request was successful or not.
_original.._value
and _original.._userBits/status64 configs can be written.
Attempting to write any other configs will fail and return an error code. dpDirectWrite() is
currently not supported for datapoint elements that represent only a part of a
dataset in the PLC (for example, an index within an array or a bit within an
INT). As a result, addresses that use subindexes will return an error.