GetRetainedValue

(Engine-Level Function)

Description:	Given the name of a variable whose value was retained, this function will load the retained value from storage. The function also provides the option of deleting the files holding that value.
Returns:	Varies
Usage:	Script Only.
Function Groups:	Variable
Related to:	nothing
Format:	GetRetainedValue(Instance, VariableName[, SharedFlag, DeleteFlag]);
Parameters:

Instance

Required object. The module instance for which we want to load the value.

VariableName

Required text. The name of the variable to load.

SharedFlag

Optional Boolean. Set TRUE to indicate that the variable was shared. Defaults to FALSE.

DeleteFlag

Optional Boolean. Set TRUE to delete the files storing the retained variable for the identified module.

Comments

This function is used to work with the storage files left behind after changing your code such that a variable that had been retained is no longer used or no longer retained. You are advised to avoid using this function with variables that continue to be retained.

If an operation is in progress elsewhere to set a new value for the variable, this function will not detect that operation nor wait for it. In this case, it is possible for the returned value to differ from the new current value.

The DeleteFlag will be ignored if the variable is still being retained. You can delete the stored value only after removing the variable from your code or re-declaring the variable without the Retained flag (and recompiling your module).

If the value is a static array, this function will return it as a dynamic array.

Example:

Given a retained variable, SaveValue, that was used for a set of operations, but that should not be left in existence between restarts, you can remove it as follows:

  If Valid(SaveValue);
  [
     { All machines should delete the Retained file to avoid this triggering
       on some future restart. }
    TempSaveValue = GetRetainedValue(Caller(Self), "SaveValue", FALSE { Shared }, TRUE { Delete });