|
Synopsis
int dpConnect(string work[, bool answer = TRUE], string dpe1[, string dpe2 ...]); int dpConnect(string work[, bool answer = TRUE], dyn_string dp-list); |
Parameters
Parameter |
Meaning |
work |
Name of the callback function ("work function") that is called when the values or attributes are changed. |
answer |
Specifies if the callback function should be executed the first time already when the dpConnect() is called or first every time a value changes. The default value is TRUE (first callback is executed when the dpConnect() is called) |
dpe1, dpe2, ... | dp_list |
Data point attributes or a data point list to be registered. If you pass a data point list, the DPEs and values in the work function are passed as a dyn_string dp-list and dyn_<type> Values. See example below.
CAUTION! Do not use data points of different systems! The function dpConnect() only works for one system. If dpConnect() is used for at least two systems, it does not work and the following error message is shown:
WCCOAui (1), 2006.09.26 14:11:19.266, PARAM,SEVERE, 175, this request cannot address more than one system, DP: dist_789:ExampleDP_Arg1.:_original.._value WCCOAui (1), 2006.09.26 14:11:19.266, CTRL, WARNING, 76, Invalid argument in function,
CAUTION! If you access an address config using a dpConnect, the address may not be changed after the dpConnect, in the PARA and the attribute _type may not be set since the config is recreated. The dpConnect is called each time a value of the attribute is changed. |
Return value
dpConnect() returns 0, in the event of a failure returns -1. |
Error
The return value of dpConnectUserData() is returned only if the syntax in the function was correct. To get information whether the call of the function dpConnect() was successful, the function getLastError() must be called. With the function throwError() the error message can be written to the PVSS_II.log log file. Example
|
Description
If values of the data point attributes dpe1, dpe2 ... change a callback function is called (the work() function is registered and called when values are changed). This callback function (is also called work function) is executed spontaneous each time when some of the registered data point values /attributes (provided that all elements contained in the function call are passed) changes. An arbitrary number of DP attributes can be registered except some attributes of the "_alert_hdl" config. These attributes can be queried via the function alertConnect() (see the _alert_hdl table). Only the attributes "_prior", "_act_state_color", "_act_state_fore_color", "_act_state_font_style", "_text" and "panel" of the table are available for dpConnect(). Note The DP attribute _status calls the callback function only then, when the status has changed. The behavior differs to the _value attribute, where the callback function is called for each value input (regardless of whether the value has changed or not).
|
When dpConnect() is called the callback function is executed immediately once with the current data point values if the argument answer was not set to "false";. If a specified attribute is modified while the callback function is executed, the next callback function call is executed first when the preceding call has been completed. The registration (function is called when values are changed) is valid until the function dpDisconnect() stops the registration, the manager that executes is stopped or the panel is closed in the UI. |
The registered callback function must contain the following parameters: in addition to the value (data type of the attribute) also the identifier of the data point attribute is returned as a string for each registered data point attribute. The order of these pairs (identifier + value) has to correspond to the registration via dpConnect(). The name of the callback function can of course be assigned freely. Also the declaration within a library is possible. When the function names are same the local definition in a script wins against the global panel and manager definitions. Via this hierarchy it is possible to use the same function name more often in the same process image (panel) in the different event scripts of the graphics objects. The local function definition wins. |
void work(string dpe1, <type1> var1 [, string dpe2, <type2> var2 ...]) |
Caution If the callback function of the dpConnect function contains default parameters, also the dpConnect call must contain these parameters. Otherwise the error message "WCCOAui (1), 2007.01.15 17:49:18.384, IMPL, WARNING, 54, Unexpected state, CtrlScript, dpVC, too less items in DpHLGroup, callback function myWork not started" is shown.
If the registered attributes are multilingual text elements these are returned to the control instance (Control manager, UI) only in the current language. UseThe function dpConnect() is used above all for displaying or processing current values and states. If, for example, a value should be shown in a process image the registration for the value changes in a dpConnect() is made within the Initialize(). See also GEDI and Control scripts. The associated callback function is executed each time a value changes. The function updates the value representation in the process image. |
Caution If a callback function is not yet completed when an event occurs again the event is added to a queue until all previous function calls have been executed. If the frequency of the events is higher than as these can be processed, the queue of pending events and with it the memory consumption of the CTRL Manager or UI Manager keeps on growing. If a callback function has more events to process than the number set in the config file, the following warning (or another error output) is displayed in the Log Viewer:
"Function has ... pending runs-> DISCARDING" Caution The default maximum amount of the queue (events that have to be executed) is 200. As soon as this amount is reached the system discards all calls except the youngest and processes only the last value. The queue can grow again. The maximum value can be set selective via the config entry ctrlMaxPendings in the UI and CTRL Manager sections. Note If the config + attribute are left out when the data point elements are registered (see addressing) the system handles this as if the online value (_online.._value) would be specified. Note Normally a dpConnect() with several registered elements returns a callback function call for each value change of an attribute. Thereby all "registered" values are passed to the CB function. If a number of value and attribute changes are sent in a single dpSet() the registration returns only a single common callback function call. A single callback function call is also returned for common registrations for attributes that belong together (like value, time stamp and status (quality) of a single data point element). See the last example. |
Example |
Calculate C = A+B. The name of the callback function is add(). The parameters passed are"Pipe_A.flow:_online.._value" and "Pipe_B.flow:_online.._value". The data point Pipe_C.flow is set via a dpSet() command. |
main()
{ dpConnect("add", "Pipe_A.flow","Pipe_B.flow"); } add(string dp1, float a, string dp2, float b) { dpSet("Pipe_C.flow", a + b); } |
Note In the last example the attribute identifiers _online.._value and _original.._value were left out (for example, "Pipe_B.flow:_online.._value"). If only the data point element is named the original value is automatically used for "set" operations and the online value for "read" operations.
Example A measured value that is displayed in the system via the data point element Drive014.speed should be visualized in a process image (panel). The value (display) should be formatted (decimal places) and the unit should be specified in a text field.
Solution Add the following program to the Initialize script of the text field. The function dpValToString() formats the value according to the number format and engineer unit specified for the data point element. The option specified as comment would display the number without formatting and with an arbitrary number of decimal places in the text field.
main() { dpConnect("displayValue","Drive014.speed"); }
displayValue(string dpe, float speed) { this.text = dpValToString(dpe, speed, true); }
Example Information about a drive should be shown in a device symbol. The data point type of the drive looks as follows:
Figure: Device symbol
The symbol should visualize the information On/Off (Drive014.speed > 0) and operational mode Hand Drive014.manual= TRUE). Furthermore the current message status color of alert handling on Drive014.fault should be shown in case of errors. Also the quality information (status: invalid, bad) of the actual .speed value is analyzed and displayed in the symbol.
Solution Write the following program in the Initialize script of the drive symbol. The dpConnect() within the if query is executed first anyway. If the dpConnect cannot be executed (for example, configuration error: the data points do not exist at all) the symbol shows this via a color change (named color "_dpdoesnotexist"). This way erroneous and incomplete configurations are detected immediately.
dpConnect() executes two registrations for two online values, a virtual quality bit and the (in each case) valid color of the current alert range of a data point element. After evaluating which combination of On/Off is available at which status (quality information) all necessary graphics attributes are set at once. This prevents the flickering of display also when there is a large number of objects.
main() { if (dpConnect("visualizeDrive", "Drive014.speed", "Drive014.speed:_online.._bad", "Drive014.fault:_alert_hdl.._act_state_color", /* color of the alert handling */ "Drive014.manual") == -1) setValue("","backCol","_dpdoesnotexist"); // this.backCol = "_dpedoesnotexist"; } visualizeDrive( string dpe1, float speed, string dpe2, bool invalid, string dpe3, string alertCol, string dpe4, bool manmode) { string symbolCol; if (speed > 0) { if (invalid) symbolCol = "STD_device_on_invalid"; /* create this color using the color editor or use some of the default colors like "STD_value_invalid" */ else symbolCol = "STD_device_on"; //default color } else { if (invalid) symbolCol = "STD_device_off_invalid"; /* create this color using the color editor or use some of the default colors like "STD_value_invalid" */ else symbolCol = "STD_device_off"; } setMultiValue("DriveSymbol","backCol",symbolCol, "DriveSymbol","foreCol",alertCol, "InvalidIndicator","visible",invalid, "ManualIndicator","visible",manmode); } Notes
Example All set point changes of the drive, that was shown
in the last example should be logged in the LogViewer during a
test run. In addition to the actual value the time stamp, the
user that changed the value (ID and user name) and the quality
information "INVALID"; have to be printed.
Solution The registration on the necessary attributes of the data point element can be executed via a single dpConnect(). Although also , for example, the source time (_stime) and maybe the user change when the value changes the callback function logSP is called only once in this case (each value change generates only a single row, see result). The attributes passed via the parameters of the callback function are formatted before printed via DebugN(). The last row of the command DebugN checks (via a condition operator) if the invalid attribute is set. The DebugN is only executed if the invalid attribute is set.
main() { dpConnect("logSP", "Drive014.cmd.setpoint", "Drive014.cmd.setpoint:_online.._stime", "Drive014.cmd.setpoint:_online.._user", "Drive014.cmd.setpoint:_online.._manager", "Drive014.cmd.setpoint:_online.._invalid"); } logSP( string dpe1, float setpoint, string dpe2, time stime, string dpe3, int uid, string dpe4, int manNum, string dpe5, bool invalid) { string valStr, managerString; sprintf(valStr, "%5.2f", setpoint); // formatting of the value convManIntToName(manNum, managerString); /* extraction of the manager identifier*/
DebugN( formatTime("%c", stime, ",%03d") + " | " + "SP: " + valStr + " | " + getUserName(uid) + " " + "on " + managerString + " | " + (invalid?"Invalid!":"")); }Result
["04.11.2003 16:56:48,629 | SP: 1250.00 | root on UI -num 2 | "] ["04.11.2003 16:57:08,638 | SP: 1500.00 | John Q. Public on UI -num 1 | "] ["04.11.2003 16:57:13,024 | SP: 1520.00 | John Q. Public on UI -num 1 | "] ["04.11.2003 16:57:21,556 | SP: 1200.00 | root on UI -num 2 | "] ["04.11.2003 16:57:34,545 | SP: 1190.00 | John Q. Public on UI -num 1 | "] ["04.11.2003 16:57:58,479 | SP: -5.00 | root on UI -num 2 | Invalid!"] Examples for correct and incorrect addressing of data point elements
ret = dpConnect("ReportEvent1", TRUE, "TestReport"); //this call reports ret=0 which is success, but the callback fails
ret = dpConnect("ReportEvent1", TRUE, "TestReport.:_online.._value"); //this call also works fine and the callback works dpConnect including a list of data pointsYou can also pass a list of data points to the callback function when using dpConnect(), dpDisconnect(), alertConnect()or alertDisconnect(). The DPEs and values to the callback function are passed as a dyn_string dp_list and dyn_<type> Values. Example 1In the following example a data point list with three data points is passed. The output of the values is done in the callback function.
The main program:
main() { dyn_string dpL;
int ans;
dpL[1] = "ExampleDP_Arg1.:_online.._value"; dpL[2] = "ExampleDP_Arg2.:_online.._value"; dpL[3] = "ExampleDP_Result.:_online.._value";
ans = dpConnect("workFu",dpL); DebugN("Result of dpConnect", ans); }
The callback function:
workFu(dyn_string dpL, dyn_float val) { DebugN("The data point values",val); } Example 2main() { dpConnect("workCB", makeDynString("ExampleDP_Arg1.", "ExampleDP_Arg2.")); delay(2); dpDisconnect("workCB", makeDynString("ExampleDP_Arg1.", "ExampleDP_Arg2.")); } workCB(string dp1, float v1, string dp2, float v2) { DebugN(dp1, v1, dp2, v2); } Example 3main() { alertConnect("work", makeDynString(":_alert_hdl.._text",":_alert_hdl.._visible")); delay(2); alertDisconnect("work", makeDynString(":_alert_hdl.._text",":_alert_hdl.._visible"));
} void work(time t, int count, string alert1, string var1 , string alert2, bool var2) { DebugN(t, count, alert1, var1, alert2, var2); } Information about dpConnects()Information about dpConnects can be queried using the attributes _dpids, _manids and _mancount.
The following example shows you how to use these attributes:
Several dpConnects are executed and the attributes are queried.
main() { dpConnect("add", "testDp1.:_online.._value", "testDp2.:_online.._value"); DebugN("the second dpconnect"); dpConnect("add_n","ExampleDP_Arg1.:_online.._value","ExampleDP_Arg2.:_online.._value"); }
add(string dp1, float a, string dp2, float b) { a = 5; b = 5;
dpSet("testDp3.:_original.._value", a + b); }
add_n(string dp1, float c, string dp2, float d) { c = 2; d = 3; dpSet("testDp4.:_original.._value", c + d); }
Query the information:
main() { dyn_dyn_string ds; dyn_dyn_string as; dyn_dyn_int dui; dyn_dyn_int hui; dyn_dyn_int di; dyn_dyn_int fi;
// Which data point elements belong to this connect group? dpGet( "ExampleDP_Arg1.:_connect.._dpids", ds);
// How often does a manager query this data point element? dpGet( "ExampleDP_Arg2.:_connect.._manids", dui);
// How often does a manager query this data point element? dpGet( "ExampleDP_Arg1.:_connect.._mancount", di);
dpGet( "testDp1.:_connect.._dpids", as); dpGet( "testDp1.:_connect.._manids", hui); dpGet( "testDp1.:_connect.._mancount", fi);
DebugN( "ExampleDP_Arg1.:_connect.._dpids", ds, "ExampleDP_Arg2.:_connect.._manids", dui, "ExampleDP_Arg1.:_connect.._mancount", di);
DebugN( "testDp1.:_connect.._dpids", as, "testDp1.:_connect.._dpids", hui, "testDp1.:_connect.._mancount", fi); } |
Member of
Data point function, Waiting Control function |
Availability
UI, CTRL, DP, W |
See also
V 3.11 SP1
Copyright ETM professional control GmbH 2013 All Rights Reserved