dpQueryConnectAll()

The function dpQueryConnectAll subscribes to attributes of configs from multiple Data Point Elements, which meet a certain query condition. When a subscribed attribute changes, a callback function (“work” function) is executed. The event manager will always send all subscribed elements, even if only one changes. Therefore update messages will always contain all subscribed elements.

Synopsis

int dpQueryConnectAll([class object,] string|function_ptr work, bool wantsanswer, anytype userData, string query,[ int blockingTime]);

Parameters


Parameter	Meaning
object	An object of a Control++ class.
work	Name of the callback function ("work function") that is called when data point values change. Or The name of a function pointer to the work function (callback function).
wantsanswer	Defines whether the work function is to be called immediately on registration.
userData	User-defined data which is passed as parameter to the callback function.
query	The query as an SQL statement CAUTION: Connect functions can only be used for configs which are managed by the event manager. Therefore it is not possible to make a connect on the following configs: _archive, _address, _cmd_conv, _msg_conv, _smooth Note: If the query returns more than 80% of the systems data point elements, a general subscription will be performed instead of the query connect. Inside the callback function, only the elements that are returned by the sql query will be used.
delay	Timerange in [ms] where the call of the callback function is blocked by the open queries. Specify the blocking time in milliseconds <=32767. If the blockingTime is set to 0, the callback function is not blocked. Without this value, the value is read from the config entry [different sections] queryHLBlockedTime from the config file.

Return Value

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

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

Errors can be retrieved with getLastError(). This includes missing arguments (also of the work function), undefined functions, incorrect arguments (for example, no Control expression). The usage of non-initialized variables for the parameter userData will raise an error.

Description

The function dpQueryConnectAll() initializes registration to a work function workfunc, which is called when changes are made to attributes and when data points and configurations are created. When a value changes, all values of the queried data are returned and not only the value change. Restrictions such as FIRST or LAST xx in the SQL string are not taken into consideration. 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.

All attributes of configs that are held by the Event manager, such as _original, _online, _alert_hdl etc. can be queried, for example:

 "SELECT '_online.._value' FROM '*'"

But configs from other managers cannot be queried this way, e.g:

 "SELECT '_adress.._active' FROM '*' WHERE ('_adress.._active' == 0)".

The query above returns an empty string of type anytype.

Since dpQueryConnectAll() is handled in the Event Manager, the keywords "SELECT ALL" and "SELECT with TIMERANGE" should not be used for query connects

CAUTION:

There can be serious performance issues when subscribing to many attributes that are likely to change very frequently at different points in time. This would lead to a situation in which the Event Manager needs to send very large messages in rapid succession, causing high load on the CPU core and therefore delaying other Event Manager functions.

A query in which the FROM part affects more than 80% of all DPEs is registered as "Connect to all".

Note:

If you use a delay parameter in the dpQueryConnectAll() and different DPs change at different times during the delay ( for example, three different DPs change at different times within the delay), the result table (which is selected via the query and returned in the variable) is returned three times.

A query with the SQL statement SELECT ALERT ..., must not be used because of performance reasons!

The first parameter workfunc denotes the work function to be called when changes are made. It must therefore be able to process the entire table.

The registered function work() must have the following transfer parameters.

void workfunc( anytype userData, dyn_dyn_anytype result)


Parameter	Meaning
userData	User-defined data which is passed as parameter to the callback function.
result	Result of the query (table for dpQueryConnectAll())

Identifier is the specific name to assign the function, result is the result of the query. For dpQueryConnectAll() this means the entire table.

If the second parameter wantsanswer is "true", then immediately after the announcement the work function with the current table is called. The query itself is a string "query" containing the SQL SELECT statement. For details on the used SQL dialect in WinCC OA see the chapter SQL.

Crating and deleting optional data point configs only triggers a callback if the _type attribute is available for the configs.

The work function leaf is announced. The query returns all original values of the leafs for the data point "Motor1":.

main()
{
  string query;
  anytype userData;
  //_LEAF returns the leaves of the DPs
  query = "SELECT '_original.._value' FROM 'Motor1' WHERE _LEAF";
  userData = getUserName();
  dpQueryConnectAll("leaf", TRUE, userData , query);
 }
                      
void leaf(anytype userData, dyn_dyn_anytype tab)
//tab contains the entire table including the values without changes
{
  int z;
  for(z=2;z<=dynlen(tab);z++)
  {
    //...........
  }
}

You can find an example of how to use a Control++ class instance in a connect function in the chapter dpConnect().

Assignment

Data point function, waiting Control function

Availability

CTRL