Statements and Operators

Old Content - visit altium.com/documentation

Parent page: EnableBasic

Enable Basic Statements

Do...Loop

Description
Conditional statement that repeats a group of statements while a particular condition is true, until a particular condition is met, or until an Exit Do statement is encountered.
Note that only one  instance of the [{While|Until} condition] syntax may be included in a Do...Loop structure — that is, it can be included at the Do end or the Loop end, but not both.
Syntax
Do [{While|Until} condition]
...statement to be executed...
[Exit Do]
...statement to be executed...
Loop [{While|Until} condition]

Parameters
condition - an expression that resolves to a TRUE or FALSE.
Notes
Putting a [{While|Until} condition] after the Do statement will cause the loop to test the condition before any statements in the loop are executed. If the condition is not true, then the loop is not executed at all. Putting a [{While|Until} condition] after the Loop statement allows the statement within the loop to execute once before the condition is tested.
Example
The following example displays an input dialog with the instructions to enter a number between 5 and 10. If the user enters a number that is not in this range, the Do...Loop re-displays the input dialog until a valid number is entered.

Sub Main
 Dim Value, Msg
 Do
 Value = InputBox("Enter a value from 5 to 10.")
  If Value >= 5 And Value <= 10 Then
    Exit Do         ' Exit Do...Loop.
  Else
    Beep            ' Beep if not in range.
  End If
 Loop
End Sub

End

Description
This procedure is used to end execution of a program or, with the optional keywords, mark the end of a function or procedure definition, or an If, With, Select Case or Type statement block.
Syntax
End [{Function | Sub | If | With | Select | Type}]
Parameters
This procedure takes no parameters
Notes
Using the End statement without any of the optional keywords in any function or procedure cause san immediate end to current program execution.

Exit

Description
Exits a loop, function or procedure.
Syntax
Exit {Do | For | Function | Sub }
Parameters
None
Example
This sample shows a Do ... Loop with an Exit Do statement to get out of the loop.

Sub Main ()
  Dim Value, Msg
  Do
   Value = InputBox("Enter a value from 5 to 10.")
   If Value >= 5 And Value <= 10 Then ' Check range.
      Exit Do             ' Exit Do...Loop.
   Else
      Beep                ' Beep if not in range.
   End If
  Loop
End Sub

For...Next

Description
Repeats the execution of a block of statements a specified number of times.
Syntax
For counter = StartNum% To StopNum% [Step increment%]
...statements...
Next [counter]

Parameters
counter - a variable used to contain the loop count number.
StartNum% - an integer or integer expression used as the starting number for the loop count.
StopNum% - an integer or integer expression used as the finishing number for the loop count.
increment% - optional integer or integer expression used to define the amount the counter is incremented on each loop. If this parameter is omitted, default is 1.
Notes
The initial value of counter is set to StartNum%. When the Next statement is encountered, counter is incremented by 1 (or by increment% if this parameter is specified). If counter is less than or equal to StopNum%, the statements within the loop are executed again. Loop execution continues until counter is greater than StopNum%.
Any number of For...Next loops can be nested by using different counter variables.
Example
This example shows three nested For...Next loops.

Sub main ()
 Dim x,y,z
 For x = 1 to 3
  For y = 1 to 3
   For z = 1 to 3
    Print "Looping" ,z,y,x
   Next z
  Next y
 Next x
End Sub

For Each...Next

Description
Repeats the group of statements for each element in an array of a collection.
Syntax
For Each element In group
...statements...
[Exit For]
...statements...
Next [element]

Parameters
element - a variable used to represent each element in group.
group - a variable containing an array of elements.
Notes
For Each ... Next statements can be nested if each loop element is unique. The For Each...Next statement cannot be used with an array of user defined types.
Example
This example uses the For Each procedure to step through all the elements in an array.

Sub Main
  dim z(1 to 4) as double
  z(1) = 1.11
  z(2) = 2.22
  z(3) = 3.33
  For Each v In z
    Print v
  Next v
End Sub

Function...End Function

Description
Declares and defines a procedure that can receive arguments and return a value of a specified data type.
Syntax
Function Fname [(ArgList)] [As type]
...statements...
Fname = expression
[ ...statements...
Fname = expression]
End Function

Parameters
Fname - the name of the function being defined.
ArgList - a list of variables to be passed to the function as arguments when the function is called. ArgList takes the form:
([ByVal] variable [As type] [, [ByVal] variable [As type]]...)
The optional ByVal keyword indicates that the argument is passed by value rather than by reference. The As keyword identifies the data type of the variable.
type - the data type of the value returned by the function.
expresssion - an expression that determines the return value of the function.
Notes
The Fname = expression statement sets the return value of the function. You must include at least one Fname = expression statement in a function to define its return value.
Example
The following example defines a function called SquareNum which returns the square of a number. The main procedure asks the user to enter a number and then passes the number to SquareNum and displays the return result.

Sub Main()
 Dim myInput$, mySquare, myNum
 myInput$ = InputBox("Enter Number to square.")
 If IsNumeric(myInput$) Then
  myNum = CDbl(myInput$)
  mySquare = SquareNum(myNum)                     'Call function
  MsgBox "The square of " & myNum & " is " & mySquare
 Else
  MsgBox "Sorry, you didn't enter a valid number."
 End If
End Sub
' ------------------
' Function definition for SquareNum()
' ------------------
Function SquareNum (ByVal X as Double) As Double
         SquareNum = X * X                         ' Return result
End Function

If...Then...ElseIf...Else

Description
Conditionally executes one or several statement blocks depending on whether condition is TRUE or FALSE.
Syntax
If condition Then ...statement...
If condition Then
...statement block...
[ElseIf condition2 Then
...statement block...]
[Else
...statement block...]
End If

Parameters
condition - an expression that resolves to a TRUE or FALSE value.
Notes
If there is only one statement to execute if condition is TRUE then the first described syntax may be used, which places the entire If...Then statement on a single line. For more complex structures that include multiple execution statements or the optional ElseIf and Else clauses, use the second syntax.
The optional ElseIf clause allows another condition to be tested if the initial If condition is FALSE. You may include any number of ElseIf clauses. When using multiple ElseIf clauses only the statement block associated with the first TRUE condition statement will be executed, even if subsequent conditions are also TRUE.
The optional Else clause is executed if no previous conditions were found to be TRUE.
Examples
The following example asks the user to enter a number, date or text and then determines what data type was entered.

Sub Main
 Dim myInput
 myInput = InputBox("Enter a number, date or some text")
 If IsNumeric(myInput) Then
  MsgBox "You entered a number = " & CSng(myInput)
 ElseIf IsDate(myInput) Then
  MsgBox "You entered a date  = " & CDate(myInput)
 Else
  MsgBox "You entered a string = " & myInput
 End If
End Sub

GoTo

Description
Branches unconditionally and without return to a specified label in a procedure.
Syntax
GoTo label
Parameters
label - name of a subroutine label statement within the procedure.
Notes
This statement is an unconditional jump. There is no way to return from a Goto jump. If you wish to jump to a subroutine and return, use the GoSub procedure. A label statement is marked by a label name which ends with the colon " : " character. The corresponding label parameter is the label name without the colon character.
Example
The following example uses the GoTo procedure to jump over a subprocedure definition.

Sub Main
  print "hello"
  GoSub Fred         ' Jump to Fred subroutine
  Goto TheEnd        ' Jump over Fred subroutine
  Fred:              ' Definition of Fred subroutine
    print "world"
  Return             ' End of Fred
  TheEnd:
End Sub

GoSub...Return

Description
Branches to and returns from a subroutines defined within a function or procedure.
Syntax
GoSub label
...statements...
label:
...statements...
Return

Parameters
label - name of a subroutine label statement within the procedure.
Notes
The GoSub statement allows you to jump to points within a function or procedure definition. A subroutine label statement is marked by a label name which ends with the colon " : " character. The corresponding label parameter is the label name without the colon character.
Example

The following example defines a subprocedure called Fred within the Main procedure.

Sub Main
  print "hello"
  Gosub Fred
  Exit Sub
  Fred:
    print "world"
  Return
End Sub

Select Case...End Case

Description
Executes one of the statement blocks under a Case statement based on the value of the test variable.
Syntax
Select Case TestVar
Case Val1
...statement block...
Case Val2
...statement block...
Case...
...
[Case Else]
...statement block...
End Select

Parameters
TestVar - a valid variable whose value will be tested against each Case statement.
Val1, Val2, ... - a numeric or string expression representing the test value.
Notes
In a Select Case block, the value of the TestVar is compared to the value given in each subsequent Case statement. If the value of TestVar is equal to the test value, the statement block associated with the particular Case value is executed. The optional Case Else block is executed if the value of TestVar does not equate with any of the preceding Case values.
Example
This example determines the number entered by the user.

Sub Test()
 Dim myNum
 myNum = "Loop"
 While Not(IsNumeric(myNum))
  myNum = InputBox("Enter an integer number between 1 and 5")
 Wend
 Select Case myNum
  Case 1
   MsgBox "The number is one" 
  Case 2
   MsgBox "The number is two" 
  Case 3
   MsgBox "The number is three" 
  Case 4
   MsgBox "The number is four" 
  Case 5
   MsgBox "The number is five" 
  Case Else
   MsgBox "The number wasn't between 1 and 5!"
 End Select
End Sub

Sub...End Sub

Description
Declares and defines a procedure, parameters and code.
Syntax
Sub SubName [(arglist)]
...Statements...
End Sub

Parameters
SubName - the name of the procedure. Follows standard Enable Basic naming conventions.
arglist - optional argument list. The list has the following syntax:
([ByVal] variable [As type][, ByVal] variable [As type] ...)
The optional ByVal parameter specifies that the variable is passed by value instead of by reference. The optional As parameter is used to specify the data type.
Notes
When calling a subprocedure from within a function or procedure, use the subprocedure name SubName. If the subprocedure takes parameters, include the necessary values or expressions after SubName with each parameter separated with a comma. Do not use parentheses to enclose the parameter list in a call to a subprocedure, unless you are using the optional Call keyword.
Example
The following example defines two procedures: one called Main and one called mySub that accepts two parameters passed by value. Main contains a call to mySub.

' Define the main procedure
Sub Main
   Dim a As String, b As Integer
   a = "From the main procedure"
   b = 5
   mySub a, b              ' Call mySub and pass params
   MsgBox "Back in Main"
End Sub
' Define mySub with a string and an integer parameters
Sub mySub(ByVal Param1 As String, ByVal Param2 As Integer)
   MsgBox Param1
   MsgBox "b = " & Str(Param2)
End Sub

While...Wend

Description
Continually loops through the statement block while condition is TRUE. The condition parameter is evaluated at the beginning of each loop.
Syntax
While condition
...Statement block...
Wend

Parameters
condition - any expression that evaluates to TRUE or FALSE.
Example
The following example uses a Boolean variable DoAgain to control the While loop.

Sub Main
 DoAgain = True
 While DoAgain
  UserInput = InputBox("Enter a number")
  DoAgain = Not(IsNumeric(UserInput))
 Wend
 MsgBox "You entered the number " & UserInput
End Sub

The following example uses a numeric comparison expression to control the While loop.

Sub Main
 Dim x As Integer
 x = 0
 While x < 10
  MsgBox "x is currently " & x
  x = x +2
 Wend
 MsgBox "x has reached " & x
End Sub

With...End With

Description
With procedure allows you to perform a series of commands or statements on a particular object without again referring to the name of that object. With statements can be nested by putting one With block within another With block. Fully specify any object in an inner With block to any member of an object in an outer With block.
Syntax
With object
...statements...
End With

Parameters
object - a valid object, such as a user-defined variable object or dialog box object.
Notes
The With procedure is useful for simplifying coding when writing a series of statements that reference different elements or properties of a single object.
Within the With statement block you can refer to elements or properties of object directly without having to use the object name. For example, if you have defined a dialog box that contains two checkboxes with the identifiers .CheckMe1 and .CheckMe2 and then dimensioned an object variable myDlg to refer to the dialog box, you could refer to the value of the checkboxes normally using the syntax myDlg.CheckMe1 and myDlg.Checkme2. If you use the With statement of the form With myDlg, you could then refer to the values of the checkboxes using .CheckMe1 and .CheckMe2 within the With block.
Example
The following example creates two user-defined variable types and then uses the With statement block to reference the elements within each data type.

Type type1          ' Define a user data type
    a As Integer    ' with multiple elements.
    d As Double
    s As String
End Type 
Type type2          ' Define a second user data type
    a As String
    o As type1
End Type
Dim type1a As type1 ' Declare object variables as
Dim type2a As type2 ' user data types.
' -------------------------------------------------------
Sub Main ()
    With type1a     ' Use With to reference the object.
      .a = 65       ' You can now refer to elements of the
      .d = 3.14     ' object by their identifiers.
    End With
    With type2a
      .a = "Hello, world"
      With .o       ' Nested With statement
        .s = "Goodbye"
      End With
   End With
   type1a.s = "YES"
   MsgBox type1a.a
   MsgBox type1a.d
   MsgBox type1a.s
   MsgBox type2a.a
   MsgBox type2a.o.s
End Sub

 

Enable Basic Operators

In an Enable Basic macro script, an operator is a character or set of characters that tells the interpreter to perform some action on one or more stated values. For example, the " * " character is used in Enable Basic to multiply two numbers together.

Arithmetic Operators

The following is a list of arithmetic operators that can be used in Enable Basic, listed in the order of precedence in which they are executed:

Operator

Usage

Function

^

x = y^z

Exponentiation: x is y raised to the power of z

-

x = -y

Negation: x is the negative value of y

*

x = y * z

Multiplication: x is y multiplied by z

/

x = y/z

Division: x is y divided by z. Note: if z=0 a divide by zero error will occur.

Mod

x = y Mod z

Modulo: x is the remainder when y (rounded to an integer) is divided by z (rounded to an integer). Mod always returns an integer value.

+

x = y + z

Addition: x is y plus z.

-

x = y - z

Subtraction: x is y minus z

Comparison Operators

The following is a list of comparison operators that can be used in Enable Basic, listed in the order of precedence in which they are executed:

Operator

Usage

Function

<

x < y

Less than: Returns TRUE if x is less than y, otherwise returns FALSE.

<=

x <= y

Less than or equal to Returns TRUE if x is less than or equal to y, otherwise returns FALSE.

=

x = y

Equals: Returns TRUE if x is equal to y, otherwise returns FALSE.

>

x >= y

Greater than or equal to: Returns TRUE if x is greater than or equal to y, otherwise returns FALSE.

>

x > y

Greater than: Returns TRUE if x is greater than y, otherwise returns FALSE.

<>

x <> y

Not equal to: Returns TRUE if x is not exactly equal to y, otherwise returns FALSE.

Comparison operators return a Boolean TRUE or FALSE which can be used as a test condition in conditional statements. Comparison operators also work with String values. In this case, the determination a "greater than" or "less than" condition is based on how the strings would compare in an alphabetical listing. String comparisons are not case sensitive — that is, "abc" = "ABC".

Concatenation Operators

The following is a list of string concatenation operators that can be used in Enable Basic, listed in the order of precedence in which they are executed:

Operator

Usage

Function

&

x & y

Joins the characters of string x to the characters of string y. If x or y are not string data types, they will be converted.

+

x + y

Joins the characters of string x to the characters of string y only if both x and y are string data types. If x or y is a number, the expression is treated as numerical and the operator acts as the numerical plus. Note: In numerical calculations, strings are converted to 0 unless they begin with a valid number, in which case they take the value of the number.

Logical Operators

The following is a list of logical or Boolean operators that can be used in Enable Basic, listed in the order of precedence in which they are executed:

Operator

Usage

Function

AND

x AND y

Logical And: Returns TRUE if both x and y are TRUE, otherwise returns FALSE.

OR

x Or y

Logical Or: Returns FALSE if both x and y are FALSE, otherwise returns TRUE.

Note
x and y must be expressions that return a Boolean TRUE or FALSE value.
The Not function can be used to return the Boolean opposite of a logical value.

Using Different Number Bases

Enable Basic supports three representations of numbers: Decimal, Octal and Hexadecimal. To use Octal (base 8) or hexadecimal (base 16) numbers in a script, prefix the number with &O or &H respectively.

Operator Precedence

The following list shows the order of precedence of execution of Enable Basic operators:

Operator

Description

Order

()

parenthesis

highest

^

exponentiation

 

-

negation

 

/, *

division/multiplication

 

Mod

modulo

 

+, -

addition, subtraction

 

&, +

concatenation

 

=, >, <, <=, >=

relational

 

AND

and

 

OR

or

lowest

You are reporting an issue with the following selected text and/or image within the active document:
ALTIUM DESIGNER FREE TRIAL
Altium Designer Free Trial
Let’s get started. First off, are you or your organization already using Altium Designer?

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

In that case, why do you need an evaluation license?

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

Got it. You actually don’t need an evaluation license for that.

Click the button below to download the latest Altium Designer installer.

Download Altium Designer Installer

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

Please fill out the form below to get a quote for a new seat of Altium Designer.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

If you are on Altium Subscription, you don’t need an evaluation license.

If you are not an active Altium Subscription member, please fill out the form below to get your free trial.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

Why are you looking to evaluate Altium Designer?

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

You came to the right place! Please fill out the form below to get your free trial started.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

Sounds exciting! Did you know we offer special discounted student licenses? For more information, click here.

In the meantime, feel free to request a free trial by filling out the form below.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

Got it. You can download a free Altium Designer Viewer license which is valid for a 6 months.

Please fill out the form below to request one.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

That’s great! Making things is awesome. We have the perfect program for you.

Upverter is a free community-driven platform designed specifically to meet the needs of makers like you.

Click here to give it a try!

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

Got it. You can download a free Altium Designer Viewer license which is valid for a 6 months.

Please fill out the form below to request one.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.