Retained Variables

Retained variables can be used when separate instances of a module need to retain a value between instantiations and VTScada executions. Unlike persisted variables, these are not shared. (Persisted variables are equivalent to shared plus retained.)

One application of Retained variables is for user settings, loading all of the new user's customized settings when the username changes. Another is for location coordinates of a dialog box that might be shared by several modules. In this way, you may use Retained variables like a database.

 

Declaring Retained Variables

Declare a retained variable by using the "Retained" keyword before the variable definition. For example:

Retained My_Retained_Var { Retained Variable };

Assigning Names to Module Instances

Each module instance must be assigned a name. This can be done in one of the following ways:

• SetInstanceName This function takes two parameters: Instance and Name. Instance is the object value of the module to which the name is to be assigned. Name is the text string name of the instance.

Tags are automatically given a unique name (matching the unique ID) when launched.

• The name parameter in the Thread function also sets the name of an instance. (All applications are launched in a separate thread with the application name being the thread/instance name.)
• If an instance name is not explicitly set, an instance name is inherited from the nearest parent's name. If none of the parents have an explicit name, the name "Default" is used.

Setting the instance name will cause all the Retained variables to be reloaded with the values for that instance. Instance names may be changed dynamically.

Retained Variable Value Storage

The values for retained variables are stored in a folder named, "Retained" that exists within your application folder structure. The files containing the retained variable values have the extension ".VAL". The name uniquely identifies the module instance for which the retained value is meant. This is typically done by using the parent-child hierarchy of the module plus a unique identifier created for that module instance. For example, Totalizer tags retain their last logged value. This is stored in a file with the built as System-Code-TotalizerTag-LastLoggedValue+UniqueID.VAL

Retained values are written to disk whenever they change. They are written using the Pack scheme, allowing complex arrays and linked lists to be persisted. Note that any modified values that are indirectly pointed to from the retained value (array elements) will not trigger a rewrite of the retained variable to disk. However, when the instance terminates, either through an instance name change or a stopping instance, the retained values will be written.

This implies that crashes, power failures, etc., can result in the most recent retained values not being on disk if these values contain pointers to values.

Retained Variables and Statically Declared Arrays

Retained variables enable you to specify a default value for a statically declared array. If specified, all the elements of the array will be set to this value when the array is instantiated. For example, an array declaration such as:

[
   Data[10] = 0;
]

will result in all 10 elements of the data array to have the initial value of "0".

If the array with the initial value specified has a default value, the default value will only be used if there is no suitable retained value .VAL file.

Recompiling to change the number or size of dimensions of a retained variable will cause any retained .VAL files previously saved with the old variable format to be ignored.