Resources, Terms, Definitions

In addition to this reference guide, the following resources are available to help you learn to write VTScada script code:

• F1 integration and syntax highlighting are features that you should look for when selecting an editor. For example, several editors allow you to link to an external CHM help file.
  A .CHM format version of the VTScada documentation is available from Trihedral by request. With this feature configured, you can highlight any word and press F1 to open the reference notes for that word. (So long as the word is found in the index.)
  
• The ability to refer to working source files for examples. Several example modules are provided for use with the VTScada scripting course.

Terms and Definitions

Comment

ZPipe(x[0], y[0] { First endpoint for pipe },
      8 { Number of vertices },
      176, 239 { Very dark gray to very light gray },
      24 { Width of pipe in pixels });

Variable, Constant

In simple terms, a variable is a named location in your PC's memory where a value can be stored. The term "variable" is used, as the value stored in the named storage location can change over time (i.e. the stored value is variable or changing).

A "constant" is exactly the same thing as a variable, except that it is defined in a way such that, after being set, it cannot be changed by later code.

Variable names can be up to 256 characters in length to allow descriptive labeling of the information that they contain. In earlier versions of VTScada, there was a limit of 16,384 variables in any given module. The limit is currently 4,194,304 variables per module.

All of the data in VTScada is stored in variables. Data values come in a variety of different types, the most common being numbers and text. VTScada also uses many other data types such as Boolean values, pointers, streams, objects and graphic values. A variable can also represent an entire collection of values stored as an array or as a dictionary.

An example showing values being assigned to variables is displayed below:

Title = "Station 009";
Color = 15;

In the preceding example, the variables specify the text and background color for a system page.

Unlike many programming languages, VTScada variables are not declared to have a specific data type. The data type is associated with the value stored by the variable so that the type can change as the value changes. This feature is called "dynamic typing". This allows you to create programs that are flexible and can simplify object-oriented coding. In a static programming language, a programmer must declare the type of each variable before compiling the code, thus making the code less flexible. The benefit of dynamic typing is that there is no need to deal with data whose type cannot be determined at compile time.

To use the value contained in a variable in a statement, you simply need to provide the name of the variable. VTScada also supports references to variables (pointers), but more about that later.

Expression

An expression is a unit of code that can produce a value. You can use the word expression to mean a statement, or a sub-unit of code within a statement. 2 + 2 is an expression.

Expressions can be created with the user-interface tools of VTScada for tag configuration parameters, the properties of graphic objects, the title of a page and more.

Statement

A statement is a command that signals VTScada to perform an action in an application, such as drawing graphics, doing mathematical functions, communicating, raising an alarm, logging data or trending. Statements are not used for tag configuration parameters, or the properties of graphic objects. They are written using a text editor when changing the code for a page, a widget, or a custom tag.

A simple statement might look like:

A = 5;

This statement sets the value of the variable "A" to "5".

Other statements have the form:

Beep(1000);

This statement passes the "Beep" function a parameter value of 1000, thereby generating a 1000 Hz tone in the internal speaker of the computer.

Statements always end with a semi-colon. They need not be written on a single line. For example, the following are two perfectly valid statements:

A = {setting the value of "A" … }
5   { … to five. };

GUIRectangle(236, 180, 280, 236,
             1, 1, 1, 1, 1 { Scaling },
             0, 0 { Movement },
             1, 0 { Visibility, scaling },
             0, 0, 0 { Selectability },
             Brush(0, 0, 1), Pen(0, 1, 1));

State

A state is a collection of statements that are grouped together within square brackets and given a name. The following is an example of a state named "Main" taken from the code for a page. When you are viewing the page, you are "in" that state.

Main [
  GUIRectangle(236, 180, 280, 236, 
               1, 1, 1, 1, 1 { Scaling }, 
               0, 0 { Movement }, 
               1, 0 { Visibility, scaling }, 
               0, 0, 0 { Selectability }, 
               Brush(0, 0, 1), Pen(0, 1, 1)); 
  GUITransform(232, 236, 288, 180, 
               1, 1, 1, 1, 1 { Scaling }, 
               0, 0 { Movement }, 
               1, 0 { Visibility, scaling }, 
               0, 0, 0 { Selectability }, 
               Variable("AI20_1")\TopBar(222, 0, 100)); 
  Return(Self); 
  GUITransform(164, 256, 336, 168, 
               1, 1, 1, 1, 1 { Scaling }, 
               0, 0 { Movement }, 
               1, 0 { Visibility, scaling }, 
               0, 0, 0 { Selectability }, 
               Variable("Library")\Bitmap(
               "Bitmaps\Tanks\Tank06.bmp", -1)); 
]

This particular state draws a rectangle, an analog input tag as a Top Bar, and a bitmap of a tank on a system page.

It is important to note that the order of the statements in a state does not imply the order in which they are executed. When a state becomes active, all statements within it are executed exactly once. If a value within a statement changes, that one statement will run again. For example, a tag's value increases and in response, the widget displaying that tag updates to show the new value. While the state is running (the page is visible or the pump is in a running state) all statements in a state can execute as needed in response to changing values. When the state stops running (the page is closed or the pump is stopped) those statements do not run.

Steady State

All statements within a state remain active as long as the state is active. Whenever an included variable's value changes, all statements within the state that use this variable will be re-evaluated. This condition is referred to as being in "steady state".

Because statements run only when triggered by a changing value, their order within the state generally does not matter. The order of statements in a state is significant only for pages, where the visual layering of images matches the order of the statements. Do not attempt to force an order on statement execution within a state - it's meant to work this way. However, it does take some care: X = X + 1; is effectively an infinite loop in steady state. (Each time the value of X changes, the statement containing that variable runs again.)

The statements within the state are referred to as "steady state statements". This is an important distinction when referring to VTScada's extensive function library. Many functions can only be used in steady state, while others cannot ever be used in this mode.

Note that all functions that can be used in Steady State can also be used in a tag expression, although many are not useful there.

Script Blocks

A script block is a collection of statements that are executed in order from first to last (or according to loops and conditions) and do not re-evaluate when variables referenced in the statement change. This is in contrast to statements in steady-state. In a script block, X = X + 1; just adds 1 to the value of X.

Scripts are created by enclosing a set of statements within a "script block" (indicated by square brackets) that in turn are preceded by an If statement. The If statement and the logical expression that it evaluates, serve as the trigger for the script. When the logical condition evaluated by the If statement becomes true, the statements with the script block will be executed once, in order as they are written.

If test_expression; { This line is called the action statement. }
    { The action statement triggers the script when the test    }
    { expression is true                                        }
[              { The square bracket marks the script beginning }
  Statement 1; { The statements with the brackets are referred }
  Statement 2; {   to as the script statements.                }
  Statement 3;
]              { This bracket marks the script end.            }

If the test expression is still true when the last statement within the script is evaluated, and if there is no provision to transfer execution to another state, then the script will run again. Take care to ensure that you do not create a continuously repeating loop. There are two ways to stop the script from repeating:

• Ensure that one of the statements within the script updates the conditions of the test expression so that it will become false.
• Provide for a state change by adding the name of another state to the action statement that triggers the script. When the script completes, execution passes to the named state.

Script blocks are found within states. The following example shows a typical state structure:

Main [
  Steady state statement;         { active while Main is active }
  Another steady state statement; { active while Main is active } If <test_expression>  State2;  { active while Main is active }
  [  { this block active only when test_expression becomes true }
     Script statement 1;   
     Script statement 1;  { last statement of the script.       }
  ]                       {  end of script section.   }
  Another steady state statement; { also active, just like the  }
                                 { ones before the script block }
]
State2 [
  Another steady state statement; { active if State2 is active }
  Another steady state statement; { active if State2 is active }
]

Execution begins with state Main active. All statements within it, including the one beginning with If are in Steady State and therefore are active as long as Main is active.

When the test expression becomes true, the script statements run in order. Because the script's action statement ends with another state name (State2), control transfers from Main to State2 when the script finishes.

The statements within a script are referred to as "script statements". This is an important distinction when referring to VTScada's extensive function library. Many functions can only be used in a script, while others can only be used in steady state.

Note also that functions that can only be used in a script cannot be used in a tag expression.

Module

A module is a collection of states, variables declarations, parameters (if needed) and possibly, other modules. Modules are separate tasks that are run simultaneously in the system. Similar to a class in other programming languages.

Any given module may be run any number of times (limited only by system resources). Each running copy of a module is called an instance, and has its own set of variables and conditions. Each instance of a module runs independently of all others. For example, every I/O tag in your application is a separate instance of the module that defines how an I/O tag works.

When designing a system, it may be helpful to assign each physical entity of the system to a particular module, and to make the states of that module correspond with the physical entity's actual physical state. For example, your system might have a module called Turbine, with four states, SpoolingUp, SpoolingDown, Running and Stopped. Physical entities composed of other smaller objects may be represented by a module that contains other modules inside of it, such as a module called Pump that has two child modules called Valve and Motor. Between child and parent modules, there exists a powerful relationship known as inheritance, whereby child modules may share some or all aspects of their parent's character, such as variables, or characteristics that the parent module has inherited from its parent. The concept of inheritance applies to all ancestors of a module, not simply its immediate parent.