logic guide clearscada 2010

This document and attachments contain confidential information and is to be treated as Commercial-In-Confidence.

Copying or disclosure to a third party is prohibited without prior consent in writing from Schneider Electric.

www.schneider-electric.comPD-6

017.

18

ClearSCADA 2010 R3

A ClearSCADA Reference Guide

07/2012

Guide to Logic

2The information provided in this documentation contains general descriptions and/or technical characteristics of the performance of the products contained herein. This documentation is not intended as a substitute for and is not to be used for determining suitability or reliability of these products for specific user applications. It is the duty of any such user or integrator to perform the appropriate and complete risk analysis, evaluation and testing of the products with respect to the relevant specific application or use thereof. Neither Schneider Electric nor any of its affiliates or subsidiaries shall be responsible or liable for misuse of the information contained herein. If you have any suggestions for improvements or amendments or have found errors in this publication, please notify us.

No part of this document may be reproduced in any form or by any means, electronic or mechanical, including photocopying, without express written permission of Schneider Electric.

All pertinent state, regional, and local safety regulations must be observed when installing and using this product. For reasons of safety and to help ensure compliance with documented system data, only the manufacturer should perform repairs to components.

When devices are used for applications with technical safety requirements, the relevant instructions must be followed.

Failure to use Schneider Electric software or approved software with our hardware products may result in injury, harm, or improper operating results.

Failure to observe this information can result in injury or equipment damage.

2005, 2012 Schneider Electric. All rights reserved.

PD-6017 07/2012

Table of Contents

Safety Information.........................................................................................9

About the Guide...........................................................................................11

1 Welcome to the Guide to Logic..................................................................13

2 Working with Logic Programs....................................................................15

Supported Logic Languages ................................................................................................. 16

How Logic Programs Work.................................................................................................... 18

Choosing a Logic Program.................................................................................................... 19

Using Outputs as Inputs (Feedback Loops) in Logic Programs.......................................... 20

Execution Order for Logic Programs..................................................................................... 21

Troubleshooting Logic Programs........................................................................................... 25

3 Characters for Use in Logic .......................................................................27

Restricted Character Set - Logic........................................................................................... 27

4 ST Programs ................................................................................................29

Create an ST Program in the ClearSCADA Database ........................................................... 31

Edit an ST Program ............................................................................................................... 32

Understanding the Basic Structure of an ST Program.......................................................... 34

Statements, Expressions and Operators............................................................................... 37

Statements ..................................................................................................................... 37

Expressions .................................................................................................................... 38

Operators ....................................................................................................................... 39

Entering a Comment.............................................................................................................. 40

Internal Variables ................................................................................................................... 40

Adding an Internal Variable to an ST Program ............................................................... 41

Using the RETAIN Keyword in an ST Program............................................................... 42

Direct Variables...................................................................................................................... 43

Using the VAR List to Access Direct Variables............................................................... 44

Using VAR NOCACHE to Prevent Cached Values Being Used in an ST Program......... 46

Using Database Object Structures to Access Direct Variables...................................... 48

Using SQL Queries to Access Direct Variables .............................................................. 50

Using Vectors to Access Direct Variables ...................................................................... 51

Indirect Variables ................................................................................................................... 52

Constants .............................................................................................................................. 57

Historic Values in ST Programs ............................................................................................. 58

Accessing Historic Direct Variables................................................................................ 58

Processed Historic Values in ST Programs (Historic Data Arrays) ................................. 61

Historic Functions and Arguments ................................................................................. 62 3PD-6017 07/2012

Built-In Data Types ................................................................................................................ 63

Integer Values................................................................................................................. 63

Floating Point Values...................................................................................................... 68

Time and Date Values..................................................................................................... 68

Binary Values.................................................................................................................. 70

String Values .................................................................................................................. 71

Derived Data Types ............................................................................................................... 72

Using Derived Data Types to Create Names for Types of Value .................................... 72

Using Structured Data Types to Group Internal Values.................................................. 73

Using Enumerated Data Types to Create Names for State Values ................................ 77

Using Nested Data Structures........................................................................................ 79

Arrays ............................................................................................................................. 80

Vectors ........................................................................................................................... 81

Setting the Default Values ..................................................................................................... 87

Default Values for Built-in Data Types (Literals).............................................................. 87

Default Values for Derived Data Types ........................................................................... 88

Default Values for Enumerated Data Types.................................................................... 88

Default Values for Structured Data Types ...................................................................... 89

Executing Methods on Database Items ................................................................................ 90

Viewing which Methods are Available ............................................................................ 90

Entering Methods in your ST Program........................................................................... 91

Declaring a Method in a METHOD Block....................................................................... 91

Declaring a Method in a DATABASE_OBJECT Structure............................................... 96

Calling a Method ............................................................................................................ 99

Controlling the Flow of the Program ................................................................................... 100

IF - THEN - ELSE ......................................................................................................... 100

IF - THEN - ELSIF - ELSE............................................................................................. 102

AND, OR, and XOR ...................................................................................................... 103

CASE - OF.................................................................................................................... 104

FOR - TO - BY.............................................................................................................. 106

WHILE - DO.................................................................................................................. 107

REPEAT - UNTIL........................................................................................................... 109

RETURN ....................................................................................................................... 110

Using an ST Program to Call an SQL Query ....................................................................... 112

Inserting, Updating, and Deleting Values by Using SQL in an ST Program ........................ 116

Passing Multiple Parameters into an SQL Query in an ST Program ................................... 119

Function Blocks in ST Programs......................................................................................... 121

Using Libraries in ST Programs........................................................................................... 121

Compiling an ST Program or ST Library ............................................................................. 122

Debugging an ST Program or ST Library ............................................................................ 124

Viewing the Variables in your ST Program........................................................................... 127

5 Ladder Diagrams ...................................................................................... 129

How Ladder Diagrams Work ............................................................................................... 130

Ladder Diagram Components ............................................................................................. 1314 PD-6017 07/2012

Create a Ladder Diagram Database Item............................................................................ 132

Edit a Ladder Diagram......................................................................................................... 132

Ladder Diagram Display ...................................................................................................... 133

Add Variables to a Ladder Diagram..................................................................................... 134

Add a Direct Variable to a Ladder Diagram.................................................................. 134

Add an Internal Variable to a Ladder Diagram ............................................................. 139

Add Processed Historic Values to Ladder Diagrams .......................................................... 141

Add a Constant Value to a Ladder Diagram........................................................................ 145

Add a Function to a Ladder Diagram .................................................................................. 146

Add a Function Block to a Ladder Diagram ........................................................................ 147

Add a Conversion to a Ladder Diagram.............................................................................. 148

Add a Comment to a Ladder Diagram ................................................................................ 149

Controlling the Flow of a Ladder Diagram........................................................................... 150

Make a Connection on a Ladder Diagram ................................................................... 150

Add a Connection Block to a Ladder Diagram ............................................................ 150

Edit a Variable on a Ladder Diagram................................................................................... 151

Rename a Variable on a Ladder Diagram............................................................................ 151

Delete a Variable on a Ladder Diagram............................................................................... 152

Compiling a Ladder Diagram............................................................................................... 153

Viewing the Variables in your Ladder Diagram.................................................................... 154

Changing the Update Interval for a Ladder Diagram .......................................................... 155

6 Function Block Diagrams .........................................................................157

How Function Block Diagrams Work................................................................................... 158

Function Block Diagram Components ................................................................................ 159

Create a Function Block Diagram Database Item ............................................................... 160

Edit a Function Block Diagram............................................................................................ 160

Function Block Diagram Display ......................................................................................... 161

Add Variables to a Function Block Diagram........................................................................ 162

Add a Direct Variable to a Function Block Diagram ..................................................... 162

Add an Internal Variable to a Function Block Diagram................................................. 167

Add Processed Historic Values to Function Block Diagrams.............................................. 169

Add Raw Historic Values to Function Block Diagrams........................................................ 173

Add a Constant Value to a Function Block Diagram ........................................................... 174

Add a Function to a Function Block Diagram ..................................................................... 175

Add a Function Block to a Function Block Diagram ........................................................... 176

Add a Conversion to a Function Block Diagram ................................................................. 177

Add a Comment to a Function Block Diagram.................................................................... 178

Create a Ladder Diagram within a Function Block Diagram ............................................... 179

Controlling the Flow of a Function Block Diagram.............................................................. 180

Make a Connection on a Function Block Diagram....................................................... 180

Add a Connection Block to a Function Block Diagram................................................ 181

Edit a Variable on a Function Block Diagram ...................................................................... 181

Rename a Variable on a Function Block Diagram ............................................................... 182

Delete a Variable on a Function Block Diagram .................................................................. 183 5PD-6017 07/2012

Compiling a Function Block Diagram or Function Block Library ........................................ 184

Viewing the Variables in your Function Block Diagram ....................................................... 185

Changing the Update Interval for a Function Block Diagram.............................................. 186

Viewing the Values on a Function Block Diagram............................................................... 187

7 Sequential Function Charts ..................................................................... 189

Sequential Function Chart Components ............................................................................. 190

Steps ............................................................................................................................ 190

Transitions .................................................................................................................... 191

Actions ......................................................................................................................... 191

Action Associations...................................................................................................... 192

Comments.................................................................................................................... 192

Connections ................................................................................................................. 193

How Sequential Function Charts Work ............................................................................... 194

Simultaneous Sequences.................................................................................................... 197

Create a Sequential Function Chart Database Item............................................................ 200

Display a Sequential Function Chart ................................................................................... 201

Add Direct and Internal Variables to a Sequential Function Chart ...................................... 202

Add a Step to a Sequential Function Chart......................................................................... 204

Define a Step as the First Step in a Sequential Function Chart .......................................... 204

Add a Transition to a Sequential Function Chart................................................................. 205

Edit a Transition ................................................................................................................... 206

Display the Actions Window on a Sequential Function Chart............................................. 207

Add an Action to a Sequential Function Chart.................................................................... 208

Edit an Action on a Sequential Function Chart ................................................................... 209

Edit an Action Association .................................................................................................. 210

Add a Comment to a Sequential Function Chart ................................................................ 213

Edit a Comment on a Sequential Function Chart................................................................ 213

Add a Method Variable to a Sequential Function Chart ...................................................... 214

Initiate a Method on a Sequential Function Chart............................................................... 216

Insert a Breakpoint on a Step in a Sequential Function Chart ............................................ 218

Delete Sequential Function Chart Components.................................................................. 218

Rename Sequential Function Chart Components............................................................... 218

Compiling a Sequential Function Chart .............................................................................. 219

Viewing the Variables in your Sequential Function Chart .................................................... 220

Changing the Update Interval for a Sequential Function Chart .......................................... 221

8 Built-in Functions, Function Blocks, and Conversions......................... 223

Using EN and ENO to Control when a Function is Performed............................................ 224

Combining Functions with other Functions ........................................................................ 225

Built-In Functions ................................................................................................................ 226

Arithmetic ..................................................................................................................... 226

Bit String....................................................................................................................... 234

Bitwise/Boolean ........................................................................................................... 239

Comparison.................................................................................................................. 2446 PD-6017 07/2012

Date and Time .............................................................................................................. 251

Numerical ..................................................................................................................... 278

Selection....................................................................................................................... 291

String ............................................................................................................................ 297

Misc.............................................................................................................................. 310

Built-In Function Blocks ...................................................................................................... 319

Counters....................................................................................................................... 319

State Change Detectors ............................................................................................... 330

Set and Reset Bistables ............................................................................................... 334

Timers........................................................................................................................... 339

Conversions......................................................................................................................... 346

Using Logic to Run an Executable File................................................................................ 348

Using Logic to Write to a File or Serial Port ........................................................................ 348

9 User Function Blocks................................................................................349

Create an ST Library............................................................................................................ 350

Edit an ST Library ................................................................................................................ 350

Create a Function Block Library .......................................................................................... 353

Edit a Function Block Library .............................................................................................. 354

Reference an ST Library or Function Block Library in a Logic Diagram ............................. 355

Reference an ST Library or Function Block in an ST Program............................................ 356

Update an ST Library or Function Block Library ................................................................. 357

10 Logic Program Properties and Values.....................................................359

Configure an ST Program, Ladder Diagram, SFC or FBD................................................... 359

Enable or Disable a Logic Program.............................................................................. 362

Define the Severity of a Logic Program's Alarms and Events...................................... 363

Define the Execution Settings for a Logic Program ..................................................... 364

Define when a Logic Program Updates its Outputs..................................................... 377

Define whether a Logic Program Executes Methods after a Failed Method................ 379

Define the Conversion Types for a Logic Program....................................................... 380

Define the Number of Instructions for a Logic Program .............................................. 382

Define the Time Zone to be used for Calculations within the Logic Program.............. 384

Configure an ST Library....................................................................................................... 385

Choose the Color for Function Blocks Stored in ST Libraries ..................................... 386

Create a ToolTip for an ST Library................................................................................ 387

OPC Properties for Logic Programs.................................................................................... 388

11 Logic Data Types .......................................................................................389

Display the OPC Data Type for a Property .......................................................................... 389

Data Types for Logic, OPC, and ClearSCADA .................................................................... 390

Data Type Hierarchy ............................................................................................................ 392

12 Using Actions Associated with Logic Programs....................................393

Disable Execution................................................................................................................ 393 7PD-6017 07/2012

Enable Execution................................................................................................................. 394

Execute................................................................................................................................ 394

Restart Execution ................................................................................................................ 395

Set Variable ......................................................................................................................... 395

13 Logic Specific Status Attributes ............................................................. 3978 PD-6017 07/2012

Safety Information

Important Information

Read these instructions carefully, and familiarize yourself with ClearSCADA before trying to install, operate, or maintain your system. The following special messages may appear throughout this documentation or on the ClearSCADA application to warn of potential hazards or to call attention to information that clarifies or simplifies a procedure.

Please Note

Electrical equipment should be installed, operated, serviced, and maintained only by qualified personnel. No responsibility is assumed by Schneider Electric for any consequences arising out of the use of this material.

A qualified person is one who has skills and knowledge related to the construction and operation of electrical equipment and the installation, and has received safety training to recognize and avoid the hazards involved.9PD-6017 07/2012

Before You Begin

ClearSCADA is a Supervisory Control and Data Acquisition (SCADA) solution. It comprises software that is used to control and monitor various devices, applications and processes on your system. Due to ClearSCADAs central control and processing role, you must appropriately design, commission and thoroughly test your systems configuration for proper operation before placing it in service. Any further configuration changes made online (once ClearSCADA is commissioned, tested, and in service) must be thoroughly tested before being used in an operational setting.

WARNINGUNINTENDED EQUIPMENT OPERATION

The configuration of this product requires expertise in the design, configuration and programming of SCADA control systems. Only persons with such experience should be allowed to configure ClearSCADA. Only persons with the appropriate programming experience should be allowed to write any scripts, Logic programs, expressions, or SQL queries intended for use in ClearSCADA.

Follow all local and national safety codes and standards.

Failure to follow these instructions can result in death, serious injury, or equipment damage.10 PD-6017 07/2012

About the Guide

Document Scope

This guide explains how to use the ClearSCADA ViewX interface to create and edit Logic programs. ClearSCADA supports Ladder Logic, Structured Text, Function Block Diagrams and Sequential Function Charts, all of which are part of the IEC 1131-3 Programming industrial control systems standard.

This Guide is designed to explain the interfaces and includes examples of various Logic programs. It is not a reference guide to the IEC 1131-3 Programming languages.

For information on the subjects covered in this Guide, see Welcome to the Guide to Logic, on page 13.

Intended Audience

This guide is intended for engineers who are responsible for the design and creation of Logic programs (programs which define relationships between database items and system behavior). It is assumed that such engineers have an in-depth understanding of one or more of the Logic programming languages supported by ClearSCADA.

Validity Note

This guide is valid for ClearSCADA 2010 R3 running on computers that are using an appropriate Windows operating system (see Operating Systems, on page 25 in the ClearSCADA Installation Guide).

Further Information

System Requirements: see ClearSCADA System Requirements, on page 11 in the ClearSCADA Installation Guide.

Related Documents

This guide includes references to content in the following guides:

ClearSCADA Guide to Core Configuration

ClearSCADA Guide to the Database

ClearSCADA Guide to Expressions

ClearSCADA Guide to Server Administration

ClearSCADA Installation Guide.11PD-6017 07/2012

User Comments

We welcome your comments about this guide. You can reach us by e-mail at [email protected] PD-6017 07/2012

Chapter 1 - Welcome to the Guide to Logic1 Welcome to the Guide to Logic

Welcome to the ClearSCADA Guide to Logic. This guide is designed to aid you in the creation and design of ST programs, Function Block Diagrams, Ladder Diagrams, and Sequential Function Charts.

ClearSCADA supports 4 Logic languages that you can use to define relationships between values, control sequences, conversion calculations etc. These languages are part of the IEC 1131-3 Programming industrial control systems standard.

The ClearSCADA Guide to Logic consists of:

Working with Logic Programs (see page 15)

Characters for Use in Logic (see page 27)

ST Programs (see page 29)

Ladder Diagrams (see page 129)

Function Block Diagrams (see page 157)

Sequential Function Charts (see page 189)

Built-in Functions, Function Blocks, and Conversions (see page 223)

User Function Blocks (see page 349)

Logic Program Properties and Values (see page 359)

Logic Data Types (see page 389)

Logic Specific Status Attributes (see page 397).

In the sections listed above, you will find reference information that you can use to find out about the various Logic languages and how they are supported in ClearSCADA. The sections contain some detail about the programming of Logic programs, but are not designed to be a complete reference on the IEC 1131-3 standard. The purpose of this Guide is to provide details about how you can use ClearSCADA to create the Logic programs you require on your system.13PD-6017 07/2012

Chapter 1 - Welcome to the Guide to Logic14 PD-6017 07/2012

Chapter 2 - Working with Logic Programs2 Working with Logic Programs

Before you configure your own Logic programs, you need to understand:

Which Logic languages are supported by ClearSCADA (see Supported Logic Languages, on page 16)

How Logic Programs Work (see page 18)

Which type of Logic program you need to create (see Choosing a Logic Program, on page 19).

What considerations you need to make when Using Outputs as Inputs (Feedback Loops) in Logic Programs (see page 20)

How to determine the Execution Order for Logic Programs (see page 21).

NOTE: If your Logic program does not run or has unexpected results, please refer to Troubleshooting Logic Programs (see page 25).15PD-6017 07/2012

Chapter 2 - Working with Logic ProgramsSupported Logic Languages

ClearSCADA supports 4 of the languages included in the International Electro-technical Commission (IEC) standard for programming industrial control systems (IEC 1131-3):

Ladder Diagrams

Function Block Diagrams (FBDs)

Sequential Function Charts (SFCs)16 PD-6017 07/2012

Chapter 2 - Working with Logic Programs Structured Text programs (ST)

In ClearSCADA these languages are referred to as Logic programs, and you can use them to:

Define complex relationships between the values for the properties of items in the database

Perform calculations

Execute methods on items in the database (one shots, overrides, controls etc.)

For example, in the water industry, a Function Block Diagram can be used to turn pumps on when the water level drops to a specified limit.

The Logic programs are interchangeableyou can use one type of Logic program with a different type of Logic program. For example, you can use ST programs with Function Block Diagrams or Ladder Diagrams. The only exception is Sequential Function Charts which can only be used with ST programs.17PD-6017 07/2012

Chapter 2 - Working with Logic ProgramsHow Logic Programs Work

Each Logic program is configured to represent a calculation or a procedure. The Logic program uses values from the database (inputs) as part of the calculation or procedure. The result of the calculation or procedure is either written to the ClearSCADA database as a value or is used to execute a method such as a control.

Logic programs can be set to execute:

When an input value changes

At specified times.

When a Logic program begins, it reads its input values (Tag Read). These values can be the values of items in the database or can be values specified in a query.

After reading its input values, the Logic program executes. The calculation or procedure that is defined in the configuration of the Logic program is executed. The input values are used as part of the calculation or procedure.

When the Logic program has executed, it has an output. The output is either:

The setting of an item's property, for example, a value that is written to a point

or:

The execution of a method on an item in the database, for example, the output of a Logic program can initiate the Refresh Outstation method.

Logic programs are designed to have a similar architecture to PLC programs. The procedure for executing a Logic program is:

1. Logic program reads its inputs

2. Logic program executes

3. Logic program writes its outputs

This sequence of events cannot be altered. The inputs are read first, and then the program executes, and then the outputs are written. Logic programs cannot use any other type of structure.

NOTE: Methods are sometimes referred to as 'actions'.18 PD-6017 07/2012

Chapter 2 - Working with Logic ProgramsChoosing a Logic Program

You need to decide which type of Logic program you are going to use. For many requirements, you can use any of the Logic programs to achieve the required effect. However, in some situations you may need to choose a specific type of program.

By answering the questions below, you can determine whether you need to create a specific type of Logic program or can use the Logic program of your choice:

If you have a choice of which Logic program to use, we recommend that you use the Logic program that you find easiest to use. For many engineers, Ladder Diagrams are the easiest type of Logic program to understand. Ladder Diagrams use relay ladder Logic and are similar to traditional PLC programs.

Like Ladder Diagrams, Function Block Diagrams and Sequential Function Charts are graphical displays. Many users prefer to use graphical programs as they show each of the elements that form the program. It is easier to create a complex program when you can see its elements.

Structured Text (ST) is a text based programming language and is a very flexible type of Logic program. You can use ST programs to provide any type of supported behavior, but to program them you will need a good understanding of the ST language and strong programming skills.19PD-6017 07/2012

Chapter 2 - Working with Logic ProgramsFor detailed information on the Logic languages, please refer to the following sections:

ST Programs (see page 29)

Ladder Diagrams (see page 129)

Function Block Diagrams (see page 157)

Sequential Function Charts (see page 189).

When creating Logic programs, you may also need to refer to:

User Function Blocks (see page 349)

Built-in Functions, Function Blocks, and Conversions (see page 223)

Logic Program Properties and Values (see page 359).

Using Outputs as Inputs (Feedback Loops) in Logic Programs

The outputs in your Logic programs can also be used as inputs, for example, you can use the output result of an ADD function as an input on a DIV function. When an output is also an input, it is referred to as a feedback loop.

If your Logic program uses feedback loops you should use ClearSCADAs built-in diagnostics tool to check the execution order of your program.

For more information on the execution order of feedback loops, see Execution Order for Logic Programs, on page 21.20 PD-6017 07/2012

Chapter 2 - Working with Logic ProgramsExecution Order for Logic Programs

Each part of a Logic program is executed in a sequence referred to as the execution order. The way in which ClearSCADA determines the execution order varies according to the type of Logic program:

For ST programs, the execution order is clearly defined in the language syntax (ClearSCADA compiles then executes the code from top to bottom).

For Sequential Function Charts, the execution order is defined by the logical state transitions in the charts.

For Function Block Diagrams and Ladder Diagrams, ClearSCADA examines the diagrams and then generates the Structured Text (ST) equivalent of the program. ClearSCADA then compiles the ST and executes it in the same way that it would execute the code for an ST Program database item.

The execution order of Function Block Diagrams and Ladder Diagrams is determined by ClearSCADA when it generates an ST equivalent of the graphical program. Typically, when ClearSCADA generates the ST equivalent, it attempts to order the program so that inputs are processed before outputs, based on the block relationship.

For example, if we take the following simple Function Block Diagram:

When this FBD is saved, ClearSCADA will generate the ST equivalent of the program which is:

PROGRAM $FBDVAR

dig5 AT %M(.dig5) : BYTE;dig2 AT %M(.dig2) : BYTE;dig3 AT %M(.dig3) : BYTE;dig4 AT %M(.dig4) : BYTE;

END_VAR

VAR

$B1_ENO : BOOL := FALSE;$B1 : BYTE;$B2_ENO : BOOL := FALSE;$B2 : BYTE;

END_VAR

$B1 := AND( IN1 := dig3, IN2 := dig2, ENO => $B1_ENO );$B2 := OR( IN1 := $B1, IN2 := dig4, ENO => $B2_ENO );IF $B2_ENO THENdig5 := $B2;END_IF; 21PD-6017 07/2012

END_PROGRAM

Chapter 2 - Working with Logic ProgramsThe program has been arranged so that:

The OR block is processed before the output 'D'

Inputs to the OR block are processed before the OR block is processed

Inputs to the AND block are processed before the AND block is processed.

If outputs are also used as inputs (feedback loops), the execution order can become complicated. In these cases, we advise that you use ClearSCADAs built-in diagnostics tool to check the execution order of your programs. The diagnostics tool shows the ST that ClearSCADA generates for your diagram, from which you can clearly see the execution order. If the order is not as you expected, you can alter your diagram as required. When you save the altered diagram, ClearSCADA will generate new ST for the program and you can use this to see how your changes have affected the execution order.

To run the diagnostics tool, simply display the Logic program in Design Mode, then select the Build menu, then the Compile with Diagnostics option.

Example:

The following function block diagram is an example of a Logic program that could be used as a safety interlock for controlling a pump. It is used to control a pump - the pump cannot be started when there is no flow. This is achieved by establishing these relationships:

When a StartPump signal is sent, the pump motor starts. However, if a flow has not been detected after a 120 second period, the pump is stopped and locked out (the pump stops responding to controls).

When a StopPump signal is sent, the pump motor stops running.

When a ResetPump signal is sent, the pump is no longer locked out. A StartPump signal can be sent to the pump to attempt to start it, but if a flow is not detected within 120 seconds, the pump will be locked out again.

As you can see, the LockedOut output is also used as an input for an AND function. This means there is a feedback loop.

Engineers can view the execution order by running the Compile with Diagnostics tool. This displays the function block diagram as ST code in the compiler, and lists the order in which the various elements of the program are executed.22 PD-6017 07/2012

Chapter 2 - Working with Logic ProgramsThe Compile with Diagnostics feature is selected and it shows the ST that ClearSCADA has generated for the Function Block Diagram. The execution order is clearly shown in the ST code, with the code being executed from top to bottom:

The execution order is shown in the ST code in the Compiler.23PD-6017 07/2012

Chapter 2 - Working with Logic ProgramsBy analyzing the ST that has been generated for the Function Block Diagram, we can see that the execution order is as follows:

ClearSCADA executes the elements to produce the LockedOut output/input first, and then executes the elements required to produce the PointState output.24 PD-6017 07/2012

Chapter 2 - Working with Logic ProgramsTroubleshooting Logic Programs

When configuring a Logic program, you can use the compile feature to check the validity of your program. For more information, see:

Compiling an ST Program or ST Library (see page 122)

Compiling a Ladder Diagram (see page 153)

Compiling a Function Block Diagram or Function Block Library (see page 184)

Compiling a Sequential Function Chart (see page 219).

However, it is possible to have a program compile successfully at the time of configuration, but be unable to execute correctly at a later date. If your program is unable to execute correctly, there are many possible causes, including:

A database item that is referenced by the Logic program has been deleted from the database. In this situation, you need to either reconfigure the program to reference a different item or create a new item with the same address and name as the item that was deleted.

The program is set to execute On Input Processed and does not contain a valid input (see Define the Execution Method for a Logic Program, on page 367)

The program cannot read from, or write to, a property tag that is referenced in the program

The program contains a calculation that is attempting to divide by 0

A subscript value for an array exceeds the range specified for the array

The order of execution is not as expected. This is often due to the use of feedback loops where an output is also used as an input. You can use the Compile with Diagnostics option to view the actual order in which ClearSCADA executes your program and then adjust your program accordingly (see Execution Order for Logic Programs, on page 21).

In many cases, you will need to reconfigure your Logic program.

To find out more information about the specific configuration issue that is affecting the execution of your Logic program, we recommend that you:

1. Display the Logic Execution Status List (display the Queries Bar, expand the Queries branch, then display the Logic Execution Status List).

2. Locate the entry that corresponds to your Logic program

3. Examine the Error Message entry for your program. The Error Message provides a brief description of the cause of the Logic programs inability to execute.

4. Re-configure the Logic program so that the issue described in the Error Message is resolved.25PD-6017 07/2012

Chapter 2 - Working with Logic Programs26 PD-6017 07/2012

Chapter 3 - Characters for Use in Logic3 Characters for Use in Logic

When creating Logic programs, there are limitations regarding the characters you can use. These are fixed by the language standard, and mean that for some parts of your programs, you can only use certain characters from the English character set.

The characters you can use vary depending on which part of a Logic program you are defining:

Language KeywordsThe keywords you use in Logic, for example, FUNCTION, are fixed by the language standard. They cannot be changed or translated in any way.

IdentifiersWe recommend that you use a restricted character set when you create identifiers in programs (see Restricted Character Set - Logic, on page 27).

String ConstantsWhen you define constants, you can use any characters from any language. For example, you can use Chinese characters within the single quotation marks of the constant.

Tag ReferencesReferences to items in the database can use characters from any character set. However, the character set that can be used in the actual tag may be limited.

Restricted Character Set - Logic

We recommend that you only use the following characters in identifiers in Logic programs:

a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z

A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z

0, 1, 2, 3, 4, 5, 6, 7, 8, 9

_

Logic program identifiers cannot:

Begin with a number

Contain double underscores (an underscore character followed immediately by another underscore character).

NOTE: Technically, it is possible to use other characters and numbers in the Unicode standard. But we recommend that you only use the restricted character set shown above.27PD-6017 07/2012

Chapter 3 - Characters for Use in Logic28 PD-6017 07/2012

Chapter 4 - ST Programs4 ST Programs

Structured Text is a high level programming language that you can use to define the relationships between values.

ST programs can consist of:

VariablesInput and output values that can change. There are also internal variables which are values that are only used within the ST program. For example, an ST program can read the value of an input (such as the value from a property of a database item), use an internal value to perform a calculation on the input value, then write the result of the calculation to an output value.

ConstantsThese are special types of value that are used by the ST program. These values are fixed and cannot change (they are constant).

Data TypesThere are several types of value. You need to specify which type of value is applicable to each variable. For example, values such as descriptions are STRING values (they contain a string of characters) whereas values from analog points are REAL or LREAL values.

There are built-in data types, also referred to as literals, that you can use to define the type of a value. You can also use derived data types to apply meaningful names to values, group internal values, and form arrays etc.

MethodsThese are actions that can be performed by an ST program. For example, an ST program can be created to acknowledge an alarm when a specific condition occurs.

Control StructuresControl structures are used to define the Logic of the ST program. By using keywords and adhering to the formatting rules, you can create a flow of conditions and results. These define the behavior that the ST program provides.

Function BlocksFunction blocks are blocks of code that provide specific functionality, for example, convert a temperature in Celsius to a temperature in Fahrenheit. The function blocks can be used over and over again in each of your Logic programs, including ST programs.

To configure an ST program, you will need an appreciation of the Structured Text standard. As the ST programs are not graphical, some users find them more difficult to work with. However, you need to have an understanding of ST as you may need to use ST when working with Function Block Diagrams, Sequential Function Charts etc. This is especially true if you need to reference historic data or are using SQL queries.29PD-6017 07/2012

Chapter 4 - ST ProgramsWe recommend that you familiarize yourself with the following sections, even if you do not intend to work with ST programs:

Create an ST Program in the ClearSCADA Database (see page 31)

Edit an ST Program (see page 32)

Understanding the Basic Structure of an ST Program (see page 34)

Statements, Expressions and Operators (see page 37)

Entering a Comment (see page 40)

Internal Variables (see page 40)

Direct Variables (see page 43)

Constants (see page 57)

Historic Values in ST Programs (see page 58)

Built-In Data Types (see page 63)

Derived Data Types (see page 72)

Setting the Default Values (see page 87)

Executing Methods on Database Items (see page 90)

Controlling the Flow of the Program (see page 100)

Using an ST Program to Call an SQL Query (see page 112)

Inserting, Updating, and Deleting Values by Using SQL in an ST Program (see page 116)

Passing Multiple Parameters into an SQL Query in an ST Program (see page 119)

Function Blocks in ST Programs (see page 121)

Using Libraries in ST Programs (see page 121)


Debugging an ST Program or ST Library (see page 124)

Viewing the Variables in your ST Program (see page 127)

By familiarizing yourself with some of the ST basics, you will find it much easier to understand the principles of the other types of Logic program.

For information on configuring the various properties of an ST program, see Logic Program Properties and Values, on page 359.30 PD-6017 07/2012

Chapter 4 - ST ProgramsCreate an ST Program in the ClearSCADA Database

Before you can create an ST program in ClearSCADA, you need to add an ST Program item to the database. The ST Program item will store the ST code that you create.

To create an ST Program database item:

1. In the Database Bar, right-click on the system, Group, or Group Template that is to contain the ST program. A context sensitive menu is displayed.

2. Select the New option, then the Logic option, then the Structured Text Program option. A new ST program database item is added to the hierarchy. It is selected automatically, ready for you to define its name.

3. Enter a suitable name for the ST program then press the Enter key or select another part of the interface to confirm.

4. You have now created the ST program database item. To create your ST program, you will need to edit it (see Edit an ST Program, on page 32).31PD-6017 07/2012

Chapter 4 - ST ProgramsEdit an ST Program

To enter the code for an ST program, you need to edit as ST Program database item. During the editing process, you will enter the code that defines the behavior that is to be provided by the program, for example, you could enter the code that allows the ST program to perform a calculation. When you save the code, the program you have created is stored in the ST Program database item.

To edit an ST program:

In the Database Bar, either double-click on an ST program item or right-click on it and select the Edit option from the context sensitive menu. The ST program is displayed in Design mode. You can only edit an ST program in Design mode.

The main display area of the ST program editor shows the ST program. Each ST program has PROGRAM , ;, and END_PROGRAM by default as ST programs require these attributes. You will define the Logic of your ST program between PROGRAM and END_PROGRAM.

At the bottom of the ST program editor is a smaller frame. This frame is the compiler. ClearSCADA displays diagnostic information in this section.

Enter your ST program code in the editor.

Diagnostic information is shown in the Compiler.32 PD-6017 07/2012

Chapter 4 - ST ProgramsTo code an ST program, you will need an understanding of the Structured Text language. We explain some of the basic principles of the ST language in the following sections, but you may need to broaden your knowledge by referring to a Third Party source:

Understanding the Basic Structure of an ST Program (see page 34)

Entering a Comment (see page 40)

Internal Variables (see page 40)

Direct Variables (see page 43)

Indirect Variables (see page 52)

Constants (see page 57)

Setting the Default Values (see page 87)

Built-In Data Types (see page 63)

Derived Data Types (see page 72)

Executing Methods on Database Items (see page 90)

Controlling the Flow of the Program (see page 100)

Using an ST Program to Call an SQL Query (see page 112)

Inserting, Updating, and Deleting Values by Using SQL in an ST Program (see page 116)

Passing Multiple Parameters into an SQL Query in an ST Program (see page 119)

Function Blocks in ST Programs (see page 121)

Using Libraries in ST Programs (see page 121).

The following sections explain how to check that your ST program is coded correctly:


Debugging an ST Program or ST Library (see page 124)

Viewing the Variables in your ST Program (see page 127).

The following section explains how to configure your ST program (including how to define when the program is executed):

Logic Program Properties and Values (see page 359).33PD-6017 07/2012

Chapter 4 - ST ProgramsUnderstanding the Basic Structure of an ST Program

Before you begin to create your own ST programs, you need to be aware of the basic structure of an ST program.

1. The start of the program.

ST programs begin with a PROGRAM keyword and a program name. This is followed by a VAR keyword and a list of variables.

2. The variable blocks.

There are 2 types of VAR blockVAR blocks for internal variables and VAR blocks for direct and indirect variables. Variables of different types have to be defined in separate blocks.

For internal variables, the VAR block will begin with a VAR keyword. The variables are defined after the VAR keyword and use the format:

: ;

For direct and indirect variables, the VAR block will also begin with a VAR keyword. The variables are defined after the VAR keyword and use this format:

(.) : ;

For example:

VAR

Desc AT %I(.Valve.Position.CurrentStateDesc) : STRING;END_VAR

Each VAR block is ended by an END_VAR keyword.

When you are using variables, you need to:

i. Define the type for any arguments

ii. Separate each argument type with a comma, for example, STRING, BYTE,STRING; means there are 3 arguments, the first is a string, the second is a byte, and the final argument is a string.

iii. Use VAR INPUT definitions to allow the ST program to receive inputs from a user/another ST program. The VAR INPUT keyword needs to be included in the recipient program (so, if one ST program receives the inputs for its indirect variables from another program, the program that receives the inputs has to have VAR INPUTS). 34 PD-6017 07/2012

Chapter 4 - ST Programsiv. Define the VAR INPUTS in the same order in which they are to be executed.

To allow a program to use the values from another program, the arguments for the indirect variables inputs have to be in the same order in both programs. For example, Program 1 defines a method that has outputs in this order: STRING, BYTE. These values are output to Program 2. In Program 2, the VAR INPUT definition has to define that the first argument is a STRING and the second argument is a BYTE as this is the order defined in Program 1.

v. Set the Interval to 0s on the ST Program Form for the recipient ST program. Programs that use manually entered input values or input values from other programs cannot be executed on an interval basis. However, they can be executed by another program (the other program executes the recipient ST program at a regular interval), according to a schedule, and manually. If required, configure a schedule to execute the program at specific times (see Using Schedules to Automate Regular Functions, on page 447 in the ClearSCADA Guide to Core Configuration).

If you execute a recipient ST program manually, you will be prompted to enter the input value. You need to enter the input value in the dialog box and select the OK button to proceed. You will only be prompted to enter a value if the recipient program has inputs defined, but the inputs are not associated with other programs.

3. The method block.

If an ST program uses methods, the methods are defined in a METHOD block. The METHOD block has to follow the VAR block(s) and also come before the ST code for the program. If the ST program does not use methods, there is no METHOD block and the ST code for the program follows the last VAR block.

The METHOD block begins with a METHOD keyword. The methods that the program uses are listed and use this format:

(.) : ;

For example:

METHOD

OVR AT %M(AIs.AnalogInp.Override) : LREAL;END_METHOD

The METHOD block is ended by an END_METHOD keyword.

4. The ST code for the program. This can include statements, expressions, and operators.

5. The end of the program.

Each ST program is ended with the END_PROGRAM keyword.

In the following basic example, the ST program contains 3 variables and 3 methods. ST programs can contain as many variables and methods as required.

For the example, entries in angle brackets < > indicate a name or type that you have to enter for the program. These will vary depending on the items you want to reference and the names you want to use. You should not enter the angle brackets in your ST programswe use them here to indicate that you need to specify a name, location, or data type that will vary according to your needs. 35PD-6017 07/2012

Chapter 4 - ST ProgramsPROGRAM

VAR

: ;

: ;

: ;

END_VAR

METHOD

AT %M(.) : ;

AT %M(.) : ;

AT %M(.) : ;

END_METHOD

;;;

END_PROGRAM

The ST program begins with a PROGRAM definition and the program name. This is followed by a VAR definition, and the names and types of the variables that are used by the program. The list of variables is referred to as a VAR block, and it is ended by an END_VAR definition.

If the ST program uses methods, a METHOD block is defined after the VAR block. The METHOD block consists of the METHOD keyword followed by the name of a method, an instruction, the location and name of the item to which the method will be applied, the name of the method to be applied, and the argument types that will be used (argument types are types of data for specific settings, for example, the Override method needs an argument type that specifies the type of value for the override value). The METHOD block is ended with an END_METHOD keyword.

The ST code that defines the behavior that the program provides is entered after the METHOD block (or after the VAR block if there is no METHOD block).

The program is ended by the END_PROGRAM keyword.

NOTE: Constants also need separate VAR blockssee Constants, on page 57.36 PD-6017 07/2012

Chapter 4 - ST ProgramsStatements, Expressions and Operators

You need to use Structured Text statements, expressions, and operators to define the instructions, calculations, and relationships for each ST program.

The types of operators and expressions that you use in your ST program affects the order in which the expressions are evaluated.

For more information, refer to the following sections:

Statements (see page 37)

Expressions (see page 38)

Operators (see page 39).

Statements

Statements are used to provide an instruction, such as assign a variable. They can contain expressions (which are calculations). The basic format for a statement is:

:= ;

Where the is a calculation that produces a new value for when the statement is evaluated.

Examples:

This statement defines the value of a variable named 'FlowRate'. It defines a constant value (also known as a literal value):

FlowRate:= 64.5;

The next statement defines a basic expression that can be used to increase a value by a defined amount:

Count:= Count + 1;

The value for the Count variable increases by 1 each time the statement is evaluated.

These are simple examples of statements. You can create much more complicated statements, including statements with nested expressions. 37PD-6017 07/2012

Chapter 4 - ST ProgramsExpressions

Expressions are calculations or evaluations that are defined within Statements (see page 37). They can use one or more operators, functions, and variables.

Each ST expression produces a value which can be wither a built-in data type (see Built-In Data Types, on page 63) or a derived data type (see Derived Data Types, on page 72). These values can be used within a program or can be written to items in the database.

An expression can be simple or complex. A simple expression includes a single calculation, for example:

y + 10

or a Boolean expression such as:

x = y

A complex expression contains several calculations that are used to produce a value, for example:

(x + y) * 2

Expressions are evaluated in order. The precedence of the operators and other expressions in the statement determines when an expression is evaluated. Expressions are evaluated in this order:

1. Parenthesized expressions, such as:

(x + y) * 2

2. Function calls, such as:

COS(x)

Where COS is the function being called, and x is the argument.

Within this order, operators are evaluated in precedence order (see Operators, on page 39). For example, a parenthesized expression with negation will be evaluated before a parenthesized expression with inequality.

NOTE: For Boolean operators, the expression is evaluated up to the part of the statement at which the value can be determined.38 PD-6017 07/2012

Chapter 4 - ST ProgramsOperators

Operators are the calculations and conditions that are used to define the behavior that is provided by a Logic program. Each operator provides a specific calculation or comparison, for example, the > operator means 'greater than' and the < operator means 'less than'. They can be used in an expression that compares values like this:

IF Value1 > 50 THEN

Value2 := 10;ELSIF Value1 < 50 THEN

Value2 := 5;END_IF;

In this expression, if Value1 is greater than 50, then Value2 is 10. If Value1 is less than 50, then Value2 is 5.

Each operator has a precedence level. This determines the order in which the operations are evaluated.

The following table shows the available operators and their precedence:

Operator Description Precedence Level

( ) Expression inside parentheses ( )

1 (Highest)

Function () Parameter list of a function or function evaluation

2

** Exponentiation 3

- Negation 4

NOT Value with opposite sign 4

* Multiplication 5

/ Division 5

MOD Modulus operation 5

+ Addition 6

- Subtraction 6

< Less than 7

> Greater than 7

= Greater than or equal to 7

= Equality 8

Inequality 8

AND, & Boolean AND 9

XOR Boolean exclusive OR 10

OR Boolean OR 11 (Lowest)39PD-6017 07/2012

Chapter 4 - ST ProgramsEntering a Comment

Comments are notes that you can add to your ST program. They are useful as they allow you to annotate your code with descriptions etc.

Comments are optional and have no effect on the program. Typically, they are used to explain the structure and purpose of sections of ST code to other users.

To enter a comment in your ST program, you need to use the following format:

(* *)For example:

(* This calculation is used to increase the count each time the input is greater than 50*)

Internal Variables

Each type of Logic program can contain internal variables. These are values that are used by the program but are not written to an item in the database. They are used for:

Conversions

Separating long, complex calculations into smaller sets of calculations

Storing program states.

Unlike direct variables, internal variables are not stored in the database. This means that if the program or the server is reset, the internal variables will reset to their default value (you can stop internal variables from resetting by using the RETAIN keyword, as explained later in this section). As internal variables are not stored, they are not transferred to any standby servers (again, this can be avoided by using the RETAIN keyword).

Internal variables are stored internally so that Logic programs can maintain the internal variables for each execution. For example, if an internal variable is used as a count, the previous value needs to be stored so that the program can use it to determine the next value.

NOTE: Internal variables need to be separated from direct variables, constants and function blocks in the VAR lists. This means that if you have a program that uses constants, internal variables, direct variables, and function blocks, you will have at least 4 VAR lists1 for constants, 1 for internal variables, 1 for direct variables, and 1 for function blocks.

For information on adding internal variables or using the RETAIN keyword, please refer to the relevant sections:

Adding an Internal Variable to an ST Program (see page 41)

Using the RETAIN Keyword in an ST Program (see page 42).40 PD-6017 07/2012

Chapter 4 - ST ProgramsAdding an Internal Variable to an ST Program

To add an internal variable to an ST program, you need to define the internal variable in a VAR list. You can then use the internal variable throughout the ST program.

You have to define internal variables in the following format:

VAR

: ;END_VAR

Where is the name you allocate to the internal variable, and is the data type of the internal variable (see Built-In Data Types, on page 63 and see Derived Data Types, on page 72).

You can then refer to the internal variable by name in your ST program. For example:

VAR

TimeCount:TIME;END_VAR

VAR

TimedStart AT %M(.Power.StartMotor.CurrentState):BOOL;END_VAR

IF TimeCount > T#60s THENTimedStart := TRUE;

ELSE

TimedStart := FALSE;END_IF;

This program uses an internal variable to act as a timer. When the timer exceeds 60, the state of a direct variable (TimedStart) changes from FALSE to TRUE.

The internal variable is defined in a separate VAR list to the direct variable. This is because internal variables and direct variables cannot be listed in the same variables list. To overcome this, you need to create multiple VAR lists. Each VAR list needs to be structured in the same way as any other VAR list except that the END_VAR only has a semi-colon at the end of the final VAR list.

For more information on data types such as BOOL, please refer to Built-In Data Types (see page 63). You can also create custom data types that allow you to group internal variables and define meaningful names for value types (see Derived Data Types, on page 72).

For information on Logic keywords that you can use to control the behavior of the program, such as IF and THEN see Controlling the Flow of the Program, on page 100.41PD-6017 07/2012

Chapter 4 - ST ProgramsUsing the RETAIN Keyword in an ST Program

Normally, internal variables are not stored for use after the program or server has been reset. Similarly, they are not transferred to any standby servers.

However, it is possible to store internal values so that:

They are not reset to their initial values when the server or program is reset

They are transferred to any standby servers.

To do this, you need to use a RETAIN keyword. The RETAIN keyword instructs the program to store the internal variable so that it can transferred and used after a reset.

In ST programs, you need to use the following format to retain the internal variables:

VAR RETAIN

:;END_VAR

For example:

VAR RETAIN

TempConversion: INT;END_VAR

Where TempConversion is the name of the internal variable and INT is the type of value that it represents (an integer).42 PD-6017 07/2012

Chapter 4 - ST ProgramsDirect Variables

Direct variables are values that are read from (or written to) items in the ClearSCADA database. You need to reference direct variables in your Logic programs to allow them to react to values in the database and apply changes to values in the database.

There are several ways of accessing direct variables in your ST programs. The most effective type of access for you to use varies according to what you need to achieve.

Usually, if you need your Logic program to read values from the database or write values to the database, you will use a:

Variables List (see Using the VAR List to Access Direct Variables, on page 44).

However, there are some situations in which using an alternative way of accessing the direct variables is more effective:

If you need to prevent your ST program from using values stored in the cache, you may need to use a VAR list in conjunction with the NOCACHE keyword. For example, you will need to use the NOCACHE keyword if your ST program has values that accumulate with each execution of the program (see Using VAR NOCACHE to Prevent Cached Values Being Used in an ST Program, on page 46).

If you need your ST program to reference the same properties for a large number of database items of the same type, you should use a Database Object Structure (see Using Database Object Structures to Access Direct Variables, on page 48).By using a Database Object Structure, you can reduce the amount of time and effort required to create the references to the database.

If you need your ST program to access multiple database items that meet certain criteria (but are not named explicitly in the program), you should use an SQL Query to access the database. The SQL Query can be included within your ST program (see Using SQL Queries to Access Direct Variables, on page 50).

If you need your ST program to read values from, or write values to an array, you need to use Vectors to access the direct variables (see Using Vectors to Access Direct Variables, on page 51).

If you need to access historic values, please refer to Historic Values in ST Programs (see page 58).43PD-6017 07/2012

Chapter 4 - ST ProgramsUsing the VAR List to Access Direct Variables

For ST programs, you need to define direct variables in a VAR variables list. The variables list comes after the PROGRAM keyword and uses this syntax:

VAR

AT : ;END_VAR

For example:

VAR

Input AT %I(..TemperatureSensor.CurrentValueFormatted): STRING;END_VAR;

In this example, the variable value is a read only value (indicated by %I). It is read from the CurrentValueFormatted tag of the TemperatureSensor database item. The reference to the TemperatureSensor item is relativethe two periods indicate the levels in the hierarchy.

The %I code is used to indicate that the variable is read only. Read Only is one of three possible access types for variables:

When you reference a database item in a Structured Text program, you can specify a field or leave the program to reference the default field for the database item. For example, if you do not specify a field for a point, the CurrentValueFormatted field is referenced.

You can specify which field is referenced by adding the name of the required field to the end of the item's path. You have to place a period between the end of the path and the name of the field, for example:

Desc AT %I(.Valve.Position.CurrentStateDesc) :STRING;In this example, the CurrentStateDesc field is referenced and is used for a read-only string value.

NOTE: Direct variables need to be separated from internal variables, constants and function blocks in the VAR lists.

For more information on data types such as STRING, please refer to Built-In Data Types (see page 63). You can also create custom data types that allow you to define meaningful names for value types (see Derived Data Types, on page 72).

For information on Logic keywords that you can use to control the behavior of the program, such as IF and THEN see Controlling the Flow of the Program, on page 100.

Characters Access Type

%I Read Only

%Q Write Only

%M Read and Write44 PD-6017 07/2012

Chapter 4 - ST ProgramsExample: Reading a Point Value and Writing it to Another Point

In this example, an ST program is used to read the current value of a point named 'TemperatureSensor1'. The value that is read is then written to the current value of a point named TemperatureSensor2'.

PROGRAM ReadTempWriteTemp

VAR

Input AT %I(TemperatureSensor1.CurrentValue): INT;

Output AT %M(TemperatureSensor2.CurrentValue): INT;

END_VAR;

Output:=Input;

END_PROGRAM

The %I is used to read a value from the database and %M is used to write a value to the database (%M can be used to both read and write). 45PD-6017 07/2012

Chapter 4 - ST ProgramsUsing VAR NOCACHE to Prevent Cached Values Being Used in an ST Program

You can use the NOCACHE keyword in your Logic programs to prevent the program from using a cached value. This is required when you need a value to accumulate each time a program executes, for example, when a total count value needs to increase when an input value changes.

If the NOCACHE keyword is not used, the ST program will use the value that was in place when the program first executed. This means that when a series of values are reported for one of the ST program's inputs, the value of the variable that is affected by the inputs will be the same. In the example below, the NOCACHE keyword is used to prevent the program from calculating the Total value as 0.0 + the current value of the Value variable. So, if the program receives 10 values for the Value variable, the program will use the default value of 0.0 for the Total value on the first execution, but will not use 0.0 on subsequent executions. If the NOCACHE keyword was not used, the program would use the 0.0 value for the Total value for each execution.

Example:

PROGRAM TotalValues

VAR

FirstTime:BOOL := TRUE;END_VAR

VAR

Value AT %M(Input Point Value): REAL;END_VAR

VAR NOCACHE

Total AT %M(Total Point): REAL;END_VAR;

IF FirstTime THENTotal := 0.0;FirstTime := FALSE;

END_IF;

Total := Total+Value;END_PROGRAM

In this example, the FirstTime value is a Boolean value (true/false) that is used to define whether the program is being executed for the first time. By default, it is set to TRUE.

The Value variable is a real value that the program reads from the Input Point Value database item.

The Total value is a NOCACHE value (it is not cached and is retrieved each time the program executes). The Total value is a real value that is calculated by the program each time it executes. The result of the calculation is written to the Total Point database item.

The If statement determines whether the Total value is 0 or is another value. If the FirstTime value is TRUE then the Total value is 0.0 (the FirstTime value is only TRUE the first time that the program executes). If the FirstTime value is FALSE, the FALSE value is maintained and the Total value is the current Total value + the value of the Value variable.46 PD-6017 07/2012

Chapter 4 - ST ProgramsThis means that the first time the program executes, the Total value is 0.0. Before the first execution of the program completes, it sets the FirstTime value to FALSE so that the next execution of the program will cause the Total value to change from 0.0. At the end of the first execution of the program, the Total value is set to the same value as the Value variable (Total=0.0 + Value = Same value as Value variable).

On subsequent executions of the program, the FirstTime value will be FALSE and so the Total will be the current Total value + the value of the Value variable. The program will not use 0.0 as the Total value each time, as the 0.0 is not cached.

To define a NOCACHE value, you have to create a separate VAR list for the values to which the NOCACHE feature applies. The VAR list has to be started as VAR NOCACHE. The values need to be entered beneath the VAR NOCACHE definition in the same way as with normal VAR lists, and the VAR list needs to be closed with END_VAR.47PD-6017 07/2012

Chapter 4 - ST ProgramsUsing Database Object Structures to Access Direct Variables

When using direct variables, you need to declare the variables that are used by the Logic program. The variables have to be declared in VAR blocks. This can be time-consuming if the Logic program needs to reference the same set of properties for many different items of the same type.

ClearSCADA provides a structure for referencing multiple fields of a single database item. The structure is called a database object structure, and it allows you to group a set of fields for a type of item. The structure is included at the top of the Logic program and can be referenced within the program. This means that you can reference the name of the structure instead of referencing multiple fields several times in the same program.

For example, if your ST program references the CurrentValueFormatted, CurrentState, and QualityStateDesc of 30 points, you would have to enter the variables for each separate point. This means you would have to define the CurrentValueFormatted, CurrentState, and QualityStateDesc variables 30 times (each field for each point).

By using a database object structure, you can create a single reference to the CurrentValueFormatted, CurrentState, and QualityStateDesc fields. The database object structure includes the specified fields in the relevant class (in this case, the CDBPoint class). This means that the same database object structure can be used to reference the specified fields for any item in the classit can be used for any point.

Example:

A Logic program needs to reference the CurrentValueFormatted, HighLimit, CurrentState and CurrentStateDesc fields of a 20 different points. If the database object structure is not used, you will have to add these fields to the program (for each of the 20 points).

The following database object structure is used:

TYPE

PointValues : DATABASE_OBJECT(CDBPOINT)CurrentValueFormatted: LREAL;CurrentState: BOOL;

QualityStateDesc: STRING;END_DATABASE_OBJECT;

END_TYPE

By using the database object structure, the fields are grouped at the top of the program. The database object structure is allocated a name (PointValues). Where the program needs to refer to the fields, the name of the database object structure and the specific point is used. This means that the database object structure can be used to refer to the same specified fields for multiple points.

In the program, references to the point values use this format:

AT %M() : ;48 PD-6017 07/2012

Chapter 4 - ST ProgramsFor example:

InputVal AT %M(.Group 1.LimitPoint) : PointValues.CurrentValueFormatted;

Where InputVal is the name of the variable, and AT %M indicates that the value is a read/write value. (Group 1.LimitPoint) specifies the location of the point that is being referenced (the 'LimitPoint' that is stored in the 'Group 1' Group). PointValues is the name of the database object structure, and .CurrentValueFormatted is the specific field that needs to be referenced.

This means that each point value can be referenced by a single line. The VAR list only needs to contain the database object structure and one set of the fields that are to be includedthere is no need to reference each field for each item.

When you create a database object structure, you need to adhere to these rules:

The database object structure has to be specified within a TYPE definition.

The TYPE definition has to be positioned at the top of the ST program, above the PROGRAM information.

The name of the database object structure is the first part of the definition. It is followed by DATABASE_OBJECT () where is the name of the class of database items.

You can view the classes of database items by using the ClearSCADA database schema (see Working with the Database Schema, on page 19 in the ClearSCADA Guide to the Database).

The list of referenced fields has to include field names that are identical to the field names in the database. Each field name has to be followed by its data type.

NOTE: When using an SQL Query with a DATABASE_OBJECT structure, you have to include the Id column as the first column in the SQL Query. This is because DATABASE_OBJECT structures have an Id field, although this field is not referenced in the DATABASE_OBJECT definition.

To end the list of fields, you have to enter END_DATABASE_OBJECT; To end the TYPE definition, you must enter END_TYPE.

The Logic program has to be entered after END_TYPE

NOTE: You cannot access database aggregates via DATABASE_OBJECT structures. You need to use standard read/write declarations to access database aggregates.49PD-6017 07/2012

Chapter 4 - ST ProgramsUsing SQL Queries to Access Direct Variables

You can use SQL Queries in your ST programs to access the ClearSCADA database.

NOTE: SQL Queries can only be used in ST programs to access the ClearSCADA database. They cannot be used to access other databases.

ClearSCADA includes an extension to the IEC-1131 standard that allows you to use Structured Query Language (SQL) to query the ClearSCADA database. When you use an SQL Query in an ST Program, the SQL Query has to request data for the values specified in the STRUCT data structure or DATABASE_OBJECT structure (to which the values from the resultset are passed). This means that the data types specified in your STRUCT or DATABASE_OBJECT structures have to match the data types of the columns in your SQL query. When using DATABASE_OBJECT structures, the names of the values in the DATABASE_OBJECT also have to match the names of the columns in the SQL query.

When you use an SQL query to provide values for a STRUCT data structure, the values from the SQL query's resultset can only be read. STRUCT data structures cannot be used for writing to the database or calling methods. The names of the values defined in the STRUCT data structure can be anything you choose, but the data types of the values have to match the data types of the columns in your SQL query.

You can use an SQL query and a DATABASE_OBJECT structure to read the values in the resultset, write new values to the database objects represented by the rows in the resultset, and access the methods for the objects represented by the rows in the resultset. This is possible as each row of values returned for a DATABASE_OBJECT structure represent the values of a specific item in the database.

The values and value types of the DATABASE_OBJECT structure have to match the column names and value types defined in the SQL query (including the Id column which is automatically added to DATABASE_OBJECT structures).

Typically, you will use DATABASE_OBJECT structures with SQL queries more often than STRUCT data structures, as DATABASE_OBJECT structures allow for greater interaction with the database.

Further Information

STRUCT data structures: Using Structured Data Types to Group Internal Values (see page 73).

DATABASE_OBJECT structures: see Using Database Object Structures to Access Direct Variables (see page 48).

Using an ST Program to Call an SQL Query (see page 112).

Inserting, Updating, and Deleting Values by Using SQL in an ST Program (see page 116).50 PD-6017 07/2012

Chapter 4 - ST ProgramsUsing Vectors to Access Direct Variables

You can use vectors to read from and write to array fields in the ClearSCADA database. Vectors are similar to arrays in that they can contain multiple values, but they also have a Length and Capacity that mean they can be used to only read or write a specific number of values.

For more information, see Vectors, on page 81.51PD-6017 07/2012

Chapter 4 - ST ProgramsIndirect Variables

Indirect variables are a ClearSCADA specific extension to the IEC 1131-3 language. They allow an ST Program to perform calculations on tags that are specified at runtime as opposed to hard coded tags that are used at compile time. At runtime, the program will either prompt the user to enter a string (the string is the tag of an item in th