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: