dpQuery()

Retrieves attribute values with the help of SQL statements.

Synopsis

int dpQuery (string query, dyn_dyn_anytype &tab);

Parameter

Parameter	Meaning
query	SQL statement
tab	Two-dimensional results table. See the example at the end of this page as well as chapter Queries and SQL keywords.

Return value

0 if execution is successful, -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.

Error

Errors can be retrieved with getLastError() . This includes incorrect or missing arguments.

Description

The function dpQuery() queries attribute values with the help of the SQL statements formulated in the string query. Please refer to the section of the manual on SQL for information about the SQL dialect used in WinCC OA. The result is stored in tab as a two-dimensional table (see Table 2).

Note

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".

Caution

It is not allowed to refer to an element in the SELECT part without the WHERE part containing "_DPT = \"XXX\" ". The columns of the result table are not clear anymore without a clear DP type!

Table: Example of the result in the variable tab

tab[1][1] (empty)	tab[1][2] column header
tab[2][1] line name 2	tab[2][2] contents of line 2
tab[3][1] line name 3	tab[3][2] contents of line 3
...	...

The first entry tab[1][1] is not used, tab[1][2] contains the overview of the columns and tab[n][1] (n>1) contains the name of the column in question. The name found in the query is finally located in tab[n][2], n>1.

Example

The original value of data points beginning with "ExampleDP_Arg" and of type "ExampleDP_Float" is returned.

main()
{

dyn_dyn_anytype tab;

int z;

dpQuery("SELECT '_original.._value' FROM 'ExampleDP_Arg*' WHERE _DPT= \"ExampleDP_Float\" ", tab);

// _DTP returns the type of a data point.

shape list1=getShape("SELECTION_LIST1");

for(z=2;z<=dynlen(tab);z++)

// dynlen(tab) returns the length of tab

setValue(list1,"appendItem",tab[z][2]);
}

Member of

Data point function, waiting Control function

Availability

UI, CTRL, DP, W