Using script object variables

Object variables are used to store information. It is recommended that you use variable names with obvious meanings to simplify future maintenance and debugging tasks. The following example illustrates how to create a new variable for the script object and assign data to its content:

$script.myVariable = “alphabet soup”

The first part of this statement makes reference to the script script object and the variable myVariable. The equals sign (=) indicates that the variable should contain the content that follows. The equals symbol is the assignment operator.  In the above example, the $script.myVariable is assigned the string content of “alphabet soup”.

Object variables have an inherent type: string, boolean, float, or integer. Variables are also lists. These types are explained further in the following sections.

Variable typing in Action Script is called variable auto-typing. The language tries to determine what type of value is being assigned to a variable based on the content of the assignment. Variable auto-typing works with another feature of the Action Script language called variable auto-conversion which is explored in the section on expressions. For more information, see Variable auto-conversion rules.

You can use object variable methods to modify the content of variables. Like script object methods, the syntax to indicate that a variable method is to be used is a pair of colons:

$script.recipients::toLowerCase()

The methods you can use on a given variable depend on its type. For a complete list of script variable methods, see Object Variable Methods.

Short-hand notation for variables in the default script object

The normal syntax for all script objects is:

$<script object name>.<script object variable name>

Because the script script object is guaranteed to be present for all scripts, the following full syntax:

     $script.recipients

can be represented using short-hand as:

     $recipients

When the script object name and period are omitted in a variable reference, it is assumed that the variable belongs to the script script object.

String variables

Strings are alphanumeric sequences, and usually have quotes around them during an assignment. Quotes are required if the string has any white space, such as a space character or a tab. The following are illustrations of string assignments to object variables:

$script.a = alphabet

$script.b = 111abc

$script.c = “12345”

$script.d = “false”

$script.e = “ ”

For a list of string variable methods, see Object Variable Methods.

Boolean variables

Booleans are variables with a logical true or false value assignment. The following illustrates how to assign an object variable a Boolean value:

$script.isDone = false

$script.createNotification = true

Although Boolean variables resemble a form of string assignment, the keywords true and false (without quotes) are reserved.

Numeric variables: float, integer, and long

Numeric values are one of three types: float, integer, or long. The following are examples of float assignments:

$script.subtotal = 1200.0

$script.taxRate = .07

$script.pi = 0.314

The following are examples of integer assignments:

$script.index = 4

$script.replyCount = 0

$script.population = 42000

Integer variables can hold values between -231 and 232-1.

Long variables are used primarily to hold IDs and dates or times that are passed as numeric. In scripts, the constant value of long variables is appended with an 'L' at the end of the string; for example:

$script.equationResult = 121731480000000L

Long variables can hold values between -263 and 264-1

List variables

All object variables are actually lists (i.e., ordered collections of elements). The assignment operator (the equals sign) ensures that the variable is a list with only one element. This is also considered to be the primary list element. If a list is used in an expression that does not explicitly use a particular list element or the entire list, the primary element is used.

Since list elements are variables, they also work with variable auto-typing as described above.

The list variable type has an important role in the notification process. Lists can contain elements of any variable type, but the following illustrates a variable constructed as a list with only string variables as elements:

$script.recipients = “Engineering Group”

$script.recipients::add(“Building 14”)

$script.recipients::add(“Winston Smythe”)

To add additional elements, called recipients, to the object variable, a similar syntax as object method referencing is used to execute a variable-based method. Variables have methods for list manipulation and other variable-specific methods. Only some of the list methods are illustrated in this introduction. For a more detailed reference, see Object Variable Methods.

In the example above, the add() method was used to add additional string elements to the recipients list, for a total of three list elements. The list maintains order based on the order that the elements were added, unless a list method is performed to change that order, such as the sort() method that sorts the elements within a list. In the example, the first element is “Engineering Group”, the second element is “Building 14”, and the third element is “Winston Smythe”.

Note that the example code above starts with an explicit “=” assignment. This guarantees that any values previously stored in the $script.recipients variable are cleared. The following code is equivalent to the previous example only if the recipients variable is undefined prior to this code being executed:

$script.recipients::add(“Engineering Group”)

$script.recipients::add(“Building 14”)

$script.recipients::add(“Winston Smythe”)

The add() method will never clear a variable’s previous value or values.

The size of the list can be determined by using the variable list method size(). The following assigns the current size of the recipient list to the $script.totalRecipients variable:

$script.totalRecipients = $script.recipients::size()

In this case, the object variable totalRecipients is an integer type with the value of “3”.

In some cases it may be necesary to access the contents of a specific element in a list. The following illustrates how to retrieve the second value in the list and assign it to another object variable:

$script.secondRecipient = $script.recipients::get(1)

The get() method variable does not remove the element from the list; the recipients object variable still contains all three elements originally assigned to it.

Attempting to access a list element that does not exist will cause a scripting exception. For example, executing the following code with the recipients variable causes an exception error:

$script.lastRecipient = $script.recipients::get(3)

There are programmatic ways to avoid this kind of issue. The following example illustrates how to retrieve the last element in a list without knowing or guaranteeing the size of the list, and without causing an exception:

$script.numberOfRecipients = $script.recipients::size()

$script.numberOfRecipients = $script.numberOfRecipients - 1

$script.lastRecipient = \

    $script.recipients::get($script.numberOfRecipients)

The significance of this code is that it works with a list of any size, and therefore the code continues to work, even if the size of the list changes.

A get() variable method without an index value will assume the index value is “0” and return the first element in the list.

The remove() variable method works in the same manner as the get() variable method, except that it removes the indexed element from the list. The following example illustrates how to remove the first element from the recipients list, and assign it to another object variable:

$script.recipient = $script.recipients::remove()

As with the get() variable method, the assumed index value is “0”.

Using remove() on a variable that no longer contains any elements causes a scripting exception, but this situation can also be programmatically avoided.

In Action Script, variables do not exist until they have been created, which requires an assignment or an add(), and they cease to exist when the last element is removed. The exists() operator checks for the existence of a particular variable, and returns a Boolean value: true if the object variable exists, and false if it does not.

The following code illustrates how to ensure it is possible to remove() from an object variable without causing an exception:

If (exists($script.recipients)) \

$script.recipient = $script.recipients::remove()

endif