EnableBasic

Parent page: Scripting Languages

This Enable Basic Reference provides an overview of the structure of scripts written in the Enable Basic language and describes how the language is used to create scripts.

Also in this reference:

The Enable Basic language

The Enable Basic language follows similar conventions to Microsoft Visual Basic™. Before attempting to create scripts using Enable Basic, you should be familiar with the process-based nature of the Altium Designer environment and how parameters are used with processes.

Enable Basic structure

An Enable Basic script is divided into three main sections:

Global declarations

This is the first section in the script file and contains the declarations of any global variables and constants. Any variables declared using the Dim statement in this section are global and can be used by the main program, as well as any functions or subroutines.

Main program

This is the main program code. The main program code is defined as a procedure with a Sub...End Sub statement block. The name given to the main program block is not important, however it must be the first procedure defined in the script file.

Subroutines and Functions

Following the main program block is the definition of any functions or subprocedures that are called by the main program. Each function is defined in a Function...End Function statement block, and each subprocedure is defined in a Sub...End Sub statement block.

Project source files

A script project is organized to store script documents (script units and script forms) which are edited in Altium Designer's scripting engine. You can execute the script from a menu item, toolbar button or from the Run Script dialog from the system menu.

PRJSCR and BAS files

Scripts are organized into projects with a *.PRJSCR extension. Each project consists of files with a *.bas extension.

It is possible to attach scripts to different projects, but it's highly recommended to organize scripts into different projects to help manage the number of scripts and their procedures/functions. Scripts consist of functions and procedures that can be called within Altium Designer.
 

Writing Enable Basic scripts

This section details:

• Formatting Values in Enable Basic
• Using Arrays in Enable Basic
• Format for Writing lines of Enable Basic Code
• Enable Basic Naming Conventions
• Using Named Variables in Enable Basic
• Enable Basic Error Codes
• Error Handling in Enable Basic

Formatting values

Values can be formatted for display in an Enable Basic macro script using the Format function. This function applies a specified formatting template to a value and returns a string that contains the formatted value. The template used to format the value is referred to as the formatting string.

The Format function takes the form:
Format ( expression [, fmt$ ])

...where;
expression is any valid Enable Basic expression.
fmt$ is a string or string expression that contains a predefined Enable Basic format name, or a user-defined format string.

Enable Basic provides a number of predefined formats which can be applied by using the format name as the fmt$ parameter in the Format statement.

The power of the Format function comes from the ability to accept user-defined formatting strings. These strings use special placeholder characters to define the format of the expression.

User-defined formatting strings

A user-defined formatting string is used to create a formatting template for use with the Format function in an Enable Basic macro script.

For example, the following code fragment uses the formatting string "###0.00" to format a number with at least one leading digit and two decimal places:
Format(334.9, "###0.00")

This format statement returns the string "334.90". The "#" and "0" characters have special meanings in a formatting string. The following are lists of the special characters for use in formatting strings and their meanings.

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.

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.

Text format strings

Character	Meaning
@	Character placeholder. Displays a character or a space. Placeholders are filled from right to left unless there is a ! 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.

A format string for numbers can have up to three sections separated by semicolons. These sections are: "Default number format[; Negative values][; Zero values]".

For example, the following formatting string defines that negative numbers appear in brackets, and that zero values return the word "nothing":
"#0.00;(#0.00);\n\o\t\h\i\n\g"

For 334.9, this returns "334.90". For -334.9, this returns "(334.90)". For 0, this returns "nothing".

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.

The following table includes some examples of formatting strings:

fmt$ =	expr	Format(expr, fmt$)
"#,#0.00"	345655.9	"345,655.90"
	-345655.9	"-345,655.90"
	0	"0.00"
	.3	"0.30"
	.003	"0.00"
"#,#0.00; -#,#0.00; \N\U\L\L"	345655.9	"345,655.90"
	-345655.9	"-345,655.90"
	0	"NULL"
	.3	"0.30"
	.003	"0.00"
"$#,#0.00; ($#,#0.00); [$0]"	345655.9	"$345,655.90"
	-345655.9	"($345,655.90)"
	0	"[$0]"
	.3	"$0.30"
	.003	"$0.00"

Note that the Format function always returns a string value, regardless of what data is being formatted.

Using Arrays

An array is a single named variable that contains a number of indexed elements. Enable Basic supports both single and multi-dimensional arrays. All the elements in an array have the same data type, and support is provided for arrays of Integer, Long, Single, Double and String data types. In a multi-dimensional array, each dimension can contain a different number of elements.

When an array is first declared, all elements are empty. To reinitialize all elements in an array after the values have been assigned, use the Erase statement.

To reference an array element in a program, use the following syntax:
myArray(i1, i2, i3, ...)

...where;
i1 is the index number of the element in the first dimension
i2 is the index number of the element in the second dimension, etc.

The Lower Bound of an array dimension is the minimum allowable index value for that dimension. Similarly, the Upper Bound of an array dimension is the largest allowable index value for that dimension. The index numbers for an array must be integers and be within the upper and lower bounds for each particular dimension - see below.

By default, the Lower Bound for all dimensions is 0. You can change the default Lower Bound to 1 by placing an Option Base 1 statement in the Global Declarations section of a macro script.

Declaration of Arrays

The general form of an array declaration is:
Dim ArrayName ( U1 , U2 , ...) As DataType

...where;
ArrayName is the name of the array (which follows standard Enable Basic naming conventions).
U1 , U2 ... are the upper bounds for each dimension.
DataType is the type of data to be held by the array.

The following code fragments are examples of standard array declarations:

 Dim Counters(9) As Integer ' single dimension, 10 element array. Dim myData(4, 9) As Double ' two dim, 50 element (5x10) array.

Explicitly declaring the lower bound for an array dimension

The Lower Bound of an array dimension is the minimum allowable index value for that dimension, and the Upper Bound is the largest allowable index value for that dimension.

Unless the Option Base 1 statement is used, the default lower bound for each array dimension is 0. You can, however, explicitly define the lower bound for each array dimension by specifying the full index range in the Dim statement.
Dim ArrayName(L1 To U1, L2 To U2, ...) As DataType

...where;
L1, L2... are the lower bounds for each dimension.
U1, U2... are the upper bounds for each dimension.

The following code fragment illustrates this syntax:

 Dim Counters (1 To 10) As Integer ' single dimension, 10 element array. Dim myData(1 To 5, 9) As String ' two dim, 50 element (5x10) array. Dim myArray(1 To 5, 11 To 20) As String ' two dim, 50 element (5x10) array.

In the preceding declarations, the index numbers of Counters run from 1 to 10, index numbers of myData run from 1 to 5 and 0 to 9 and the index numbers for myArray run from 1 to 5 and 11 to 20.

Enable Basic Code format

Case sensitivity

Enable Basic is not case sensitive — that is, all keywords, statements, variable names, function and procedure names can be written without regard to using capital or lower case letters. Both upper and lower case characters are considered equivalent. For example, the variable name myVar is equivalent to myvar and MYVAR. Enable Basic treats all of these names as the same variable.

The only exception to this is in literal strings, such as the title string of a dialog definition, or the value of a string variable. These strings retain case differences.

Statement separators

In general, each Enable Basic code statement is written on a separate line in the script file. The carriage return character marks the end of a code statement. You can, however, put more than one code statement on a single line by separating the code statements with the colon " : " character.

For example:
X.AddPoint( 25, 100)
X.AddPoint( 0, 75)
...is equivalent to:
X.AddPoint( 25, 100) : X.AddPoint( 0, 75)

The Space Character
A space is used to separate keywords in a code statement. However, Enable Basic ignores any additional spaces in a code statement.

For example:
X = 5
...is equivalent to:
X    =    5

Spaces can be freely used to make code more readable.

Splitting a line of code

Enable Basic does not put any practical limit on the length of a single line of code in a macro script. However, for the sake of readability and ease of debugging, it's good practice to limit the length of code lines so that they can easily be read on screen or in printed form.

If a line of code is very long, you can break the code by using the "_" underscore continuation character. Place the "_" at the end of a line to indicate that the code continues on the next line. The "_" must be preceded by a space.

The following code fragment shows the use of the continuation character:

 Declare Sub InvertRect Lib "User" (ByVal hDC As Integer, _ aRect As Rectangle)

This code will be treated by the Enable Basic interpreter as if it were written on a single line.

Including Comments

In a macro script, comments are non-executable lines of code which are included for the benefit of the programmer. Comments can be included virtually anywhere in a script. Any text following an apostrophe or the word Rem are ignored by Enable Basic.

 ' This whole line is a comment rem This whole line is a comment REM This whole line is a comment Rem This whole line is a comment

Comments can also be included on the same line as executed code. For example, everything after the apostrophe in the following code line is treated as a comment.

 MsgBox "Hello" ' Display Message

Naming conventions

In an Enable Basic macro script file, the main program block and subprocedures are declared using the Sub...End Sub statement block. Functions are declared using the Function...End Function statement block.

Both of these statement blocks require a name to be given to the procedure or function. Also, Enable Basic allows you to create named variables and constants to hold values used in the macro.

In general, there is no restriction to the names that can be given to procedures, functions, variables and constants, as long as they adhere to the following rules:

• The name can contain the letters A to Z and a to z, the underscore character "_" and the digits 0 to 9.
• The name must begin with a letter.
• The name must be no longer than 40 characters.
• The name cannot be a Enable Basic keyword or reserved word.
• Names are case insensitive when interpreted. Both upper and lower case cab be used when naming a function, subroutine, variable or constant, however the Enable Basic interpreter will not distinguish between upper and lower case characters. Names which are identical in all but case will be treated as the same name in Enable Basic.

Using Named Variables

In an Enable Basic script file, named variables or constants are used to store values to be used during program execution. Variables can be used to store a variety of data types.

In Enable Basic there is no need to explicitly declare a variable before using it. A previously undeclared variable name can be used in a code statement and Enable Basic will recognize the variable.

A variable can be explicitly declared to hold a specific data type using the As Type clause of the Dim or Static statements. For example, the following code fragment defines a string variable and an integer variable:
Dim myStr As String, myInt As Integer

The type of data a variable can hold can be implicitly declared by using one of the Type Specifier characters as the last character of the variable's name. Valid Type Specifiers are:

• $ = String
• % = Integer
• & = Long
• ! = Single
• # = Double

For example, the following code fragment declares a string and also an integer variable:
Dim myString$, myInt%

Variables whose type is not explicitly or implicitly declared are treated as a Variant data type. Variants can store any data type and can vary the data type dependent on the value assigned.

To determine the current data type of a Variant, use the VarType function. For example, the following code fragment declares a variant and then assigns several different types of data to it:

 Dim myVar myVar = 1.2768 ' myVar is a Single data type. myVar = "Hello" ' myVar is now a String data type

Data Types

The following is a list of data types used by Enable Basic:

Data Type	Type Specifier	VarType =	Size
String	$	8	65,500 char
Integer	%	2	2 bytes
Long	&	3	4 bytes
Single	!	4	4 bytes
Double	#	5	8 bytes
Variant		0
Object		9
Boolean		11
Date		7

Data Type conversion

In an Enable Basic macro script, named variables used to store program values can be explicitly or implicitly declared to accept a particular data type. If the data type is not declared for a variable, it is created as a Variant.

When a value is assigned to a Variant, Enable Basic sets the data type of the variant to suit the value. Assigning a different value to a Variant will change the data type to suit. Use the VarType function to return the current variable data type.

When a value is assigned to a variable whose data type has been explicitly or implicitly declared, Enable Basic will attempt to automatically convert the value, if it is not of the correct data type. For example, the following code fragment declares an Integer variable, myInt and then tries to assign a string value to it.

 Dim myInt As Integer myInt = "3.76 amps"    ' myInt is now 4 

The result of this assignment statement is that Enable Basic will automatically convert the string to an integer and store this integer in myInt. In this case, after the assignment myInt = 4.

Automatic data type conversion means that you do not have to be exact about matching assignment statements and variable types. Be aware, however, that the results of conversion may not always be what is expected, so care should be taken to make sure that any assignment statements produce predictable results.

For example, the code fragment;
Dim myInt As Integer
myInt = "R33"
...would set myInt = 0 because when Enable Basic converts a string to a number it looks for a numerical value in the string, starting from the first character. If the first character is not a number or a decimal point, then the conversion returns 0.

User-defined variable types

Users can define custom variable types that are composites of other built-in or user-defined types. Variables of these new composite types can be declared and then member variables of the new type can be accessed using dot notation. Variables of user-defined types can not be passed to DLL functions expecting 'C' structures.

User-defined types are created using the Type...End Type statement block, which must be placed in the Global Declaration section of the code (all user-defined variable types are global). The variables that are declared as user-defined types can be either global or local. User-defined variable types cannot contain arrays.

User-defined variable types are often used when you need to define a group of linked variables or data records. The following code fragment illustrates this by defining a user-defined variable type called "Component" which includes three elements: Designator, Value and CompType. Together, these elements form the description of a component:

 Type Component  Designator As String  Value As Double  CompType As String End Type

Once a user-defined type is defined, individual elements can be referenced using "dot" notation. For example, the following code fragment declares a variable called "myComp" as a Component type and then sets the value for each element:

 Dim myComp As Component myComp.Designator = "R7" myComp.Value = 1200 myComp.CompType = "Resistor"

 

Enable Basic Error Codes

Err	Description	Err	Description
3	Return without GoSub	5	Invalid procedure call
6	Overflow	7	Out of memory
9	Subscript out of range	10	Array is fixed or temporarily locked
11	Division by zero	13	Type mismatch
14	Out of string space	16	Expression too complex
17	Can't perform requested operation	18	User interrupt occurred
20	Resume without error	28	Out of stack space
35	Sub, Function, or Property not defined	47	Too many DLL application clients
48	Error in loading DLL	49	Bad DLL calling convention
51	Internal error	52	Bad file name or number
53	File not found	54	Bad file mode
55	File already open	57	Device I/O error
58	File already exists	59	Bad record length
60	Disk full	62	Input past end of file
63	Bad record number	67	Too many files
68	Device unavailable	70	Permission denied
71	Disk not ready	74	Can't rename with different drive
75	Path/File access error	76	Path not found
91	Object variable or With block variable not set	92	For loop not initialized
93	Invalid pattern string	94	Invalid use of Null
429	OLE Automation server cannot create object	430	Class doesn't support OLE Automation
432	File name or class name not found during OLE Automation operation	438	Object doesn't support this property or method
440	OLE Automation error	443	OLE Automation object does not have a default value
445	Object doesn't support this action	446	Object doesn't support named arguments
447	Object doesn't support current local setting	448	Named argument not found
449	Argument not optional	450	Wrong number of arguments
451	Object not a collection	444	Method not applicable in this context
452	Invalid ordinal	453	Specified DLL function not found
457	Duplicate Key	460	Invalid Clipboard format
461	Specified format doesn't match format of data	480	Can't create AutoRedraw image
481	Invalid picture	482	Printer error
483	Printer driver does not supported specified property	484	Problem getting printer information from the system.
485	Invalid picture type	520	Can't empty Clipboard
521	Can't open Clipboard

Error handling

In an Enable Basic macro script you can trap and process any run-time errors that occur using the On Error statement. This statement defines a jump to a subprocedure that will be run whenever an error is encountered. This statement takes the form:
On Error Goto label

...where;
label represents the name of a subprocedure defined in the procedure or function.

The error handling subprocedure would then take the form:
label:
...error handling statement block...
Resume Next

The Resume Next statement tells the program to resume at the next instruction line after the one that caused the subprocedure call.

Enable Basic maintains an internal object variable called Err that stores the error number and description of the last error that occurred. This variable can be used in an error handling subroutine to determine the type of error that has occurred.

The properties of the Err object are as follows:

• Err.Number returns the number of the last error to occur.
• Err.Description returns a text description of the last error to occur.

Once an On Error statement is included in a procedure, error handling can be temporarily disabled by issuing the statement:
On Error Goto 0

This causes the interpreter to handle errors internally, rather than invoke a user-defined subprocedure. Issue the standard On Error statement to re-enable the error handling subprocedure.