Variables

This section discusses how to declare and use ION Script variables, the types of data an ION Script variable can hold, and how to create persistent variables that can be used across multiple ION Script pages.

All ION Script variables must be prefixed by the $ symbol when they are referenced, and when they are assigned a value using the ION_EVALUATE tag. They are not prefixed with the $ symbol, however, when they are declared using the VARIABLE_DECL tag.

Declaring & Assigning Values

<VARIABLE_DECL NAME="name" TYPE="type" VALUE="value" 
   PERSIST="TRUE"/>

Declaring a variable allows you to explicitly define the type of data held by the variable, and allows you to make the variable persistent.

Although it is recommended, ION Script variables do not need to be declared before they are used. Variables can be assigned values equal to the result of an expression using the ION_EVALUATE tag as follows:

<ION_EVALUATE EXPR="$variable = expression" />

Variable Types

ION Script currently uses four data types:

DOUBLE — Double precision

INT — Integer

BOOL — Boolean

STR — String

ION Script variables are strongly typed, meaning the type of data they hold cannot change once they have been declared or assigned a value. Variables are assigned a data type only once: if you declare the variable using VARIABLE_DECL, then you assign the type using the TYPE attribute. If you assign a value to the variable using ION_EVALUATE, then the type assumed by the variable depends on the result of the expression to which it is assigned. Reassigning a value to a variable that has already been declared or assigned a value does not change the type of the variable, even if the value that it is reassigned is of a different type than the variable.

If you assign a value to an undeclared variable, the variable assumes one of the following types:

If you assign a numeric value to an undeclared variable, the type becomes double.

If you assign a string value to an undeclared variable, the type becomes string. For example, the following code creates a string variable and assigns the value 'Smith':

<ION_EVALUATE EXPR="$Name='Smith'" DISPLAY="TRUE"/>

If you assign TRUE or FALSE to an undeclared variable, the type becomes boolean. For example, the following code creates a boolean variable and assigns a value of true:

<ION_EVALUATE EXPR="$Selected=TRUE" DISPLAY="TRUE"/>

The only case in which ION Script will convert a value from one type to another is when you declare a variable as a TYPE that is different from the value to which you assign it. Consider the following examples:

If you declare a variable as an INT equal to 1.666, the value is converted to an integer equal to 1. (When ION Script converts the floating-point value to an integer, the decimal portion is truncated.)

If you declare a variable as an INT and assign it a non-numeric string value, the value becomes an integer equal to 0.

If you declare a variable as a DOUBLE and assign it a non-numeric string value, the value becomes a double-precision value equal to 0.00.

If you declare a variable as a STR and assign it a number, the number is converted to double-precision and then to a string. To avoid having the number converted to double before string, nest single quotation marks inside the double quotation marks as follows:

<VARIABLE_DECL NAME="A" TYPE="STR" VALUE=" '35.4' " />

If you declare a variable as a BOOL equal to a number, the value becomes false.

A single expression can contain variables and/or values of different types. The result of an expression containing variables and/or values of multiple types assumes the type of the highest-precision value. For example, adding an INT to a DOUBLE results in a DOUBLE. The degree of precision, from highest to lowest, is DOUBLE, INT, BOOL, STR. When the expression contains a string added to a numeric value (using the + operator), the result is a string.

Assigning String Literals to ION Script Variables

Whenever you assign a string literal as the value of an ION Script variable, the string literal should be enclosed in single quotation marks, which are then enclosed in the double quotation marks used to delimit the attribute value. For example, the following code shows the correct way to assign a string literal to the VALUE attribute of the VARIABLE_DECL tag:

<VARIABLE_DECL NAME="animal" TYPE="STR" VALUE="'dog'"/>

If you are assigning a string variable as opposed to a string literal to the VALUE attribute, do not enclose the variable in single quotation marks. For example, if the variable animal has already been defined as a string, you would assign the value of the animal variable to a new variable as follows:

<VARIABLE_DECL NAME="pet" TYPE="STR" VALUE="$animal"/>

Determining Variable Type

To easily determine the data type of a variable, use the ISTYPE operator as follows:

$VarName ISTYPE VarType

where VarName is the name of the variable, and VarType is one of the following string literals: 'BOOL', 'STR', 'INT', 'DOUBLE', or 'UNDEF'.

Note
The left side of the ISTYPE expression must be a variable and not an expression. If you need to determine the resulting type of an expression, assign the expression to a variable and use ISTYPE to determine the type of the variable.

For example, to determine whether the variable MyVar is undefined, you could use the following ION Script code:

<ION_IF EXPR="$MyVar ISTYPE 'UNDEF'">  
   MyVar is undefined  
<ION_ELSE/>  
   The value of MyVar is <ION_VARIABLE NAME="$MyVar"/>  
</ION_IF>

Null Strings Versus Undefined Strings

There is a difference between an empty (null) string and an undefined string. A null string is a defined variable that is assigned no characters. If the value you assign to a variable is a null string, an undefined variable, or an expression that cannot be evaluated, and the TYPE is "STR", that variable is defined, and the variable's value is a null string. In the following example, the variable A is assigned a null string, and the variable B is not declared:

<ION_SCRIPT>  
   <ION_HEADER>  
      <VARIABLES>  
         <VARIABLE_DECL NAME="A" TYPE="STR" VALUE="''"/>  
      </VARIABLES>  
   </ION_HEADER>  
   <ION_BODY>  
      <ION_VARIABLE NAME="$A"/>  
      <ION_VARIABLE NAME="$B"/>  
      <ION_IF EXPR="$A ISTYPE 'UNDEF'">  
          A is undefined  
      </ION_IF>  
      <ION_IF EXPR="$B ISTYPE 'UNDEF'">  
         B is undefined  
      </ION_IF>  
   </ION_BODY>  
</ION_SCRIPT>

The result of this ION Script page is:

Error: Variable $B does not exist
B is undefined

Variable Names

The following rules apply to variable names in ION Script:

When referencing the variable, or assigning it a value using ION_EVALUATE, the variable name must be prefixed with the $ symbol.

The first character (after the $ symbol) must be a letter. Subsequent characters can be letters, numbers, or underscores (_).

Variable names are case-sensitive. If you declare a variable as $A, you cannot refer to that variable as $a.

The variable name cannot be one of the following ION Script reserved words: Browser, Document, Form, FormURL, ION, or Mouse.

Variable Scope

ION Script documents can contain the ION_INCLUDE tag, which is used to insert the contents of another file (ION Script, HTML, or text) into the current ION Script document. Variables defined in the enclosing page have global scope, meaning they can be accessed from either the enclosing page or the included page. Variables defined in included files have local scope, meaning they can be accessed only from the included page.

If a variable with the same name is declared in the enclosing page and the included page, the variable takes the value that was declared in the included page. For example, consider the following two ION Script files:

enclosing.ion:

<ION_SCRIPT>  
<ION_HEADER>  
   <TITLE>Scope Test</TITLE>  
   <VARIABLES>  
      <VARIABLE_DECL NAME="A" VALUE="5" TYPE="INT"/>  
      <VARIABLE_DECL NAME="B" VALUE="5" TYPE="INT"/>  
   </VARIABLES>  
</ION_HEADER>  
<ION_BODY>  
   <B>Enclosing file:</B><BR>  
   A = <ION_VARIABLE NAME="$A"/><BR>  
   B = <ION_VARIABLE NAME="$B"/><BR>  
   C = <ION_VARIABLE NAME="$C"/>  
   <ION_INCLUDE SRC="ion://included.ion"/>  
</ION_BODY>  
</ION_SCRIPT>

included.ion:

<ION_SCRIPT>  
<ION_HEADER>  
   <VARIABLES>  
      <VARIABLE_DECL NAME="B" VALUE="10" TYPE="INT"/>  
      <VARIABLE_DECL NAME="C" VALUE="20" TYPE="INT"/>  
   </VARIABLES>  
</ION_HEADER>  
<ION_BODY>  
   <BR>  
   <B>Included file:</B><BR>  
   A = <ION_VARIABLE NAME="$A"/><BR>  
   B = <ION_VARIABLE NAME="$B"/><BR>  
   C = <ION_VARIABLE NAME="$C"/>  
</ION_BODY>  
</ION_SCRIPT>

In this example, the enclosing page declares variables A and B, each set to 5. The included page also declares variable B, but sets the value to 10. The value of B in the included page becomes 10. Although variable A was not declared in the included page, we have access to its value from the enclosing page. The reverse is not true, however: the variable C, declared in the included page, is not accessible in the enclosing page because its scope is limited to the included page. The following figure shows the result of loading Enclosing.ion in the browser:

Figure 3-1: Enclosing Results

Figure 3-1: Enclosing Results

Variable Persistence

Variables can be persistent across ION Script pages. Once a variable is declared as persistent, it is available to all ION Script pages that are called via an ION Script event or ION_LINK, without having to re-declare the variable in each page. If the variable is declared as not persistent (PERSIST set to FALSE or no PERSIST attribute), or not declared at all, the variable can be referenced only in the page in which it is declared or assigned a value, and in included pages. If you declare a persistent variable and pass it to a page that declares a variable (persistent or not) with the same name, the new declaration is not used—the value passed from the previous page is used.

IDL Online Help (March 06, 2007)