Store and Declare Modules

Modules are stored in text files, each ending with the extension ".SRC". As part of compilation, a .RUN file will be created for each .SRC file.

The most important module file is AppRoot.SRC. A file with this name will exist in every VTScada application. In script applications, AppRoot can (and often does) contain executable code. In a standard application, AppRoot never contains executable code. It's role is to be a starting point, containing the following:

  • Declarations of the global constants and variables.
  • Optional structure definitions.
    (For example, tag parameter metadata is typically defined in AppRoot.)
  • Declarations of modules local to this application.
    This includes all of the application pages, user-defined tags and widgets, custom services, drivers, reports and more.

When you create new modules for a standard application, you must declare them in AppRoot. The form of that declaration has four parts:

  1. The group within which the module is being declared. Modules that are pages go into the [(PAGES) ... ] group. Modules that are reports go into the [(PLUGINS) ... ] group.
    Most modules that you write will be either plugins or services.
  2. The name to be assigned to that module. Any legal name may be used.
  3. The keyword, Module.
  4. The path to (and name of) the .SRC file containing the module's code. This is a text value and therefore must be enclosed in double quotes. The path is always relative to the application folder.

Like all statements in the VTScada language, this declaration must end with a semicolon.

Use care when naming your modules. Try to avoid any VTScada names like AnalogInput.

Add a New Module to an Application

Preparation: You will need a module. Create a text file named ColorCycle.SRC in main folder holding your application, then copy or type the following into it:

{=========================== ColorCycle.SRC ==================================}
{ A simple demonstration module. Displays a message that changes              }
{ color every two seconds                                                     }
( {Parameters...}
  Message             { Optional paramter for the text to display             };
  Xcoord              { Optional X & Y location for the message               };
  Ycoord;
)
[ {Variables...}
  NextColor = 0       { Next color to use from the VTScada palette.           };
  LocX                { Local storage of the coordinates                      };
  LocY;
]

Init [  { Set defaults for the parameters}
  If 1 Main;
  [
    Message = PickValid(Message, "Hello World!");
    LocX    = Max(10, PickValid(Xcoord, 100))  { >= 10 pixels from the edge   };
    LocY    = Max(55, PickValid(Ycoord, 100))  { Room for the title bar       };
  ]
]

Main [
  ZText(LocX, LocY, Message, NextColor, 0); 
  If Watch(1, \TwoSecondFlasher);
  [
    NextColor++;
    IfThen(NextColor > 255, 
      NextColor = 0;
    );
  ]
]

This extremely simple module can be added to the code of any page, where it will display a message. The default message is "Hello World!", located at 100, 100, but you can provide your own message and coordinates as follows: ColorCycle("My message", XLocation, YLocation);

If you get an error message when running the Import File Changes command, check your file changes carefully for punctuation and placement. Ensure that you did not skip a step.

Add a module to a standard application:

  1. Open AppRoot.SRC of your application in a text editor.
  2. Within the square brackets of the Plugins group, add the following line:
  ColorCycle         Module "ColorCycle.SRC" { Display a message       };

(If this were a page, you would add it to the [ (PAGES) group. If a Widget, the [ (65282) group. This module does not qualify as either of those, or any other group designation, therefore Plugins is the best choice.)

Example:

  [ (PLUGINS)       {===== Modules added to other base system modules =====}
    ColorCycle  Module "ColorCycle.SRC";
  ]
  1. Save AppRoot.SRC and close your text editor.

For the next two steps, if either the Pages folder or Overview.SRC (or both) does not exist, run the application, open the Idea Studio, then close the Idea Studio. The folder and file will be there.

  1. Navigate to the Pages folder of the application.
  2. Use a text editor to open the file, Overview.SRC
  3. Within the Main state block, add the following line:
  ColorCycle();

(You might choose to add your own message and coordinates, as described in the exercise preparation notes.)

Example:

Main [
  Return(Self);
  ColorCycle("This is a message", 300, 200);
  1. Save the file.
  2. In the VTScada Application Manager, select the Import File Changes button for this application.
  3. Select "Yes" when prompted to import ColorCycle.SRC.
  4. Run the application.