Class Documentation

Name:Variable
Version:1.1
ID:ID_VARIABLE
Status:Stable
Category:Command
Date:October 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2004. 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 stored field values from a variable object.
SaveSettings  Save changes to the variable data file.
SetUnlistedField  Stores new field values in a variable object.

Methods

The Variable class implements the following methods:

StripSlash  Strips trailing forward and back slashes from 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.
Action:SaveSettings
Short:Save changes to the variable data file.

If the variable object is file-based, the SaveSettings action can be called at any time to write all of the data back to the file. If the variable object is not file-based, the SaveSettings action does nothing.


Method:StripSlash()
Short:Strips trailing forward and back slashes from variable fields.
Arguments:
STRING Variable  The name of the variable field that you want to strip.

This method will strip any given variable field of any back or forward slashes that happen to be trailing at the end of the field string. For instance, using this method to strip a variable containing "athene:documents/" will result in the string being reduced to "athene:documents".

Result
ERR_Okay  All back and forward slashes were removed successfully.
ERR_Args  Invalid arguments were specified.
ERR_Search  The referenced variable name does not exist.

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
This 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.

USEPRESETS
This flag gives priority to any values that have been preset in the variable object. Any configuration data loaded from the file referenced in the Location field will not be able to override preset values.


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

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.