Class Documentation

Name:Variable
Version:1.0
ID:ID_VARIABLE
Status:Unspecified
Category:Command
Date:April 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2001. All rights reserved.



Description

The Variable class is used to create, store and retrieve values during the execution of a script. Essentially it allows you to store any type of data that you like using object compatible methods. It also has its uses in saving program options, desktop settings and other bits of information that may need to be recalled at a later stage.

Data storage and retrieval is achieved through the use of unlisted fields, so a variable object named "storage" with fields "x", "y" and "z" would be created as follows when using DML:

   <variable name="storage" &x="1" &y="2" &z="3"/>

For occasions when data needs to be stored permanently, the Variable class supports file locations for data storage and retrieval. Using our previous example, we can store the x, y and z values in a configuration file, as follows:

   [data]
   x = 1
   y = 2
   z = 3

To load the data file into a variable object, we would use this DML code:

   <variable name="storage" location="data.cfg"/>

When using a file location, bear in mind that the Variable class will save all data back to the file when the Variable object is destroyed.

Actions

The Variable class supports the following actions:

GetUnlistedField  Retrieves variable fields.
SetUnlistedField  Sets variable fields.

Structure

The Variable object consists of the following public fields:

Flags  Special flag settings.
Location  Variables can be loaded from a configuration file if you set this field.
Field:Flags
Short:Special flag settings.
Type:LONG
Prefix:VF_
Status:Read/Write

This field contains flags that affect object behaviour. Currently available flags are:

NOREPLACE
The NoReplace flag is useful when the over-writing of variable data is undesirable. Setting this field will still allow new variables to be stored in the object, but you won't be able to update the values.

 

Field:Location
Short:Variables can be loaded from a configuration file if you set this field.
Type:STRING
Status:Read/Init

Setting the location field tells the Variable object to load its variables from a file location. The file must be written in the standard configuration format (refer to the Config class for details). When the Variable class is destroyed, all current field stores will be saved back to the file location so that any changes are retained.