Keywords
Contents
- Reserved words in Enable Basic
- Enable Basic Keywords
- Abs
- AppActivate
- Atn
- Asc
- Beep
- Call
- CBool
- CDbl
- CInt
- CLng
- Const
- CreateObject
- CSng
- CStr
- Declare
- Dim
- IsEmpty
- IsNull
- IsNumeric
- Int
- InStr
- InputBox
- GetObject
- Hex
- Format
- Pre-defined formats for fmt$
- Predefined Numeric Formats
- Predefined Date & Time Formats
- Creating User Defined Format Strings for fmt$
- Special Characters for Number Format Strings
- Special Characters for Date & Time Format Strings
- Special Characters for Text Format Strings
- Fix
- LBound
- Let
- MsgBox
- Name
- On Error
- Option Base
- Option Explicit
- Rem
- SendKeys
- Set
- Shell
- Space
- Static
- Stop
- Type...End Type
- UBound
- Val
- VarType
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 |
|---|---|
|
| Display the number as is, with no thousand Separators |
|
| Display at least one digit to the left and two digits to the right of the decimal separator. |
|
| Display number with thousand separator and two digits to the right of the decimal separator. |
|
| Multiplies the number by 100 and displays it with two decimal places and a percent sign ( |
|
| Standard scientific notation. |
|
| Displays False if number is 0, otherwise displays True. |
Predefined Date & Time Formats
Enable Basic predefined date & time format names:
| fmt$ = | Description |
|---|---|
|
| Display a Long Date, as defined in the International section of the Control Panel. |
|
| Display a date in the same form as the Short Date, but with the month shown as abbreviation, rather than a number. |
|
| Display a Short Date, as defined in the International section of the Control Panel. |
|
| Display a Long Time, as defined in the International section of the Control panel. Long Time includes hours, minutes, seconds. |
|
| Display time in 12-hour format using hours and minutes and the Time AM/PM designator. |
|
| 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 |
|---|---|
|
| 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. |
|
| 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. |
|
| Displays the date as dddd and displays the time as ttttt. |
|
| Display the day of the month as a number without a leading zero (1-31) |
|
| Display the day of the month as a number with a leading zero (01-31) |
|
| Display the day of the week as an abbreviation (Sun-Sat). |
|
| Display a date serial number as a complete date (including day , month, and year). |
|
| Display the day of the week as a number (1- 7 ). |
|
| Display the week of the year as a number (1-53). |
|
| 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. |
|
| 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. |
|
| Display the month as an abbreviation (Jan-Dec). |
|
| Display the month as a full month name (January-December). |
|
| display the quarter of the year as a number (1-4). |
|
| Display the day of the year as a number (1-366). |
|
| Display the day of the year as a two-digit number (00-99) |
|
| Display the day of the year as a four-digit number (100-9999). |
|
| Display the hour as a number without leading zeros (0-23). |
|
| Display the hour as a number with leading zeros (00-23). |
|
| Display the minute as a number without leading zeros (0-59). |
|
| Display the minute as a number with leading zeros (00-59). |
|
| Display the second as a number without leading zeros (0-59). |
|
| Display the second as a number with leading zeros (00-59). |
|
| Display a time serial number as a complete time (including hour, minute, and second) formatted using the system time separator. |
|
| Use the 12-hour clock and displays an uppercase AM/PM |
|
| Use the 12-hour clock and displays a lowercase am/pm |
|
| Use the 12-hour clock and displays a uppercase A/P |
|
| Use the 12-hour clock and displays a lowercase a/p |
|
| 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 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 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 |
|
| CTRL |
| INS or INSERT |
|
| SHIFT |
| LEFT ARROW |
|
| BACKSPACE |
| NUM LOCK |
|
| BREAK |
| PAGE DOWN |
|
| CAPS LOCK |
| PAGE UP |
|
| DEL or DELETE |
| PRINT SCREEN |
|
| DOWN ARROW |
| RIGHT ARROW |
|
| END |
| SCROLL LOCK |
|
| ENTER |
| TAB |
|
| ESC |
| UP ARROW |
|
| HELP |
| 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 |
|---|---|
|
| Normal with focus |
|
| Minimized with focus (default) |
|
| Maximized with focus |
|
| normal without focus |
|
| 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 |
|---|---|
|
| (empty) Variant |
|
| Null |
|
| Integer |
|
| Long |
|
| Single |
|
| Double |
|
| Date/Time |
|
| String |
|
| Object |
|
| Boolean |
|
| (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