Module Structure

Executable lines of code are called "statements". These can be written over several lines of the file, but always end with a semi-colon. Statements must be written inside the brackets that enclose one of the following sections of a module: parameters, variables or states.

Here is an example showing the structure of a module with comments but no code. Descriptions of each numbered item follow the example.

{========================== MyFile.src ============================}
{ 1. This is a sample module                                       }
{==================================================================}
(
  { 2. Parameter section: }
)
[
  { 3. Variable declarations. }
]

State1 [
  { 4. State section. All the executable code in a module lives
      inside states. The first state encountered will run. }
]
{ This line is outside any state. Write no code here.      }

State2 [
  { 4. Another state. Will run only if control is passed to it. }
]

< {5. Submodule starts }
MySubModule
{ Content as above. }
>
{======================= End of File ========================}
  1. A comment section, describing the module.
    While not strictly part of the module's definition, and containing no statements, the comment block is a vital component from the point of view of good coding practice. Comments are enclosed in braces, also referred to as curly brackets {}. You may scatter comments throughout your code.
  2. Parameter section, enclosed in parentheses ( ).
    These are referred to as the "declared" or "formal" parameters. Parameters used in the call to the module are referred to as the actual parameters. Actual parameters are matched to declared parameters in order from left to right.
    If the call to a module has fewer actual parameters than declared parameters, the extra declared parameters will be set to Invalid. If there are more, you can access those parameters within your module by using the Parameter() function, even though there were not declared as part of the module's formal parameter set.
    Declared parameters can be given default values using an initialization state in the module definition, via a PickValid() call. Attempting to set a default value for the declared parameter when declaring it is regarded as bad form. Behavior in that case will differ depending on whether the actual parameter was missing or provided as a variable with an Invalid value, which is likely to cause confusion and errors.
    Parameters are passed by value or by reference according to how the module is started. (Launched Versus Called Modules).
    You can assign metadata to module parameters when declaring them. See: Parameter Metadata
    You can also enforce value types for parameters. See: Parameter and Variable Type Checking
  3. Variable section, enclosed in brackets [ ].
    All variables and submodules used in the module must be declared here. Data types are attached to whatever value is stored within the variable rather than to the variable itself, therefore there is no need to specify data types as part of the declaration. The exception is the declaration of submodules. These should be declared in the variable section and should be followed by the keyword "Module". Additionally, if the submodule is stored in another file, that file name must be provided. As with parameters, you can enforce type checking. See: Value Types and Variable Storage, Retention, Access
  4. State Sections.
    Each state in the module begins with the name of the state, followed by brackets that enclose the code of the state. The first state found in the module will always be the first state to run. It is commonly called "Init" or "Main", but the name has no special meaning. Those words are simply used by convention to increase readability.
  5. Submodules (optional), enclosed in angle brackets < >.
    These are also referred to as "child modules". The first module within any file should not be enclosed in angle brackets, but each child module within the same file must be. Within each submodule, the structure is the same as described in the preceding points.

Not shown:

  • Reference box coordinates. Used only in modules that define graphics such as widgets. The reference box coordinates are placed before the parameter section in the module file and will contain four numeric constant values in the form:

(Left, Bottom, Right, Top)

If the purpose of a module is to display a graphic object, it is useful to define a reference box. This defines the rectangle to be occupied by all graphics drawn by the module, possibly including a margin around those objects. If a reference box is not defined, then VTScada will automatically calculate one based on the graphics being displayed. Leaving the reference box to be calculated automatically can have a negative effect if the module contains various states with different graphic statements. If VTScada must re-calculate the reference box as the module changes from state to state, transformations applied to the display can be affected.