Keywords

Old Content - visit altium.com/documentation

Parent page: EnableBasic

This reference covers the Enable Basic keywords used for the Scripting System in Altium Designer.

Reserved words in Enable Basic

The following words are reserved in Enable Basic and cannot be used for variable names.
A, B
Abs, AppActivate, Asc, Atn, Append, As, Base, Beep, Begin, Binary, ByVal
C
Call, Case, ChDir, ChDrive, Chr, Const, Cos, CurDir, Ctype, CDbl, CInt, Clng, Csng, CStrg, Cvar, Close, CheckBox
D, E
Date, Day, Declare, Dim, Dir, Do...Loop, Dialog, DDEInitiate, DDEExecute, End, Exit, Exp
F, G, H
FileCopy, FreeFile, For...Next, Format, Function, GoTo, Global, Hex$, Hour
I, J, K
If...Then...Else...[End If], InputBox, InStr, Int, IsNull, Integer, IsEmpty, IsNull, IsNumeric, IsDate, Kill
L, M, N
LBound, LCase, Left, Len, Let, Log, Ltrim, Mid, MkDir, Month, MsgBox
O, P, Q
Oct, Open, OKButton, Object, Option, Print
R, S, T
Rem, RmDir, Rnd, Return, Rtrim, SendKeys, Set, Second, Select, Shell, Sin, Sqr, Stop, Str, Tan, Text, TextBox, Time, Type, Trim, Trim$ To, Time, Then, Tan
U, V, W, X, Y, Z
UBound, UCase, UCase$, Val, Variant, VarType, Write #

 

Enable Basic Keywords

Abs

Description
Returns the absolute value of a number. The data type of the return value is the same as that of the number argument. However, if the number argument is a Variant of VarType String and can be converted to a number, the return value will be a Variant of VarType Double.
Syntax
Abs(number)
Parameters
number - a variable, constant or expression which returns a valid number.
Example
The following example uses an input box to ask the user to enter a number, and then displays the absolute value of the number.

Sub Main
 Dim Msg, X, Y
 X = InputBox("Enter a Number:")
 Y = Abs(X)
 Msg = "The number you entered is " & X
 Msg = Msg & ". The Absolute value of " & X & " is " & Y
 MsgBox Msg ' Display Message.
End Sub

AppActivate

Description
Activates a currently open application.
Syntax
AppActivate ApplicationName$
Parameters
ApplicationName$ - a string or string expression that resolves to the name that appears in the title bar of the application window to activate.
Notes
The AppActivate procedure is only applicable to applications which are currently running. To run a program, use the Shell function.
Example
This example changes the Windows Calculator mode.

Sub Main ()
 Ent = Chr(32)                   ' Define the enter key
 X = Shell("Calc.exe", 1)        ' Run the  Calculator
 MsgBox "Change to Scientific mode"
 AppActivate "Calculator"        ' Ensure Calc visible
 SendKeys "%" + Ent + "R", True
 SendKeys "%VS", True            ' Activate scientific
 MsgBox "Change to Standard mode"
 AppActivate "Calculator"        ' Focus Calculator
 SendKeys "%VT", True            ' Activate standard
End Sub

Atn

Description
Returns the arc tangent of a number.
Syntax
Atn(number)
Parameters
number - a numeric variable, constant or expression.
Notes
The return result is a numeric value representing the arc tangent of number expressed in radians. The function will by default return a Double data type unless a Single or Integer is specified as the return value.
Example
The following example displays a message dialog showing the value of Pi.

Sub AtnExample ()
 Dim Msg, Pi               ' Declare variables.
 Pi = 4 * Atn(1)           ' Calculate Pi.
 Msg = "Pi is equal to " & Str(Pi)
 MsgBox Msg                ' Display results.
End Sub

Asc

Description
Returns a numeric value that is the ASCII code for the first character in String$.
Syntax
Asc(String$)
Parameters
String$ - a character string or string expression.
Notes
If String$ contains more than one character, Asc only returns the ASCII code for the first character in the string. To convert an ASCII code to its corresponding character, use the Chr function.
Example
The following example displays a message dialog containing all the letters of the alphabet.

Sub Main ()
 Dim I, Msg                   ' Declare variables.
 For I = Asc("A") To Asc("Z") ' From A through Z.
  Msg = Msg & Chr(I)          ' Create a string.
 Next I
 MsgBox Msg                   ' Display results.
End Sub

Beep

Description
Sounds a tone through the computer's speaker.
Syntax
Beep
Parameters
This procedure accepts no parameters.
Notes
The frequency and duration of the beep depends on hardware, which may vary among computers.
Example
The following example prompts the user to enter a number between 1 and 3. If the user enters a number out of this range, the computer will beep and display a message.

Sub BeepExample ()
 Dim Answer, Msg              ' Declare variables.
 Do
  Answer = InputBox("Enter a value from 1 to 3.")
  If Answer >= 1 And Answer <= 3 Then ' Check range.
   Exit Do                    ' Exit Do...Loop.
  Else
   Beep                       ' Beep if not in range.
  End If
 Loop
 MsgBox "You entered a value in the proper range."
End Sub

Call

Description
Activates an Enable Basic subroutine called SubName or a DLL function within the dynamic linked library called SubName.
Syntax
[Call] SubName [(parameter list)]
Parameters
SubName - the name of the function or procedure to call.
parameter list - a comma-delimited list of arguments to pass to the called function or procedure.
Notes
Use of the Call keyword is optional when calling an Enable Basic subprocedure, user-defined function or a DLL function, and is only included for compatibility with some older versions of Enable Basic.
Note that parentheses must always be used to enclose the argument list if the Call syntax is being used.
Example
This example uses the Call statement to the DisplayMsg subprocedure and then calls the same procedure without the Call statement. Note that when the Call statement is used, the parameter list for a subprocedure must be enclosed in parentheses.

Sub Main ()
 Dim Msg As String
 Msg = "Answering a call"
 Call DisplayMsg(Msg)     ' Using the Call statement.
 DisplayMsg Msg           ' Not using the Call statement.
End Sub
Sub DisplayMsg(ByVal myString As String)
 MsgBox myString
End Sub

CBool

Description
Converts expression to a Boolean TRUE or FALSE
Syntax
CBool(expression)
Parameters
expression - a valid numeric expression.
Notes
The function returns a Boolean data type, which is either TRUE or FALSE.
If expression is numeric, the function returns FALSE if expression = 0, or TRUE if expression = any non-zero number.
If expression is a string, the function converts the string to a numeric value before conversion to a Boolean.

Example
The following example shows how different expressions are converted to a Boolean TRUE or FALSE.

Sub Main
 Print CBool(0)         ' Returns FALSE
 Print CBool(1)         ' Returns TRUE
 Print CBool(345.778)   ' Returns TRUE
 Print CBool(-255)      ' Returns TRUE
 Print CBool("Hello")   ' Returns FALSE
 Print CBool("0 volts") ' Returns FALSE
 Print CBool("5 volts") ' Returns TRUE
End Sub

CDbl

Description
Converts expression to a Double data type. The Double data type represents a double-precision floating point number.
Syntax
CDbl(expression)
Parameters
expression - a valid string or numeric expression.
Example
This example converts a single precision integer y to a double precision number x.

Sub Main ()
 Dim y As Integer
 y = 25
 If  VarType(y) = 2 Then
  Print y
  x = CDbl(y)   ' Converts the integer value of y to
                ' a double value in x
  Print VarType(x)
 End If
End Sub

CInt

Description
Converts any valid expression to an integer.
Syntax
CInt(expression)
Parameters
expression - any valid expression.
Notes
The function returns an Integer data type derived from the expression parameter. If expression is a floating point number, then the return value is the rounded integer value of the number. If expression is a string, the return value is 0, except when the string starts with a number, in which case the return value is the rounded value of the number. If expression is a Boolean True, the return value is -1. If expression is a Boolean False, the return value is 0.
Example
The following example shows the return values of the CInt function for various expression types.

Sub Main ()
 MsgBox CInt(2.45)      ' Returns 2
 MsgBox CInt(2.55)      ' Returns 3
 MsgBox CInt("Text")    ' Returns 0
 MsgBox CInt("A5")      ' Returns 0
 MsgBox CInt("5A")      ' Returns 5
 MsgBox CInt(True)      ' Returns -1
 MsgBox CInt(False)     ' Returns 0
End Sub

CLng

Description
Converts any valid expression into a long integer.
Syntax
CLng(expression)
Parameters
expression - any valid expression.
Notes
The function returns a Long data type derived from the expression parameter. If expression is a floating point number, then the return value is the rounded integer value of the number. If expression is a string, the return value is 0, except when the string starts with a number, in which case the return value is the rounded integer value of the number. If expression is a Boolean True, the return value is -1. If expression is a Boolean False, the return value is 0.
Example
The following example shows the return values of the CLng function for various expression types.

Sub Main ()
 MsgBox CLng(2.45)      ' Returns 2
 MsgBox CLng(2.55)      ' Returns 3
 MsgBox CLng("Text")    ' Returns 0
 MsgBox CLng("A5")      ' Returns 0
 MsgBox CLng("5A")      ' Returns 5
 MsgBox CLng(True)      ' Returns -1
 MsgBox CLng(False)     ' Returns 0
End Sub

Const

Description
Assigns a symbolic name to a constant value. A constant must be defined before it is used.
Syntax
[Global] Const Name = Expression
Parameters
Name - the name of the variable
Expression - an expression that defines the constant.
Notes
Defining a Const outside a procedure or at the module level automatically declares the constant to be global. The use of the Global prefix is not necessary, but is retained for compatibility with earlier versions of Enable Basic. If a constant is defined within a function or procedure, it is local to that function or procedure.
A type declaration character may be used in the Name parameter, however if none is used Enable Basic will automatically assign a data type to the constant: Long (if it is a long or integer), Double (if a decimal place is present), or a String (if it is a string).
Example
In the following example, GloConst and MyConst are defined as global constants (note that outside of a procedure definition Const and Global Const are equivalent) and PI is defined as local to the Main procedure.

Global Const GloConst = 142 ' Global to all 
Const MyConst = 122         ' procedures in a module
Sub Main ()
 Const PI = 3.14159         ' Local constant
 Myvar = MyConst + PI + GloConst
 Print MyVar
End Sub

CreateObject

Description
Creates an OLE automation object.
Syntax
CreateObject(class)
Parameters
class - a valid OLE class object.
Example
This example creates a letter in Microsoft Word using Word Basic and OLE.

Sub Main ()
 Dim word As object
 Set word = CreateObject("Word.Basic")
 word.FileNewDefault
 word.Insert "Dear Sir:"
 word.InsertPara
 word.InsertPara
 word.Insert "The letter you are reading was"
 word.Insert "created with Enable Basic."
 word.InsertPara
End Sub

CSng

Description
Converts any valid expression to a Single.
Syntax
CSng(expression)
Parameters
expression - any valid expression.
Notes
The function returns a single precision number derived from the expression parameter. If expression is a number, then the return value is the single precision value of the number. If expression is a string, the return value is 0, except when the string starts with a number, in which case the return value is the value of the number. If expression is a Boolean TRUE, the return value is -1. If expression is a Boolean FALSE, the return value is 0.
Example
The following example shows the return values of the CSng function for various expression types.

Sub Main ()
 MsgBox CSng(2.45)      ' Returns 2.450000
 MsgBox CSng("Text")    ' Returns 0.000000
 MsgBox CSng("A5")      ' Returns 0.000000
 MsgBox CSng("5A")      ' Returns 5.000000
 MsgBox CSng(True)      ' Returns –1.000000
 MsgBox CSng(False)     ' Returns 0.000000
End Sub

CStr

Description
Converts any valid expression to a String.
Syntax
CStr(Expression)
Parameters
Expression - any valid expression.

Declare

Description
The Declare procedure makes a reference to an external procedure in a Dynamic Link Library (DLL).
Syntax
Declare Sub ProcName Lib LibName$ [Alias AliasName$] ([argument list])
Declare Function ProcName Lib LibName$ [Alias AliasName$] ([argument list]) [As Type]
Declare Function ProcName App [Alias AliasName$] ([argument list]) [As Type]

Parameters
ProcName - the name of the function or subroutine being called.
LibName$ - string containing the name of the DLL that contains the procedure.
AliasName$ - string containing the actual procedure name in the DLL. If different from the name specified by the ProcedureName parameter argument list then the optional argument list needs to be passed the format is as follows: ([ByVal] variable [As Type],... )
The optional ByVal keyword specifies that the variable is passed by value instead of by reference.
Type - defines the data type the function returns.
Notes
When declaring a procedure that has no arguments, include empty double parentheses () to assure that no arguments are passed. For example: Declare Sub OnTime Lib "Check" ()
The third version of the syntax listed makes a reference to a function located in the executable file located in the application where Enable Basic is embedded.
Example
The following statement declares a function residing in User.dll called GetFocus that takes no parameters and returns an integer value.
Declare Function GetFocus Lib "User" () As Integer
The following statement declares a function residing in User.dll called GetWindowText that takes the parameters hWnd%, Mess$, cbMax%, which are passed as values and returns an integer.
Declare Function GetWindowText Lib "User" (ByVal hWnd%, _ByVal Mess$, ByVal cbMax%) As Integer

Dim

Description
The first listed syntax allocates storage for and declares the data type of variables and arrays in a module. The second listed syntax is used to assign an object variable to represent the values of the controls in a user-defined dialog box. The dialog box represented by DlgName must be defined using the Begin Dialog ... End Dialog procedures.
Syntax
Dim VarName[(subscripts)] [As Type]
Dim DlgObject As DlgName

Parameters
VarName - the name of the variable.
subscripts - subscript dimensions used when dimensioning an array. subscripts must be of the form (Dim1, Dim2, ...), where Dim1, etc are the number of items in each array dimension.
Type - the data type declaration of the variable.
DlgObject - the name of an Object variable to hold the dialog record.
DlgName - the name of the dialog as specified in a dialog definition.
Notes
You can dimension more that one variable in a single Dim statement by separating each variable definition by a comma. If the optional As Type clause is omitted, the variable is defined as a Variant data type.
In Enable Basic, it is not necessary to define a variable with the Dim statement before using it. Using a variable in an assignment-type statement will create the variable.
Using the Dim procedure outside a function or procedure defines variables as Global.
Example
The following statement dimensions variable a as Double:
Dim a As double
The following statement dimensions Y as Integer, Z as Single and S as a String:
Dim Y As Integer, Z As Single, S As String
The following statements are equivalent, and dimensions V as a Variant:
Dim V As Variant
Dim V
The following statement creates a two-dimensional array of Integers, the first dimension having 3 elements and the second having 10 elements:
Dim MyList(2, 9) As Integer
The following subprocedure dimensions an object variable MyDlg to represent the dialog control values of a user-defined dialog called DialogBox1:

Sub Main()
 ' Begin dialog definition
 Begin Dialog DialogBox1 58,60, 161, 65, "Enter your name"
  Text 2,2,64,12, "Type your name:"
  TextBox 6,14,148,12, .nameStr
  OKButton 16,48,40,12
  CancelButton 60,48,36,12
 End Dialog
 ' End of dialog definition
 Dim MyDlg As DialogBox1    ' Dimension object variable for dialog.
 Dialog MyDlg               ' Display the dialog.
 MsgBox MyDlg.nameStr       ' Display the text from the dialog text box.
End Sub

IsEmpty

Description
Returns a value that indicates whether a variable has been initialized.
Syntax
IsEmpty(VarName)
Parameters
VarName - a valid variable name.
Notes
When a numeric or variant type variable is first declared in Enable Basic, it is empty. You can set a variable to be empty using the statement VarName = Empty. The function returns a Boolean TRUE if VarName is empty, otherwise it returns a FALSE.

IsNull

Description
Returns a value that indicates whether a numeric variable contains the NULL value.
Syntax
IsNull(VarName)
Parameters
VarName - a valid variable name.
Notes
The function returns a Boolean TRUE if VarName contains the NULL value. If IsNull returns a FALSE the variant expression is not NULL. The NULL value is a special value that indicates a variable contains no data. This is different from a null-string, which is a zero length or empty string which has not yet been initialized.

IsNumeric

Description
Indicates if the expression can be converted to a numeric data type.
Syntax
IsNumeric(expression)
Parameters
expression - any valid Enable Basic expression.
Notes
The function returns a Boolean TRUE if the expression can be resolved to a numeric value, otherwise it returns a false.
Example
The following example checks whether the value entered into an input box is a valid number.

Sub Form_Click ()
 Dim TestVar                          ' Declare variable.
 TestVar = InputBox("Enter a number, letter, or symbol.")
 If IsNumeric(TestVar) Then           ' Evaluate variable.
  MsgBox "Entered data is numeric."   ' Message if number.
 Else
  MsgBox "Entered data is not numeric." ' Message if not.
 End If
End Sub

Int

Description
Returns the integer portion of a number.
Syntax
Int(num)
Parameters
num - a number or numeric expression.
Notes
The function does not perform any rounding, but returns an Integer data type which is the integer portion of number.
This function is identical to the Fix function.

InStr

Description
Returns the character position of the first occurrence of SearchString$ within SourceString$.
Syntax
InStr(numBegin, SourceString$, SearchString$)
Parameters
numBegin - a valid positive integer expression between 1 and 65,535 that sets the starting character for the search.
SourceString$ - a string expression that is the string to be searched.
SearchString$ - a string expression that to be used as the search string.
Notes
The numBegin parameter is NOT optional. Set the parameter to 1 to search the entire SourceString$.
The function returns an Integer data type that is the starting position of SearchString$ within SourceString$. The first character in SourceString$ has a value of 1. If SearchString$ is not found, the function returns 0. The search is case sensitive.
Example
The following example performs two searches on the string "Good Bye". The first looks for "Bye" starting from the first character of the string. The second searches for "Good" starting from the 5th character of the string.

Sub Main ()
 B$ = "Good Bye"
 A% = InStr(1, B$, "Bye")   ' Returns 6.
 C% = Instr(5, B$, "Good")  ' Returns 0 as the search is
                            ' is started from the 5th
                            ' character of Good Bye.
 MsgBox A$
 MsgBox B$
End Sub

InputBox

Description
Opens a dialog box that allows user input. The dialog contains a prompt string, text entry box, OK and Cancel buttons.
Syntax
InputBox(prompt$[, title$][, default$][, PosX, PosY])
Parameters
prompt$ - a string expression displayed in the input box as a prompt to the user.
title$ - a string expression to be displayed in the title bar of the input box.
default$ - a string expression to be used as the default input text.
PosX, PosY - x and y coordinates defining the location of the top left corner of the input dialog box in pixels relative to the top left corner of the Altium Designer window.
Notes
If the user presses the OK button, the function returns a string that entered into the input box by the user. If the user presses the Cancel button, a null string is returned.
Example
The following example asks the user to enter their name and then displays the name in a message dialog.

Sub Main ()
 myTitle$ = "Greetings"
 myPrompt$ = "What is your name?"
 myDefault$ = ""
 X% = 200
 Y% = 100
 N$ = InputBox(myPrompt$, myTitle$, myDefault$, X%, Y%)
 MsgBox "Hello " & N$
End Sub

GetObject

Description
Retrieves an object or object class from a file.
Syntax
GetObject(FileName$[, class$])
Parameters
FileName$ - a string expression containing the name and path of the file containing the object to retrieve. If FileName$ is an empty string then class is required.
class - a string expression containing the class name of the object to retrieve.

Hex

Description
Hex returns a String data type which represents the hexadecimal number. The hexadecimal value is based on a decimal integer parameter.
Syntax
Hex(num)
Parameters
num - a number or numeric expression. The parameter is rounded to the nearest integer value before conversion.
Example
Hex conversion example.

Sub Main () 
 Dim Msg As String, x%
 x% = 10
 Msg =Str( x%) &  " decimal is "
 Msg = Msg & Hex(x%) & " in hex "
 MsgBox Msg
End Sub

Format

Description
Formats a string or number for display using the fmt$ parameter as a template.
Syntax
Format(expression [, fmt$])
Parameters
expression - any valid expression.
fmt$ - a string or string expression that contains a pre-defined Enable Basic format name, or a user-defined format string.
Notes
This function returns a String data type which contains the value of expression formatted according to the fmt$ parameter. If the fmt$ parameter is omitted or is zero-length and the expression parameter is numeric, Format provides similar functionality to the Str function by converting the numeric value to a String data type. However, positive numbers converted using Format lack the leading space reserved for displaying the sign of the value, whereas those converted using Str retain the leading space.
Example
This example shows various uses of the Format function to format values using both named and user-defined formats. For the date separator (/), time separator (:) and AM/PM literal, the actual formatted output displayed by your system depends on the locale settings on which the code is running. When times and dates are displayed in the development environment, the short time and short date formats of the code locale are used. When displayed by running code, the short time and short date formats of the system locale are used, which may differ from the code locale. For this example, English/United States is assumed.

Sub Main
 ' Returns current time in the system short & long time format.
 MsgBox Format(Time, "Short Time")
 MsgBox Format(Time, "Long Time")
 ' Returns current date in the system short & long date format.
 MsgBox Format(Date, "Short Date")
 MsgBox Format(Date, "Long Date")
 '------------------------------------
 MyTime = "08:04:23 PM"
 MyDate = "January 27, 1993"
 MsgBox Format(MyTime, "h:n:s")           ' Returns "20:4:23"
 MsgBox Format(MyTime, "hh:nn:ss")        ' Returns "20:04:23 "
 MsgBox Format(MyDate, "dddd, mmm d yyyy")' Returns 
                                          ' "Wednesday, Jan 27 1993"
                                          '
 ' If a format string is not supplied, a simple string is returned.
 MsgBox Format(23)                       ' Returns "23".
 ' Example number formats
 MsgBox Format(5459.4, "##,##0.00")      ' Returns "5,459.40"
 MsgBox Format(334.9, "###0.00")         ' Returns "334.90"
 MsgBox Format(5, "0.00%")               ' Returns "500.00%"
 ' Example text formats
 MsgBox Format("HELLO", "<")             ' Returns "hello"
 MsgBox Format("This is it", ">")        ' Returns "THIS IS IT"
End Sub

Pre-defined formats for fmt$

To use one of the Enable Basic pre-defined formats, include the format name as the fmt$ parameter in a Format statement.

Predefined Numeric Formats

Enable Basic predefined number format names:

fmt$ =

Description

"General"

Display the number as is, with no thousand Separators

"Fixed"

Display at least one digit to the left and two digits to the right of the decimal separator.

"Standard"

Display number with thousand separator and two digits to the right of the decimal separator.

"Percent"

Multiplies the number by 100 and displays it with two decimal places and a percent sign (%) appended to the end.

"Scientific"

Standard scientific notation.

"True/False"

Displays False if number is 0, otherwise displays True.

Predefined Date & Time Formats

Enable Basic predefined date & time format names:

fmt$ =

Description

"Long Date"

Display a Long Date, as defined in the International section of the Control Panel.

"Medium Date"

Display a date in the same form as the Short Date, but with the month shown as abbreviation, rather than a number.

"Short Date"

Display a Short Date, as defined in the International section of the Control Panel.

"Long Time"

Display a Long Time, as defined in the International section of the Control panel. Long Time includes hours, minutes, seconds.

"Medium Time"

Display time in 12-hour format using hours and minutes and the Time AM/PM designator.

"Short Time"

Display time using the 24-hour format (e.g. 17:45)

Creating User Defined Format Strings for fmt$

To create your own formats, define a string that includes special formatting characters and acts as a "template" for formatting the supplied expression.

  • A format string for numbers can have up to three sections separated by semicolons. These sections are: "Default number format[; Negative values][; Zero values]"
  • A format string for text can have up to two sections: "Default string format[; Null string values]"
  • Date and time format strings have only one section.

To construct each section of the formatting string, use the formatting characters listed below:

Special Characters for Number Format Strings

The following characters are used to define number formatting strings:

Character

Meaning

0

Digit placeholder. If there is no corresponding digit in the format expression, leading and/or trailing zeroes will be added. When used to the left of the decimal placeholder, indicates the number of decimal places displayed.

#

Optional Digit placeholder. If there is a digit in the corresponding placeholder position, it is displayed. Otherwise no digit is displayed.

.

Decimal placeholder.

%

Percentage placeholder. The percent character (%) is inserted in the position where it appears in the format string. When this character is used, the expression is multiplied by 100.

,

Thousand separator. Indicates that a comma is to be inserted between each group of three digits to the left of the decimal point. The character must have a digit placeholders (0 or #) on either side of it in the format string.

E+, e+
E-, e-

Scientific format. If the format expression contains at least one digit placeholder (0 or #) to the right of E-,E+,e- or e+, the number is displayed with "E" or "e" inserted between the number and its exponent. The number of digit placeholders to the right determines the number of digits in the exponent. Use E- or e- to place a minus sign next to negative exponents. Use E+ or e+ to place a plus sign next to positive exponents.

\

Interprets the next character in the format string as a literal. The backslash itself isn't displayed. Use this to display the special formatting characters as text in the output format. To display a backslash, use two backslashes (\\).

*

Display the next character as the fill character. Any empty space in a field is filled with the character following the asterisk.

Special Characters for Date & Time Format Strings

The following characters are used to define date and time formatting strings:

Character

Meaning

/

Date separator. The actual character used as the date separator in the formatted out depends on the system date format.

:

Time separator. The actual character used as the time separator depends on the system time format.

c

Displays the date as dddd and displays the time as ttttt.

d

Display the day of the month as a number without a leading zero (1-31)

dd

Display the day of the month as a number with a leading zero (01-31)

ddd

Display the day of the week as an abbreviation (Sun-Sat).

ddddd

Display a date serial number as a complete date (including day , month, and year).

w

Display the day of the week as a number (1- 7 ).

ww

Display the week of the year as a number (1-53).

m

Display the month as a number without a leading zero (1-12). If m immediately follows h or hh, the minute rather than the month is displayed.

mm

Display the month as a number with a leading zero (01-12). If mm immediately follows h or hh, the minute rather than the month is displayed.

mmm

Display the month as an abbreviation (Jan-Dec).

mmmm

Display the month as a full month name (January-December).

q

display the quarter of the year as a number (1-4).

y

Display the day of the year as a number (1-366).

yy

Display the day of the year as a two-digit number (00-99)

yyyy

Display the day of the year as a four-digit number (100-9999).

h

Display the hour as a number without leading zeros (0-23).

hh

Display the hour as a number with leading zeros (00-23).

n

Display the minute as a number without leading zeros (0-59).

nn

Display the minute as a number with leading zeros (00-59).

s

Display the second as a number without leading zeros (0-59).

ss

Display the second as a number with leading zeros (00-59).

ttttt

Display a time serial number as a complete time (including hour, minute, and second) formatted using the system time separator.

AM/PM

Use the 12-hour clock and displays an uppercase AM/PM

am/pm

Use the 12-hour clock and displays a lowercase am/pm

A/P

Use the 12-hour clock and displays a uppercase A/P

a/p

Use the 12-hour clock and displays a lowercase a/p

AMPM

Use the 12-hour clock and displays the system am/pm designators.

Special Characters for Text Format Strings

Character

Meaning

@

Character placeholder. Displays a character or a space. Placeholders are filled from right to left unless there is an
! character in the format string.

&

Character placeholder. Display a character or nothing.

<

Force lowercase.

>

Force uppercase.

!

Force placeholders to fill from left to right instead of right to left.

Fix

Description
Returns the integer portion of a number.
Syntax
Fix(number)
Parameters
number - a number or numeric expression.
Notes
This function does not perform any rounding, it returns the integer portion of the number.
This function is identical to the Int function.

LBound

Description
Returns the smallest available subscript for the dimension of the indicated array.
Syntax
LBound(array [, dimension])
Parameters
array - a valid array name, excluding parentheses.
dimesion - a optional numeric expression representing an array dimension of a multi-dimensional array. The first dimension of an array is 1, the second 2, etc.
Notes
If dimension is omitted and array has more than one dimension, the lower bound for the first dimension is returned.
Example
The following example displays the upper and lower bounds for each dimension of a two-dimensional array.

Sub Main()
 Dim myArray(2 To 6, 4 To 8)
 Dim Low1, Low2, Up1, Up2, Msg
 Low1 = LBound(myArray)
 Up1 = UBound(myArray)
 Low2 = LBound(myArray, 2)
 Up2 = UBound(myArray, 2)
 MsgBox "First dimension goes from element " & Low1 & " to " & Up1
 MsgBox "The 2nd dimension goes from element " & Low2 & " to " & Up2
End Sub

Let

Description
Assigns a value to a variable.
Syntax
[Let] VarName = expression
Parameters
VarName - a valid variable name.
expression - any Enable Basic expression.
Notes
Let is an optional keyword which is retained for compatibility with older versions of Enable Basic.

MsgBox

Description
Displays a message in a dialog box and waits for the user to click a button on this dialog.
Syntax
MsgBox Msg$, [TypeNum] [, Title$]
Var = MsgBox(Msg$, [TypeNum] [, Title$])

Parameters
Msg$ - a string expression which gives the message to display in the message box.
TypeNum - an optional numeric expression that defines the buttons, icons and behavior of the message box. For a list of valid numbers, see below. The default is 0.
Title$ - an optional string expression that defines the text to appear in the title bar of the message box.
Notes
The function form of MsgBox returns an Integer data type indicating which button the user presses:
1 = OK; 2 = Cancel; 3 = Abort; 4 = Retry; 5 = Ignore; 6 = Yes; 7 = No
When using the procedure form of MsgBox, you can display the various buttons by setting TypeNum, but there is no way to determine which button the user presses.
Example
This example displays a series of message dialogs with different button combinations. When the user clicks a button, the program displays a message dialog with an information icon telling the user which button was pressed.

Sub Main
 For myCount = 1 to 5
  Msg$ = "TypeNum = " & myCount & Chr(10) & "Select a button"
  ButNum = MsgBox(Msg$, myCount, "Test") ' Message box function
  Select Case ButNum
   Case 1
    ButName$ = "OK"
   Case 2
    ButName$ = "Cancel"
   Case 3
    ButName$ = "Abort"
   Case 4
    ButName$ = "Retry"
   Case 5
    ButName$ = "Ignore"
   Case 6
    ButName$ = "Yes"
   Case 7
    ButName$ = "No"
  End Select
  Msg$ = "You selected the <" & ButName$ & "> button."
  MsgBox Msg$, 64, "Button"     ' Message box procedure with info icon
 Next myCount 
End Sub

Determining the value for TypeNum

By setting a value for the optional TypeNum parameter, you can control the look and functioning of the message box. The value is arrived at by selecting an option in each of the following areas: buttons displayed, icon displayed, default button and dialog mode. Each option has a key number associated with it. The final value of TypeNum is calculated by adding together each key number for the options chosen.

Example
The following table lists key values for the TypeNum parameter. To calculate a value for TypeNum, select one option from each category and add together the corresponding key numbers.

Buttons

  • 0 Display OK button only.
  • 1 Display OK and Cancel buttons.
  • 2 Display Abort , Retry , and Ignore buttons.
  • 3 Display Yes , No , and Cancel buttons.
  • 4 Display Yes and No buttons.
  • 5 Display Retry and Cancel buttons.

Icons

  • 16 Display warning icon.
  • 32 Display question mark icon.
  • 48 Display exclamation mark icon.
  • 64 Display information icon.

Default button

  • 0 First button is default.
  • 256 Second button is default.
  • 512 Third button is default.

Mode

  • 0 Application modal. The user must respond to the message dialog before continuing work in the current application
  • 4096 System modal. All applications are suspended until the user responds to the message dialog.

Name

Description
Changes the name of a directory or a file.
Syntax
Name OldName$ As NewName$
Parameters
OldName$ - a string expression that identifies the directory or file you wish to rename.
NewName$ - a string expression that contains the new name for the file or directory.
Notes
If you are renaming a file and it is not in the current directory you must give the full path as part of both parameters of the statement.
It is possible to use the Name procedure to move a file by giving a different path in NewName$. If you do this, the file will be moved (not copied) to the new directory.

On Error

Description
Determines the way the program reacts when an error is encountered. The first syntax causes the program to jump to the subroutine identified by label. The second syntax causes the program to resume running at the next line after the line at which the error occurred. The third syntax disables any error handling in the current procedure.
Syntax
On Error GoTo label
On Error Resume Next
On Error GoTo 0

Parameters
label - name of a label statement within the procedure.
Notes
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 sets the error handling jump and then causes two errors to be generated. The error handling routing uses the Number and Description properties of the Err object to show a message describing the error. Control is then returned to the main program after the lines that generated the errors.

Sub Main
  On Error GoTo ErrorHandler
  Dim x as object
  x.draw        ' Object not set error
  y = 1/0     ' Division by zero
  MsgBox "You are now back in the main program."
  Exit Sub
ErrorHandler:
  Msg$ = "The following error has occurred:" & Chr(10)
  Msg$ = Msg$ & "Error number = " & Err.Number & Chr(10)
  Msg$ = Msg$ & Err.Description
  MsgBox Msg$, 16, "An error has occurred"
  Resume Next
End Sub

Option Base

Description
Declares the default lower bound for array subscripts.
Syntax
Option Base BaseNum
Parameters
BaseNum - can be 0 or 1.
Notes
If used, this statement can appear only once in a module, must occur only in the Declarations section, and must be used before you declare the dimensions of any arrays. If no Option Base statement is used in a module, the default base for arrays is 0.
Regardless of the setting of the Option Base, you can explicitly set the bounds for an array dimension by using a declaration of the form: Dim myArray(1 To 10).
Example
In the following example, the Option Base statement is used to set the default base for arrays to 1. Two arrays are then dimensioned: A is a ten element array using the default lower bound; B is a ten element array dimensioned using an explicit To keyword to set the lower bound to 0.

Option Base 1       ' Module level statement.
Sub Main
 Dim A(10)          ' Default base used
 Dim B(0 To 9)      ' To statement explicitly sets base
 MsgBox "Lower bound for A = " & LBound(A)
 MsgBox "Lower bound for B = " & LBound(B)
End Sub

Option Explicit

Description
Forces explicit declaration of all variables. If this statement is used, a compile error will be generated if the code contains any variables which are not explicitly declared.
Syntax
Option Explicit
Parameters
This procedure takes no parameters.
Notes
If used, this statement can appear only once in a module, must occur only in the Declarations section.
Example

Option Explicit
Sub Main
 y = 5 ' generates a compile error because
 ' the variable y has not been declared
End Sub

Print

Description
Print a string to the default message window.
Syntax
Print expression[, expression...]
Parameters
expression - any valid expression.
Notes
The default message window is a simple message box. The primary intention of the Print procedure is to provide a simple means of displaying values during program development. To display program messages to a user, use the more flexible MsgBox procedure or function.
Example
This example shows how the Print procedure can be used during program development to display information during program execution.

Sub PrintExample ()
 Dim Pi
 Pi = 22/7
 Print Pi   ' View the output of a calculation
End Sub

Rem

Description
Used to include explanatory remarks in a program.
Syntax
Rem remark
' remark

Parameters
remark - explanatory text or comment used to document a macro.
Notes
The Rem statement causes the line of text following the keyword to be treated as a comment. Comments are ignored by the interpreter. Use the single quote symbol ' to mark part of a line as a comment. All text following the ' symbol on the line is treated as a comment.
Example

The following example shows the use of comments in a procedure.
Sub Main()
 Rem This is a comment line
 MsgBox "hello"  ' This is a comment in a line of code
 ' This is also a comment line
End Sub

SendKeys

Description
Sends one or more keystrokes to the active window as if they had been entered at the keyboard.
Syntax
SendKeys (Keys$, [wait])
Parameters
Keys$ - a string expression that represents the keys to be sent to the active window.
wait - optional Boolean TRUE or FALSE. If TRUE, the keystrokes are processed before control is returned to the calling program. If wait is FALSE or omitted, control returns immediately.
Notes
The following special string sequences can be included in the Keys$ string:

Key

Code

Key

Code

ALT

%

HOME

{HOME}

CTRL

+

INS or INSERT

{INSERT} or {INS}

SHIFT

^

LEFT ARROW

{LEFT}

BACKSPACE

{BACKSPACE}

NUM LOCK

{NUMLOCK}

BREAK

{BREAK}

PAGE DOWN

{PGDN}

CAPS LOCK

{CAPSLOCK}

PAGE UP

{PGUP}

DEL or DELETE

{DELETE} or {DEL}

PRINT SCREEN

{PRTSC}

DOWN ARROW

{DOWN}

RIGHT ARROW

{RIGHT}

END

{END}

SCROLL LOCK

{SCROLLLOCK}

ENTER

{ENTER} or ~

TAB

{TAB}

ESC

{ESC}

UP ARROW

{UP}

HELP

{HELP}

F1, F2, etc

{F1}, {F2}, etc

Example
The following example opens the Windows calculator, changes the view to Scientific and multiplies two numbers together.

Sub Main ()
 X = Shell("Calc.exe", 1) ' Shell Calculator.
 SendKeys "%VS", True     ' Change to Scientific mode Alt-VS.
 SendKeys "12*5=", True   ' 60 should be displayed.
End Sub

Set

Description
Assigns an object to an object variable.
Syntax
Set ObjectVar = {[New] ObjectExpression | Nothing}
Parameters
ObjectVar - a valid object variable.
ObjectExpression - an object or object expression.
Notes
The Dim and Static statements only declare a variable that refers to an object. No actual object is referred to until you use the Set statement to assign a specific object.
The optional New keyword is usually used during declaration to enable implicit object creation. When New is used with Set, it creates a new instance of the class. If ObjectVar contained a reference to an object, that reference is released when the new one is assigned. The New keyword can't be used to create new instances of any intrinsic data type and can't be used to create dependent objects.
Using the Nothing keyword discontinues association of ObjectVar with any specific object.
Example
The following example interacts with the Visio drawing application by creating a series of objects associated with the application.

Sub Main
 Dim visio As Object
 Set visio = CreateObject( "visio.application" )
 Dim draw As Object 
 Set draw = visio.Documents
 draw.Open "c:\visio\drawings\Sample1.vsd"
 MsgBox "Open docs: " & draw.Count
 Dim page As Object
 Set page = visio.ActivePage
 Dim red As Object
 Set red = page.DrawRectangle (1, 9, 7.5, 4.5)
 red.FillStyle = "Red fill"
 Dim cyan As Object
 Set cyan = page.DrawOval (2.5, 8.5, 5.75, 5.25)
 cyan.FillStyle = "Cyan fill"
 Dim green As Object
 Set green = page.DrawOval (1.5, 6.25, 2.5, 5.25)
 green.FillStyle = "Green fill"
 Dim DarkBlue As Object
 set DarkBlue = page.DrawOval (6, 8.75, 7, 7.75)
 DarkBlue.FillStyle = "Blue dark fill"
 visio.Quit
End Sub

Shell

Description
Runs an executable program file and returns the program's task ID.
Syntax
Shell(AppFile$ [, style])
Parameters
AppFile$ - a string expression that contains the name (and path) of and executable program file. Supported file types include .PIF, .COM, .BAT, or .EXE.
style - optional integer expression that sets the window style for the application when it is invoked. See below.
Notes
If the call to the application file is successful, the function returns a Long integer data type containing the task ID for the instance of the application. If the call is not successful, the function returns 0.
The way the application opens is determined by the style parameter, as follows:

style =

Window type

1,5,9

Normal with focus

2

Minimized with focus (default)

3

Maximized with focus

4,8

normal without focus

6,7

minimized without focus

Example
The following example opens the Windows calculator, changes the view to Scientific and multiplies two numbers together.

Sub Main ()
 X = Shell("Calc.exe", 1) ' Shell Calculator.
 SendKeys "%VS", True     ' Change to Scientific mode Alt-VS.
 SendKeys "12*5=", True   ' 60 should be displayed.
End Sub

Space

Description
Inserts a number of spaces in a string expression or Print# statement.
Syntax
Space(number)
Parameters
number - an integer expression giving the number of spaces to insert. The parameter number can be any valid integer.
Notes
This function gives a shorthand way of inserting a number of spaces into a string expression. The function returns a String data type which contains the designated number of spaces.
Example
The following example uses the Space function as a shorthand way of inserting a number of spaces into a string expression.

Sub Main
 MsgBox "Hello" & Space(20) & "There"
End Sub

Static

Description
Used to declare variables and allocate storage space. These variables will retain their value throughout the program run.
Syntax
Static VarName [As type]
Parameters
VarName - a valid variable name
type - a valid variable data type. Valid types are: Integer, Long, Single, Double, Date, Boolean, String, Variant, Object.
Notes
Declaring a variable within a function or subprocedure with the Static statement enables the preservation of the value of the variable between calls to that function or procedure during program execution.
Example
This example defines three procedures. The main procedure calls two subprocedures a number of times. The two subprocedures are identical except that Sub2 defines a static variable whose value is retained between calls.

Sub Main
 For a = 1 to 4
  Sub2    ' Jump to Sub2
  Sub3    ' Jump to Sub3
 Next a
End Sub
' Define second procedure 
Sub Sub2
 Static i As Integer
 i = i + 5
 MsgBox "The current value of i = " & i
End Sub 
' Define third procedure
Sub Sub3
 Dim j As Integer
 j = j + 5
 MsgBox "The current value of j = " & j
End Sub

Stop

Description
Ends the execution of a program.
Syntax
Stop
Parameters
None
Notes
The Stop statement can be placed anywhere in your code. This statement has the same effect as the End statement.

Type...End Type

Description
Declares a user-defined data type containing one or more elements.
Syntax
Type usertype
elementname As type
[elementname As type]
...
End Type

Parameters
usertype - name of a user-defined data type. It follows standard variable naming conventions.
elementname - name of an element of the user-defined data type. It follows standard variable-naming conventions.
type - a valid data type: Integer, Long, Single, Double, String, Variant, or another user-defined type. The argument typename can't be an object type.
Notes
Once you have declared a user-defined type using the Type procedure, you can declare a variable of that type anywhere in your script. Use Dim or Static to declare a variable of a user-defined type. Line numbers and line labels aren't allowed in Type...End Type blocks.
User-defined types are often used with data records because data records frequently consist of a number of related elements of different data types. Arrays cannot be an element of a user defined type in Enable Basic.
Example
The following example creates a data type called Component which has three elements: Designator, Value and CompType. The macro dimensions a variable myComp as a Component type and asks the user to enter a value for each element of myComp.

Type Component              ' Create a user defined data type.
    Designator As String
    Value As Double
    CompType As String
End Type 
Dim myComp As Component      ' Dimension a variable as the user type.
' ------------------------------------------------------------
' The following sub procedure asks the user for a value for each
' element, and then displays the results.
Sub Form_Click ()
    myComp.Designator = InputBox("Enter a designator(eg C5)")
    myComp.Value = CDbl(InputBox("Enter a value (number only)"))
    myComp.CompType = InputBox("Enter component type (eg Resistor)")
    Msg$ = "The component " & myComp.Designator
    Msg$ = Msg$ & " is a " & myComp.CompType
    Msg$ = Msg$ & " with a value of " & myComp.Value & " units."
    MsgBox Msg$
End Sub

UBound

Description
Returns the largest available subscript for the dimension of the indicated array.
Syntax
UBound(array [, dimension])
Parameters
array - a valid array name, excluding parentheses.
dimesion - a optional numeric expression representing an array dimension of a multi-dimensional array. The first dimension of an array is 1, the second 2, etc.
Notes
If dimension is omitted and array has more than one dimension, the upper bound for the first dimension is returned.
Example
The following example displays the upper and lower bounds for each dimension of a two-dimensional array.

Sub Main()
 Dim myArray(2 To 6, 4 To 8)
 Dim Low1, Low2, Up1, Up2, Msg
 Low1 = LBound(myArray)
 Up1 = UBound(myArray)
 Low2 = LBound(myArray, 2)
 Up2 = UBound(myArray, 2)
 MsgBox "First dimension goes from element " & Low1 & " to " & Up1
 MsgBox "The 2nd dimension goes from element " & Low2 & " to " & Up2
End Sub

Val

Description
Returns the numeric value of a string of characters.
Syntax
Val(String$)
Parameters
String$ - a string expression.
Notes
The function attempts to convert String$ to a number by extracting any valid numerical value contained at the beginning of the string. For example, the string "200 ohm" will return a value of 200. If the string does not begin with a numerical value, the function returns 0. The function returns a Double data type.
Example
The following example shows the return values for various strings.

Sub ValConvert
 Print Val("45")                ' returns 45
 Print Val("45ohm")             ' returns 45
 Print Val("a 45 ohm resistor") ' returns 0
 Print Val("45e-5 farad")       ' returns 0.00045
End Sub

The following example asks the user to enter a string and then displays the result of passing the string to the Val function.

Sub main
 Dim Msg
 Dim YourVal As Double
 Again = 6
 While Again = 6
  YourVal = Val(InputBox$("Enter a number or string"))
  Msg = "The number you enered is: " & YourVal
  Msg = Msg & Chr(10) & Chr(10) & "Try again?"
  Again = MsgBox(Msg, 68, "Val test")
 Wend
End Sub

VarType

Description
Returns a value that indicates the data type of the parameter VarName.
Syntax
VarType(VarName)
Parameters
VarName - a valid variable name.
Notes
The function returns an integer that indicates the data type according to the following table:

return value

Var Type

0

(empty) Variant

1

Null

2

Integer

3

Long

4

Single

5

Double

7

Date/Time

8

String

9

Object

11

Boolean

12

(empty) Array

Example
The following example creates variables of different types and then displays the VarType for each variable.

Sub main
 Dim a
 b = Empty
 c = 5
 d = 123456789
 e = CSng(1.23)
 f = 1.23456789
 g = Date
 h = Time(Now)
 i = "Hello"
 Dim j As Object
 k = True
 Dim l(3)
 MsgBox "a is VarType " & VarType(a)
 MsgBox "b is VarType " & VarType(b)
 MsgBox "c is VarType " & VarType(c)
 MsgBox "d is VarType " & VarType(d)
 MsgBox "e is VarType " & VarType(e)
 MsgBox "f is VarType " & VarType(f)
 MsgBox "g is VarType " & VarType(g)
 MsgBox "h is VarType " & VarType(h)
 MsgBox "i is VarType " & VarType(i)
 MsgBox "j is VarType " & VarType(j)
 MsgBox "k is VarType " & VarType(k)
 MsgBox "l is VarType " & VarType(l)
End Sub
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.