Scripting Fundamentals (Hello World!)

The VTScada programming language lies behind nearly everything that you see in an application. There are many reasons to learn this language, including:

  • To fix damaged pages or widgets.
  • Create a custom configuration panel (properties dialog) for your user-defined tag types.
  • Create new ways to display information.
  • Create new types of report.
  • Create new functions, device drivers, services...

Briefly, code is kept in units called "modules". (Refer to Module Structure for a detailed description of what follows here.) For example, every VTScada page is a module, with each stored in a separate file on disk. So is every tag type, every widget template, every file that ends with the extension ".SRC". Those source code files are compiled into ".RUN" files before being used by VTScada.

The executable code within a module is written as a series of statements. Every statement must end with a semicolon. A single statement may continue over several lines in the source code file and may include many expressions as well as comments.

Here is how to write "Hello World!" using a single statement that represents text created using the Idea Studio:

GUIText(144, 151, 304, 131,
        1, 1, 1, 1, 1 { Scaling              },
        0, 0          { Movement             },
        1, PickValid(\ScaleDisplayContent, 0) { Vis., Font Scaling },
        0, 0, 0       { Selectability        },
        Brush("<00000000>", 0, 1), Pen("<FF000000>", 1, 1),
        Scope(VTSDB, "LabelFont", TRUE)\Value,
        3, 4,
        "%s",
        "Hello World!");

Statements must be placed in a named block called a "State". VTScada uses state-based logic, meaning that while one state is active (the pump is stopped) a certain set of statements run. When the state changes (the pump starts), a different set of statements run. Navigating from one tab to another in a configuration dialog is also an example of changing states.

Comments

Comments are enclosed in braces {curly brackets}. If inserting a comment within a statement, it is standard practice to keep it near to the variable or parameter to which it refers, placing any punctuation that divides one parameter from the next after the comment. For example, here is an example of variable declarations taken from a typical script application. Note that the semicolon is placed after the comment.

  System        { Provides access to system library functions };
  Layer         { Provides access to the application layer    };

Where to write code

This depends on the purpose for your code. Expressions, which are fragments of script code, can be added to tag and widget parameters while working inside the VTScada user interface. New code is often added to old code to extend an existing feature. For example, if you are building a new report, driver or service, you will create a new text file and put your code there. If you want to add new features directly to a page, or a widget, you would open the matching .SRC file and start typing, although take note that the code you add might not be compatible with the Idea Studio.

To ensure compatibility, ensure that your editor is set to save using UTF-8 encoding.

When creating new modules, you must declare them in the application's AppRoot.SRC file. If you are creating a new stand-alone utility, you might create a script application and write code in its AppRoot.SRC file.

Some of the examples in the following pages show code being added to a page (Overview.SRC) in a standard application.
Do not assume from this that pages are the natural home for all new code. When an operator closes a page, all code within it stops. If you are creating something that should run continuously while the application runs, do not put your code in a page.
The examples are designed to illustrate concepts as simply as possibly.

Hello World

(Do not experiment within a production application.)

  1. Using a text editor, find and open the file Overview.SRC, within your application's folder.
    (C:\VTScada\YourApplication\Pages\Overview.SRC)
  2. At the first line below Main [ add the following:
ZText(400, 100, "Hello World!", 3, 0);

Detail from Overview.SRC after adding step 2

  1. Save the file.
  2. In the VAM, click the Import File Changes tool for the application.
    If a prompt notifies you of a syntax error, repair it and try again.
    Always close the error dialog between attempts, otherwise older errors will continue to be shown after being fixed.
  3. Run the application and open the Overview page. The greeting should be displayed.
  4. Take a moment now to read the description of ZText.
    These notes could describe the parameters of the function, but that won't help you learn this language nearly as well as developing the habit of turning to the function reference.

ZText or GUIText? The Z-functions are fine when learning the language because they're simple to write. But when developing applications, you are advised to use the newer GUI-functions, which are compatible with the Idea Studio and far more powerful.