dpSet()
The function assigns data point attributes values or creates data point configs.
Synopsis
int dpSet(string dp1, <type1> var1 [, string dp2, <type2> var2, ...]);int dpSet(dyn_string dpnames, dyn_anytype values);Parameters
| Parameter | Meaning |
|---|---|
| dp1 |
Data point attribute (for example, "Valve17.opening:_original..value"), or data point name CAUTION:
Do not use data points of different systems! The function dpSet() only works for one system. If the dpSet() is used for at least two systems, it does not work and the following error message is shown: |
| var1 | Value that is assigned ( for example, 40) or DPCONFIG_DEFAULTVALUE |
Return Value
The function dpSet() usually returns 0, in the event of a failure, however, it returns -1.
Errors
Errors of the related (CTRL) manager can be retrieved with getLastError(). The return value is then the appropriate error code. Errors issued by other managers (Event) can be retrieved with getLastError() only when using waiting functions (see dpSetWait()).
An error is issued in the event of non-existent data points or spelling errors. In case of value range violations exceptions are not generated and error messages are not shown for value range violations.
Description
The function dpSet() assigns the values var1, var2, ... to the data point attributes. You can transfer any number of pairs of data point attributes and values to the function dpSet(). The data point attributes are transferred as a string, the data type of the value depends on the attribute in question. Several data points can be set at the same time with an array. The number of data points and the values in the arrays must be the same!
You can add a config, for example, to an existing data point element or delete it with the help of the function dpSet(), or dpSetTimed(). To do this simply specify the attribute "_type" of the config in question. The appropriate Control constant must be set as the value. These values can be found in the appendix under the appropriate config.
-
In one dpSet() function it is not allowed to assign a value to the same data point attribute several times. In this event only the first assignment is accepted and the other ones are discarded. The return value is 0, an appropriate error can be retrieved with getLastError().
-
Please consider that, with an increased number of value pairs, the time consumed for processing the values may highly increase.
The appendix also contains the other Control constants with their associated integer values which you can set (dpSet()) or retrieve (dpGet()).
If there exists no definition for a config or attribute, the following defaults are used and added internal:
| Function | Default |
|---|---|
| dpSet*() | _original.._value |
| dpGet() | _online.._value |
| dpGetAsynch() | _offline.._value |
| dpGetPeriod() | _offline.._value |
| dpConnect() | _online.._value |
| dpDisconnect() | _online.._value |
The status bits of driver can be set via dpSet(). The status bits that are built virtual as well as the bits _default_bad and _stime_inv cannot, however, be set. See _original status bits. This is useful for test purposes, for example, in order to train users.
Atomicity of dpSet
The use of atomic dpSet() might lead to slight loss of performance.
Setting multiple values in one dpSet() operation might cause inconsistencies because certain write operations might fail while others succeed. Atomic data point set operations verify that no write operation fails before changing any values. Therefore, no inconsistencies can arise. The use of atomic dpSet() might lead to light loss of performance.
By enabling "atomicDpSet" in the "general" section of the config file, i.e, setting "atomicDpSet = 1", all data point set operations for Original, Lock, and General configs are atomic, except for write operations initiated by WinCC OA drivers, which are never atomic.
If atomic behavior is activated but a data point set operation includes other configs besides Original, Lock, and General, the operation is handled non-atomic. By default atomic set behavior is deactivated.
Atomic behavior can be used for all data point set operations supported by WinCC OA ("dpSet", "dpSetWait", etc.). If these operations are restricted to Original, Lock, and General configs either all set operations succeed or no operations are executed. In case of a failure, the return code is set accordingly and further error messages can be retrieved in the usual way.
Set the regulation ratio of valve Valve17 to 40%.
main()
{
int rc; // return code
rc=dpSet("Valve17.opening:_original.._value", 40);
DebugN(rc);
}Adding the config "replacement" to the data point element Valve17.opening.
main()
{
int rc;
rc=dpSet("Valve17.opening:_default.._type", DPCONFIG_DEFAULTVALUE);
DebugN(rc);
}Deleting the config "replacement" for the data point element Valve17.opening.
main()
{
int rc;
rc=dpSet("Valve17.opening:_default.._type", DPCONFIG_NONE);
DebugN(rc);
}Another possibility is the following call with dynamic parameters:
main()
{
dpSet(makeDynString("test1.:_original.._value","test2.:_original.._value", "test3.:_original.._value","test4.:_original.._value", "test5.:_original.._value"), makeDynBool(false, false, false, false, false));
}Assignment
Data point function
Availability
UI, CTRL
