Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?


Programs consist of a series of statements. Simple statements assign or retrieve values to and from variables, while complex statements like If and loops support program flow or provide powerful functionality using objects.

Expression Statements

Expression statements are used to assign values to variables or apply an operation. For example:

msg = "Hello"
result = obj.Method()
Print x

An assignment expression sets the value of a variable, array element, or object property:

var = 1
array(1) = 2
obj.Property = 3
objarray(1).Property = 4

The end of a statement is normally marked by a carriage return. You can, however, place multiple statements on the same line by placing the colon (:) character between them:

a = 1 : b = 2 : c = 3
Print a : Print " " : Print b : Print " " : Print c


The Call statement lets you call a function or method from within Basic:

Call obj.Method(a,b)

Within a Call statement, the actual “Call” token is completely optional and can be omitted:


By default, all function arguments are passed by reference within Basic. You can override this default on a argument-by-argument basis using the ByRef and ByVal directives:

obj.Method(ByRef a, ByVal b)


The If statement provides the ability to execute statements conditionally. Within Caché Basic, an If statement takes the following form:

If (expression) Then
End If

If expression evaluates to true, the body of the If statement is executed. The body of the If statement consists of a block of one or more statements between a Then and End If tokens.

There is also a simpler, single-line form of the If statement:

If (expression) Then statement()

In the single-line form, there is no End If token; the body of the If statement follows the If token and continues to the end of the line. Note that you can include multiple statements by separating them with colon (:) characters:

If (expression) Then statement1() : statement2()

An If statement make contain an Else clause:

If (expression) Then
End If

The statements within the Else block are executed if expression evaluates to False.


ElseIf is an optional statement which is part of the closest If statement. The ElseIf statement allows an If statement to sequentially test a set of expressions:

If (expression) Then
ElseIf (expression2) Then
ElseIf (expression3) Then
End If

The statements within the first If or ElseIf block whose expression is true are executed. If none are true, then the Else block is executed.


The For statement is used to repeat a sequence of statements.


The For...Next loop uses a counter to execute a block of statements a specified number of times:

For i = 1 To 10
    PrintLn i

In this case, i will be initialized to 1 and the body of the For...Next loop will be executed until i reached 10. The value of i is incremented by 1 after each iteration.

Using the Step keyword, you can increase or decrease the counter variable by the value you specify. To decrease the counter variable, use a negative Step value. You must specify an end value that is less than the start value:

For i = 10 To 1 Step -1
    PrintLn i
PrintLn "Blast Off!"

If you like (say for legibility), you can place the counter variable after the Next token:

For i = 1 To 10
    PrintLn i
Next i

Using the wrong variable after the Next token results in a syntax error.

For Each...Next

The For Each...Next repeats a group of statements for each item in a collection or each element of an array. A For Each...Next loop is similar to a For...Next loop. Instead of repeating the statements a specified number of times, a For Each...Next loop repeats a group of statements for each item in a collection of objects or for each element of an array. This is especially helpful if you don't know how many elements are in a collection.

For example, the following creates an array of ten items and then uses a For Each...Next loop to display the subscript of each item:

' Create a simple array
For i = 1 To 10
    array(i) = i * i

' Now display the subscripts and contents of the array
For Each key in array
    PrintLn key & ": " & array(key)

With a multidimensional array, this gets more interesting:

' Create a multidimensional array
For i = 1 To 5
    For j = 1 To 5
        array(i, j) = i * j
    Next j
Next i

' Now display the subscripts and contents of the array
For Each key1 in array
    For Each key2 in array(key1)
        PrintLn key1 & "," & key2 & ": " & array(key1,key2)
    Next key2
Next key1


You can use a While statement to run a block of statements an indefinite number of times:

While (expression)

The statements are repeated as long as expression is True. The end of the While block is marked by the Wend token.

For example, the following code executes its While block 9 times:

x = 1
While (x < 10)
    PrintLn x
    x = x + 1


You can use a Do...While statement to run a block of statements an indefinite number of times:

Loop While (expression)

The statements are repeated as long as expression is True. The Do...While block is contained within the Do and Loop tokens.

The Do...While statement differs from the While statement in that it executes its contents before evaluating its loop expression.

Select ... Case

The Select...Case statement lets a program choose one of several execution paths based on evaluating an expression. It is a convenient alternative to a long series of ElseIf statements.

A Select...Case statement takes the following form:

Select Case testexpression
    [Case expressionlist-n
        [statements-n]] . . .
    [Case Else expressionlist-n
End Select

The expression testexpression is evaluated and its result is then compared with each of the expressionlist values associated with each Case clause. The code block associated with the first matching Case clause is then executed. If there is no match, then the Case Else block (if present) is executed.

For example:

x = 2
Select Case x
    Case 1
        PrintLn "First case"
    Case 2
        PrintLn "Second case"
    Case Else
        PrintLn "Unknown"
End Select

There is also a simpler form of Case that can be used as an in-line expression:

Case(expr, val1:ret1, val2:ret2)

In this case (pun intended), the expression expr is first evaluated, and then its value is compared with each of a series of values (val1, val2, in this example). The value associated with the first matching value is returned.

For example:

x = 2
PrintLn Case(x,1:"hello",2:"goodbye")


To declare local variables Caché Basic supports the Dim statement. There is no need to declare variables in Caché Basic and the declaration is optional unless you include the Option Explicit clause in your program.


You can return a value from a method using the Return statement:

Method Add(a As %Integer, b As %Integer) As %Integer [language = basic]
    Return a + b

Note that it is a syntax error to use the Return statement within a method that does not return a value.