Accessing Data via SQL in Structured Text

[Anonymous user]

📖 Home  Back  
In a structured text program you can define simple variables using %M, %I and %Q, however useful these are they are static.

There is a more dynamic way of reading data from ClearSCADA to use in a structured text program that returns the data in the form of a "resultset" (similar to ADO's RecordSet). This is defined using %S and a new TYPE declaration. It can only access data from within ClearSCADA, that is, you cannot use %S to run a query against an external database.

Due to the way that SQL commands within logic programs are handled, it is critical that sensible queries are used. Inappropriate queries can severely impact performance of the system and potentially delay other system operations.

TYPE

The first step is to define a suitable data type to store each row returned from the query. This is achieved using the TYPE keyword and derived using DATABASE_OBJECT or STRUCT keywords.

You would use DATABASE_OBJECT when accessing information from table derived from CDBObject Database Table. It allows read-write access to properties and the execution of methods (without parameters).

For example,

TYPE
  Point :  DATABASE_OBJECT(CPointAlgManual)
   FullName : STRING;
   CurrentValue : LREAL;
  END_DATABASE_OBJECT;
END_TYPE

When using DATABASE_OBJECT it automatically includes the Id field as a column, so if you will be looking at a table without an Id Metadata Columns then the DATABASE_OBJECT cannot be used. The table defined (CPointAlgManual in the example) must be the table referred to in the SQL later. Anything derived from the base class CDBObject (i.e. all database objects) has an Id metadata column, however creating a column in a datagrid called Id does not count.

Also, if you plan on using a JOIN you'll not be able to use DATABASE_OBJECT. Instead you have to use STRUCT.

For example,

TYPE
  Point :
  STRUCT
    Id : DINT;
    FullName : STRING;
    CurrentValue : LREAL;
  END_STRUCT;
END_TYPE

Structurally, DATABASE_OBJECT and STRUCT are the same, however you cannot use methods in a STRUCT. A STRUCT does not assume anything, such as the Id column is included, and the STRUCT may point to any table within ClearSCADA, or multiple tables (JOINs). The order of the columns is important as they must be the same as in the SQL SELECT query.

Once you have your new TYPE defined you can declare the SQL to retrieve the resultset.

Declaration

The declaration of the resultset is similar to normal variables, it must exist within the VAR/END_VAR blocks only containing other external variables (%M, %I, %Q and %D).

For example,

VAR
  Points AT %S(SELECT Id, FullName, CurrentValue FROM CPointAlgManual) : RESULTSET OF Point
END_VAR

The above declaration will work for both DATABASE_OBJECT and STRUCT examples of TYPE and will return all Internal Analogues and their current value.

You can also pass in parameters declared in the VAR_INPUT block.

For example,

VAR
  Points AT %S(SELECT Id, FullName, CurrentValue FROM CPointAlgManual WHERE FullName LIKE '%' || ? OR FullName LIKE ? || '%') : RESULTSET OF Point WITH_PARAMS Name, Name;
END_VAR

The || is there to concatenate the % onto the start or end of the condition. If you just wanted a simple comparison then the following is suitable, even for strings:

VAR
  Points AT %S(SELECT Id, FullName, CurrentValue FROM CPointAlgManual WHERE FullName LIKE ?) : RESULTSET OF Point WITH_PARAMS Name;
END_VAR

Using the Resultset

Once you have a resultset you can access its information. The following properties are available:

• .Value - Allows access to column values.
• .Valid (BOOL) - Indicates if the end of the resultset has been reached (similar to EOF).
• .Size (DINT) - Number of rows in resultset.
• .Idx (DINT) - Index of the current row.

The following methods are available to navigate the resultset:

• .First()
• .Last()
• .Next()
• .Prev()

For example,

WHILE Points.Valid DO
  Count := Count + Points.Value.CurrentValue;
  Points.Next();
END_WHILE;

The .Last() method moves the cursor to the last record, not after the end of the last record. This means that .Valid will still return True and if you were using .Last to break out of a WHILE loop then if the condition of the break happens on the last record, you could get into an infinite loop. You may have to call .Next() after a .Last() to go beyond the bounds of the resultset and .Valid() to become false. For example,

WHILE Points.Valid DO
  IF Count > 100 THEN
    Points.Last();
    Points.Next(); (* Required else could cause an infinite loop after a few points had be summed up in the Count value*)
  ELSE
    Count := Count + Points.Value.CurrentValue;
    Points.Next();
  END_IF;
END_WHILE;

Things To Remember/Note

• With the exception of VECTORs the STRUCT data structure is read-only, DATABASE_OBJECT supports writing to properties and calling methods.
• STRUCT can point to any ClearSCADA table (historic, events, data grids, data tables, CDBObject derivatives) whilst DATABASE_OBJECT can only point to CDBObject derivatives.
• The %S is a much larger performance hit (relatively) on the database compared to using %M, %I and %Q as it's the same as a normal SQL query. You can have many %S and TYPE declarations however the more %S you use, the slower the logic to initialise. Make sure you control your SQL to reduce the amount of data as much as possible using WHERE clauses and that the logic doesn't execute too often
• If you forget to call .Next() in a WHILE loop then the logic will try to go into an infinite loop, however will error after a second or so with the "Too many opcodes exceeded message". It will keep trying to execute the logic program though and could cause system slowdowns.
• The SQL used is the same as elsewhere in the product, so you can use UNIONS, JOINS, TOP, etc without problem, however UNIONS and JOINS need to use STRUCT instead of DATABASE_OBJECT.
• When using linked tables a database write lock will be maintained whilst the data is collected. If the query to the target data source takes more than a second then performance of the ClearSCADA system may start degrade depending on how often that query is executed. Care should be taken when using linked tables. For more information on how logic executes refer to Logic Execution

Go: Home Back