AddVariable

(Engine-Level Function)

Description: Adds a new variable to an existing module and returns its variable value.
Warning: This function should be used only by advanced programmers.
Returns: Variable
Usage: Script Only.
Function Groups: Compilation and Online Modifications,  Variable
Related to: DeleteVariable | MakeNonShared | MakeNonPersistent | MakePersistent | MakeShared | SetDefault | SetVariableClass | SetVariableText
Format: AddVariable(Module, Name, Reserved, Attrib, Class, PersistentSize, VarTextSize, NumDimensions, ArrayElem, ArraySize)
Parameters:  
Module
Required. Any expression that returns a module value.
Name
Required. Any text expression that gives the name of the new variable.
Reserved
Reserved for future use. Set to 0.
Attrib

Required. Any numeric expression giving the variable attribute bits as follows:

(See: Bitwise Parameters & Operations)

Attrib

Bit No.

Attribute

1

0

Array

2

1

Shared

4

2

Persistent

8

3

Module

16

4

Parameter

32

5

Constant

64

6

(Obsolete) Reserved - set to 0

128

7

(Obsolete) Reserved - set to 0

256

8

Temporary *

512

9

Protected

1024

10

Variable is an instance variable (see comments)

A variable cannot be both persistent and temporary, since a persistent variable is stored on disk, and a temporary variable exists only while VTScada is running or until the application is recompiled.

* Note: Temporary variables should be used only by advanced users, since recompiling the application destroys them.
Class
Required. Any numeric expression in the range 0 to 65535, giving the variable class number for the new variable.
PersistentSize
Required. Any numeric expression giving the number of bytes of storage allocated in the .VAL persistent variable file for this variable.
For array types, set this to the byte size of the largest array element (normally 8 bytes for numeric values).
For arrays containing text, enter the character length of the longest string element.
Use a valid 0 if this isn't a persistent variable.
VarTextSize
Required. Any numeric expression giving the length of the variable declaration text in characters.
This parameter is ignored for temporary variable types.
NumDimensions
Required. Any numeric expression that gives the number of array dimensions for the variable.
NumDimensions should be "0" for a simple variable.
ArrayElem
Required. Any array element giving the starting element in the array. The subscript for the array may be any numeric expression.
If NumDimensions is 0, ArrayElem is ignored.
If NumDimensions is 1, this specifies the starting index for the array.
If NumDimensions is greater than 1, this is element of an array of starting indices for each dimension of the multidimensional array.
ArraySize
Required. Any numeric expression specifying the size of the array.
If NumDimensions is 0, ArraySize is ignored.
If NumDimensions is 1, this specifies the number of elements in the array.
If NumDimensions is greater than 1, this is an array of sizes for each dimension of the array.
Comments:

Seldom (if ever) used when adding features to modern VTScada applications.

This function doesn't affect the .SRC file; it affects the expected location of items in the .SRC file. Both must be updated in unison.
The return value is the new variable added. If the variable already existed, it will remain unchanged and the return value will be Invalid.
Bit 10 (1024) of the Attrib parameter specifies that the variable is an instance variable. An instance variable is a temporary variable that gets added to a single instance of a module, rather than all instances of a module. If you specify this bit, then you must have passed an object (module instance) into the first parameter. Instance variables cannot also have the attributes Shared, Persistent, Module, or Parameter.

Example:

  If 1 Main;
  [
    AddVariable(Self() { Create variable as part of this module },
                "MyObjectID" { Name of new variable },
                0 { Reserved },
                256 { Variable is temporary },
                0 { Class },
                0 { Variable not persistent },
                0 { no name },
                0 {  },
                0 { Array starting index },
                0 { Number of elements in array });
  ]

In this example, the statement creates a temporary variable with a hard-coded name.