1.5 Storage Interface

The Storage interface provides a way to save variable data. Variables can be saved in temporary storage or persistent storage.

1.5.1 Variables

Scripting variables can be used to store information for use in the current Endpoint Security Agent session (temporary variables) or for use across sessions (persistent variables).

As you use variables, be aware of the following naming conventions:

Variable names can contain any printable character.
Variable names are not explicitly limited in size.
A global variable is defined by prepending a forward slash (/) to the variable name. Global variables are available to other scripts. For example: Storage.NameValueExists(“/boolWarnedOnPreviousLoop”).
Any variable that does not start with a forward slash (/) is a local variable. Local variables are available only to the script that created them.
Variables are stored in either temporary storage or persistent storage (for details, see Section 1.5, Storage Interface). Variable names are unique to each storage system. If a script uses the same name for a variable in both the temporary and persistent storage, the values are independent of each other despite the name being the same.

1.5.2 Temporary Storage Methods

Temporary storage allows a variable to be retained for the current Endpoint Security Agent session only. The variable is lost when the agent shuts down.

All variables are considered local to the script unless the variable name follows the naming conventions for a global variable. Local variables use the script’s identifier to ensure uniqueness. If the script identifier is changed, the script no longer has access to its local variables.

bool Storage.NameValueExists(string name)

	Description:	Determines if a temporary variable already exists.
	Parameters:	name — variable name being requested
	Returns:	True if the variable is found in the store. False if not.

string Storage.GetNameValue(string name)

	Description:	Gets the value associated with a temporary variable.
	Parameters:	name — variable name being requested
	Returns:	The value being stored. If the value does not exist, an empty string is returned.

int Storage.SetNameValue(string name, string value)

Description:

Sets the value for a temporary variable.

Parameters:

name — variable name in which to store the value

value — value to store

Returns:

0 on success. Any other number on failure.

int Storage.ClearNameValue(string name)

	Description:	Clears the value for a temporary variable.
	Parameters:	name — name of variable to clear
	Returns:	0 on success. Any other number on failure.

1.5.3 Persistent Storage Methods

Persistent storage allows a variable to be retained across Endpoint Security Agent restarts; the variable can only be cleared by script or by using the Agent Status feature in the Endpoint Security Agent’s About box.

bool Storage.PersistValueExists(string name)

	Description:	Determines if a persistent variable already exists.
	Parameters:	name — variable name being requested
	Returns:	True if the variable is found in the store. False if not.

string Storage.GetPersistValue(string name)

	Description:	Gets the value associated with a persistent variable.
	Parameters:	name — variable name being requested
	Returns:	The value being stored. If the value does not exist, an empty string is returned.

int Storage.SetPersistValue(string name, string value)

Description:

Sets the value for a persistent variable.

Parameters:

name — variable name in which to store the value

value — value to store

Returns:

0 on success. Any other number on failure.

int Storage.ClearPersistValue(string name)

	Description:	Clears the value for a persistent variable.
	Parameters:	name — name of variable to clear
	Returns:	0 on success. Any other number on failure.

1.5.4 JScript Example

var ret;
var curValue = 0;
if (Storage.NameValueExists("testval"))
    curValue = Storage.GetNameValue("testval");
curValue++;
ret = Storage.SetNameValue("testval", curValue);
Action.Trace("NameValue = " + curValue);
Action.DisplayMessage("Storage", "Name Value: " + curValue, "Info", 3);
Action.Sleep(3000);
 
curValue = 0;
if (Storage.NameValueExists("/testval"))
    curValue = Storage.GetNameValue("/testval");
curValue++;
ret = Storage.SetNameValue("/testval", curValue);
Action.Trace("Shared NameValue = " + curValue);
Action.DisplayMessage("Shared Storage", "Name Value: " + curValue, "Info", 3);
Action.Sleep(3000);
 
curValue = 0;
if (Storage.PersistStringExists("testval"))
    curValue = Storage.GetPersistString("testval");
curValue++;
ret = Storage.SetPersistString("testval", curValue);
Action.Trace("Persist String = " + curValue);
Action.DisplayMessage("Storage", "Persist String: " + curValue, "Info", 3);
Action.Sleep(3000);
 
curValue = 0;
if (Storage.PersistStringExists("/testval"))
    curValue = Storage.GetPersistString("/testval");
curValue++;
ret = Storage.SetPersistString("/testval", curValue);
Action.Trace("Shared Prersist String = " + curValue);
Action.DisplayMessage("Shared Storage", "Persist String: " + curValue, "Info", 3);
Action.Sleep(3000);

1.5.5 VBScript Example

dim ret
dim curValue
curValue = 0
 
If Storage.NameValueExists("testval") then
    curValue = Storage.GetNameValue("testval")
End If
curValue = curValue + 1
ret = Storage.SetNameValue("testval", curValue)
Action.Trace "NameValue = " & curValue
msg = "Name Value: " & curValue
 
Action.DisplayMessage "Storage", msg, "Info", 3
Action.Sleep 3000 
 
curValue = 0
If Storage.NameValueExists("/testval") then
    curValue = Storage.GetNameValue("/testval")
End If
 
curValue = curValue + 1
ret = Storage.SetNameValue("/testval", curValue)
Action.Trace "Shared NameValue = " & curValue
Action.DisplayMessage "Shared Storage", "Name Value: " & curValue, "Info", 3
Action.Sleep 3000
 
curValue = 0
If Storage.PersistStringExists("testval") then
    curValue = Storage.GetPersistString("testval")
End If
curValue = curValue + 1
ret = Storage.SetPersistString("testval", curValue)
Action.Trace "Persist String = " & curValue
Action.DisplayMessage "Storage", "Persist String: " & curValue, "Info", 3
Action.Sleep 3000
 
curValue = 0
If Storage.PersistStringExists("/testval") then
    curValue = Storage.GetPersistString("/testval")
End If
curValue = curValue + 1
ret = Storage.SetPersistString("/testval", curValue)
Action.Trace "Shared Prersist String = " & curValue
Action.DisplayMessage "Shared Storage", "Persist String: " & curValue, "Info", 3
Action.Sleep 3000