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. By default, the timeout is set to 10,000 ms (10 seconds).

Setting the timeout to 0 results in a minimal timeout of approximately 1 second.

If the timeout is reached (e.g.: 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 function dpDirectWrite() usually returns 0, in the event of a failure, however, it returns -1.

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 using directWrite.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.
Important:
The _original.._value and _original.._userBits/status64 configs can be written. Attempting to write any other configs will fail and return an error code.
Attention:
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.

Assignment

Datapoint Functions

Availability

UI, CONTROL