dpQueryConnectSingle()

Like dpQueryConnectAll() but returns as result only two lines (Heading and change to value). For exceptions see: Description.

int dpQueryConnectSingle(string workfunc, bool wantsanswer, anytype userData, string query,[int blockingTime]);

Parameter

Meaning

workfunc

Name of the work function

wantsanswer

Defines whether the work function is to be called spontaneously during registration

userData

User-defined data which is passed as parameter to the callback function.

query

The query as an SQL statement

CAUTION!

Note that for the Connect functions only DPE's of one system may be specified.

delay

Timerange  in [ms] where the call of the  CB-Function from open queries is blocked. Without the entry the value is taken from the config file (see queryHLBlockedTime), with  0 nothing is blocked, otherwise the delay has to be given in [ms](<=32767).   

dpQueryConnectSingle() returns 0, -1 in the event of an error.

Note

The return value only indicates whether a CONNECT message was sent, but not whether the execution of the function (query) was successful. The error is written to the thread after the function has been executed and can be retrieved with a subsequent call to the function getLastError(). See also Error Handling.

Errors can be retrieved with getLastError() . This includes missing arguments (also of the work function), undefined functions, incorrect arguments ( for example, no Control expression), and if no identifier or query is specified. The usage of not initialized variables for the parameter userData will raise an error.

The function dpQueryConnectSingle() is identical to dpQueryConnectAll() except the type of registration. If a change is made only  two lines (Heading and change to value) are returned. If an immediate answer after registration with wantsanswer is "true" is forced, the entire table is returned. The optional parameter delay allows a time definition for blocking queries. That means that the work function is not called immediately after value change, but awaiting the time (indicated with delay) and finally the open queries are transferred at one time to the work function. The registered function workfunc() must have the following transfer parameters:

void workfunc(anytype userData, dyn_dyn_anytype result)

Parameters

Meaning

userData

Name for assignment of the function

result

Result of the query (two lines: Heading and change to value)

Notes

• When querying the _original config of a DPE the result contains also struct elements (structs) are returned if also an update of the query was performed (= new data points were created). Normally, blank lines are filtered when creating a query so that structs are removed. When updating a query, however, new data points are added to the table with the result that from that date also structs are available in the table. For performance reasons the structs are filtered from the table when creating a query.

• If several data point values are changed simultaneously, the work function is called only once.

• A connect to all elements in the database is only possible for _original, _online and _offline configs, for example:
  
  "SELECT '_original.._value' FROM '*'"
  
  but not for other configs, for example:
  
  "SELECT '_alert_hdl.._active' FROM '*' WHERE ('_alert_hdl.._active' == 0)").
  
  "SELECT ALL" and "SELECT with TIMERANGE" queries are forwarded to the Data manager. The Data manager does not accept dpQuery* calls (these are only processed by the Event manager).
  
  A query, which FROM part affects more than 80% of all DPEs, is registered as "Connect to all".

• Note that if you want to include a data point type in query you can do it in the following way:
  
  dpQuery("SELECT '_online.._value' FROM '*' WHERE _DPT = \"ExampleDP_Float\" ", tab);

Example

int rc;

anytype userData = getUserName();

setValue("Text1","backCol","Red");

rc = dpQueryConnectSingle("work", true, userData, "SELECT ALERT SINGLE '_alert_hdl.._value' FROM 'E*'");

DebugN("nach QueryConnectSingle: ", rc);

int i;

DebugN("Callback:", dynlen(val), userData);

for (i = 2; i <= dynlen(val); i++)

DebugN("Wert: ", i, val[i][1], val[i][2], "Benutzer: ", userData);

Data point function, Waiting Control function

UI, CTRL, DP, W

dpQuery(), dpQueryConnectAll(), dpQueryDisconnect(), isRefresh(), isAnswer(), Basics SQL in Control