Xbasic GuideVariables and Data Types

Variables store values for later use. Before a variable is used either by a script or in an expression, it must be declared. A variable is declared either explicitly as a formal declaration in a script, a table, a set, a form, or an application; or implicitly by assigning it a value for the first time in a script. In general, a variable declaration must specify two things: the name of the variable, and the type of data the variable can contain.

A variable name must start with a letter (A to Z, a to z). Subsequent characters can be alphanumeric or an underscore (A to Z, a to z, 0 to 9, _). Variable names are not case-sensitive, so the names GONZO and Gonzo refer to the same thing. Variable names cannot contain spaces. Xbasic does not prevent you from using a keyword as a variable name; however, you should prefer to avoid using keywords as variable names in your scripts. A list of keywords can be found in "Xbasic Keywords" in the Appendix.

A variable is implicitly defined by assigning it a value with the assignment operator (=), using it in a FOR loop statement, or declaring it as a parameter of a function.

VariableName = Expression
VariableName[Subscript] = Expression
FOR VariableName = StartValue TO EndValue
FUNCTION FunctionName AS DataType (Parameter AS DataType, Parameter AS DataType,...)

For example:

x = 3
arr[2] = "Orange"
FOR index = 1 TO 10

It is often important to explicitly define a variable before using it in a script. The DIM statement explicitly defines variables:

DIM variable_name AS data_type

For example:

DIM x AS N 'a numeric variable
DIM arr[0] AS C 'a character array
DIM args AS SQL::Arguments 'a SQL Arguments object

An explicit declaration is necessary if it is ambiguous where the variable is used or if Xbasic Strict Mode is enabled. When strict mode is enabled, all variables must be declared before they can be used.

The DIM statement is also necessary if you wish to create a complex variable, such as an array or object pointer variable.

Data Types

In the statement DIM variable_name AS data_type, the data_type declares the type of data stored in the variable. Xbasic data types can be simple types, such as character, logical, or numeric, or more complex types such as arrays, collections, objects, or function pointers. You can also declare that a variable can contain any value.

In addition to the basic types listed above, you can also declare class variables. Class variables have methods and types. The Alpha Anywhere Xbasic library includes a wide variety of classes for performing tasks, such as manipulating JSON data, calling REST services, performing SQL queries, and more. A variable declared as a class type uses the DIM statement. For example:

DIM conn AS SQL::Connection
DIM args AS SQL::Arguments

Redeclaring Variables

Once a variable's type is declared, you cannot change it. Attempting to assign a value to a variable that is not the same type as the variable causes an Xbasic error. For example, run the following Xbasic in the Interactive Window:

DIM myVar AS N
myVar = 67

myVar = now()

Note that when you execute the myVar = now() statement, an error appears in the Interactive Window:

ERROR: Variable type mismatch: Cannot assign data of type 'T' to variable of type 'N'.

Variables cannot be assigned values of another type. If you want to change the data type stored by a variable, the variable must first be deleted using the DELETE statement. After deleting the variable, you can create it again with a different data type. EG:

DELETE myVar
DIM myVar AS T
myVar = now()

When working with large variables, it can be beneficial to DELETE them when they are no longer needed. Loading files from disk, SQL query results, and data returned from web services can consume large amounts of memory.

Deleting variables is also useful when working in the Interactive Window to "reset" variables to an undefined state, ensuring that the variables contain the data you expect. For example, enter the following statements in the Interactive Window:

DIM args AS SQL::Arguments
args.set("City","Madrid")
args.set("Country","Spain")
? args.find("City")

DELETE args

DIM args AS SQL::Arguments
args.set("Country","Spain")
? args.find("City")

The first time you execute ? args.find("City"), the following object is output in the Interactive Window:

= Data = "Madrid"
IsNull = .F.
Name = "city"
Usage = 0
XML = <SQLArgument>
<Name>city</Name>
<Data Type="C">Madrid</Data>
<IsNull Type="L">0</IsNull>
<Usage>Input</Usage>
</SQLArgument>

The second time you execute ? args.find("City"), you see the following statement:

= <No data returned>

DELETE args deleted the args variable. When the args variable was then recreated using the DIM statement, the "City" argument was never created using the set() method of the args variable.

Converting Data Types

A value can be converted to other types using the convert_type() function.

DIM quantity AS N
quantity = convert_type("123","N")

convert_type() converts the value of a variable into the requested type. If data value cannot be converted to the requested type, the function will return a character value.

Values can also be implicitly converted to character strings using the concatenation operator (+). For example, run the code below in the Interactive Window:

DIM price AS N = 1.5
DIM quantity AS N = 10
DIM total AS N
total = price * quantity
? typeof(total)
totalStr = "" + total
? typeof(totalStr)

Specific functions exist for converting data to formatted character strings and converting character strings to other data types, such as date and time values. For example, the time() function converts a date or time value to a formatted character string.

For more information about converting character variables, see Character Conversion Functions.

Default Values

Variables can be assigned a default value when they are declared. Default values are used in cases where a variable may or may not exist but is required later in the script. Defining default values is also useful when working with session variables in web applications (we discuss session variables later in this guide.)

To specify a default value for a variable, use the DEFAULT keyword when the variable is declared:

DIM name AS C = DEFAULT "Steve"

Using the DEFAULT keyword to assign the initial value to a variable is similar to using the assignment operator (e.g., DIM name AS C = "Steve") to set the variable's value with one major difference: if the variable already exists, the DIM AS DEFAULT statement is ignored.

When declaring a variable with the DEFAULT keyword, Alpha Anywhere first checks to see if the variable exists. If the variable does not exist, the variable is created and assigned the specified DEFAULT value. If the variable already exists, however, the variable the existing variable is not modified.

The Interactive Window is a useful tool to help understand how the DEFAULT keyword works. Copy the following code into the Interactive Window, replacing <Your name here> with your name:

name = "<Your name here>"
today = date()
dayOfWeek = time("Weekday", today)
DIM name AS C = DEFAULT "Susan"
message = "Hello " + name + ". "
message = message + "Today is " + dayOfWeek + "."
showvar(message,"Salutations")

Run the script by selecting all of the code and using the "Run Selected Script" tool from the right-click menu. When the script executes, it creates a variable called name and sets the value of the variable to your name. When the DIM name AS C = DEFAULT "Susan" statement is processed, Alpha Anywhere ignores the statement because the variable name already exists and has a value.

Now, change the first line to the following:

DELETE name

Rerun the script. This time, when the script executes, it deletes the name variable. When the DIM name AS C = DEFAULT "Susan" statement executes, the name variable doesn't exist, so it is created and assigned the value "Susan".