VBScript Support in Altium NEXUS

Parent page: Scripting Language Support

This reference describes the VisualBasic Scripting language used to create scripts in Altium NEXUS. It provides details of the VisualBasic Scripting statements, functions, and extensions that are supported in the scripting system.

Also in this reference:

• VBScript Statements
• VBScript Subroutines and Functions
• Using Form Components with VBScript

The VBScript Language Copy Link Copied

The Visual Basic Scripting (or VBScript for short) can be used to create scripts that deal with Altium NEXUS Object Models and Visual Components. In this reference, it's assumed that you are familiar with basic programming concepts and the basic operation of Altium NEXUS.

The Altium NEXUS scripting system supports the VBScript language (along with other scripting languages) which is derived from the Microsoft ActiveX Scripting system. So for instance, you should be able to use CScripts or WScripts which are based on the same ActiveX scripting engine that is used in Altium NEXUS.

All scripting languages supported in Altium NEXUS are typeless or untyped, which means that a script cannot define records or classes and pass pointers as parameters to functions.

VBScript script example

view sourceprint?
1
Sub DisplayName (sName)
2
  MsgBox "My Name is " & sName
3
End Sub

Altium NEXUS and the Delphi RTL

The Scripting system supports a subset of the Embarcadero Delphi Run Time Library (RTL) and the Altium NEXUS API.

VBScripts scripts can access several Object Models in Altium NEXUS. For example, the PCB Object Model can be used in VBScripts to deal with PCB objects on a PCB document, or the Workspace Manager Object Model to work with Projects and their documents to extract netlist data.

The Scripting Reference contains information on interfaces with respect to Altium NEXUS Object Models, components, global routines, types, and variables that make up this scripting language. Consult the Microsoft Visual Basic documentation for more information on VBScript functions.

Server Processes

A script can be used to execute server processes, which represent commands in Altium NEXUS.

VBScript Source Files Copy Link Copied

A VBScript project is organized to store script documents (script units and script forms). A script can be executed from a menu item, toolbar button, or from the Run Script dialog from the system menu.

PRJSCR, VBS, and DFM files

Scripts are organized into projects with a *.PRJSCR extension. Each VBScript project consists of files with a *.vbs extension. Files can be either script units or script forms — each form has a VBScript script file with *.vbs extension and a corresponding form with a *.dfm extension). A script form is a graphical window (dialog) that hosts different controls that run on top of Altium NEXUS.

It is possible to attach scripts to different projects, and it's highly recommended to organize scripts into different projects to manage the number of scripts and their procedures/functions. Scripts (script units and script forms) consist of functions/procedures that can be called within Altium NEXUS.

VBScript Examples Copy Link Copied

The simple examples included in this reference illustrate the basic features of VBScript programming in Altium NEXUS.

The VBScripts can use script forms, script units, functions, and objects from the Altium NEXUS scripting API, and a subset of functions and objects from the Embarcadero Delphi RTL that are exposed in the scripting system.

Writing VBScript Scripts Copy Link Copied

This section covers the basic concepts of writing VBScripts in Altium NEXUS.

VBScript Naming Conventions

VBScript variables are case insensitive — that is, variables in upper and lower case have the same meaning:

Example

view sourceprint?
1
The variables b and B are the same.
2
b = 60
3
B = 60

Local and Global Variables

Since all scripts have local and global variables, it is important to have unique variable names in your scripts within a script project. If the variables are defined outside any subroutines and functions, they are global and can be accessed by any unit in the same project.

If variables are defined inside a routine, then these local variables are not accessible outside these routines. Since scripts are typeless, variables are not initialized with their types.

The local variables inside a procedure are automatically initialized.

Variable Initialization

view sourceprint?
1
Sub Example
2
  Dim X
3
  Dim s
4
  ' x set to 0
5
  x =  0
6
  ' s set to empty
7
  s = ""
8
End Sub

Subroutines and Functions

VBScript allows two kinds of procedures; subroutines and functions — a function returns a value only. The syntax of calling a subroutine or function in a script is:

Call SubRoutineA(parameters)
...or
SubRoutine parameters

Subroutine example

view sourceprint?
1
Sub SetTheHeight AHeight
2
  Set Component.Height = AHeight
3
End Sub

Function example

view sourceprint?
1
Function Addone(value)
2
  AddOne = Value + 1
3
End Function

Another Function example

view sourceprint?
01
Function Test(s)
02
 Test = S + " rules.."
03
End Function
04
  
05
Sub DisplayName (sName)
06
 MsgBox sName
07
End Sub
08
  
09
Sub Main
10
Dim S
11
 S = "Altium NEXUS"
12
 DisplayName Test(s)
13
End Sub

Parameters and Arguments

In VBScript, a procedure declaration normally has a list of parameters — note that variables are considered typeless and the scripting system works out automatically what the variable types are. The value used in place of the parameter when you make a procedure call is called an argument.

Example of a subroutine with a parameter

view sourceprint?
1
Sub DisplayName (sName)
2
  MsgBox "My Name is " & sName
3
End Sub

Example of calling a subroutine

view sourceprint?
1
Sub Main
2
  DisplayName "Altium NEXUS  Rules"
3
End Sub

Note that the use of the Call keyword to invoke a subroutine or a function is optional (maintained for backward compatibility).

Comments in Scripts

In a script, comments are non-executed lines of code that are included for the benefit of the programmer. Comments can be included virtually anywhere in a script.

With VBScript comments:

• Any text following ' are ignored.
• Any text following Rem are ignored.

Example

view sourceprint?
1
' This whole line is a comment
2
REM this whole line is also a comment
3
DocName = Document.Name ' Get name of active document

Splitting a Script Line

In VBScript, each code statement is terminated on the line (by a CR/LF combination) to indicate the end of the statement. VBScript allows you to write a statement on several lines of code, to split a long instruction over two or more lines, using the underscore character (_).

VBScript does not put any practical limit on the length of a single line of code in a script. However, for the sake of readability and ease of debugging, it is 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 it can be broken into multiple lines, and this code will be treated by the VB interpreter as if it were written on a single line.

Unformatted code example

1
If Not (PcbApi_ChooseRectangleByCorners(BoardHandle,"Choose first corner","Choose final corner",x1,y1,x2,y2)) Then EndIf

Formatted code example

view sourceprint?
1
If Not (PcbApi_ChooseRectangleByCorners(BoardHandle,_ 
2
                                        “Choose first corner”,_ 
3
                                        “Choose final corner”,_ 
4
                                        x1,y1,x2,y2)) Then EndIf

Using Altium NEXUS Object Models Copy Link Copied

The biggest feature of the scripting system is that the Interfaces of Altium NEXUS objects (Object Interfaces) are available to use in VBScripts. For example, you can update design objects on Schematic and PCB documents through the use of Schematic Interfaces and PCB interfaces respectively.

The Altium NEXUS Object Interfaces are available for use in any script. Normally in scripts, there is no need to instantiate an interface. The interface representing an existing Altium NEXUS object is extracted, and from this interface, the embedded or aggregate interface objects can be extracted to get or set their property values.

To access a PCB document and its data objects, you first invoke the PCBServer function. By convention, interface names are prefixed by an I character — for example, IPCB_Board represents an interface for an existing PCB document in Altium NEXUS.

Example

view sourceprint?
1
' Checks if the current document is a Schematic document
2
  If SchServer Is Nothing Then Exit Sub
3
  Set CurrentSheet = SchServer.GetCurrentSchDocument
4
  If CurrentSheet Is Nothing Then Exit Sub

To have access to a PCB document, invoke the PCBServer.

Creation of a PCB Object Using the PCB Object Model

view sourceprint?
01
Sub ViaCreation
02
  Dim Board
03
  Dim Via
04
  Set Board = PCBServer.GetCurrentPCBBoard
05
  If Board is Nothing Then Exit Sub
06
  ' Create a Via object
07
  Via = PCBServer.PCBObjectFactory(eViaObject, eNoDimension, eCreate_Default)
08
  Via.X = MilsToCoord(7500)
09
  Via.Y = MilsToCoord(7500)
10
  Via.Size   = MilsToCoord(50)
11
  Via.HoleSize   = MilsToCoord(20)
12
  Via.LowLayer   = eTopLayer
13
  Via.HighLayer = eBottomLayer
14
  ' Put this via in the Board object
15
  Board.AddPCBObject(Via)
16
End Sub

Objects, Interfaces, and Functions

Altium NEXUS Objects, Interfaces, and Functions can be accessed in scripts from the following:

• Client API
• PCB Server API
• Schematic Server API
• Work Space Manager Server API
• Nexus API
• Altium NEXUS API functions
• Parametric processes

Reserved Words and Functions Copy Link Copied

The scripting system supports the VBScript language which is derived from the Microsoft Active Scripting language technology. The reserved words VBScript are:

A, B
Abs, Array, Asc, Atn
C
Call, Case, CBool, CByte, CCur, CDate, CDbl, Chr, CInt, Class, CLng, Const, Conversions, Cos, CreateObject, CSng, CStr
D, E
DateAdd, DateDiff, DatePart, DateSerial, DateValue, Day, Derived Math, Dim, Do, Each, Erase, Escape, Empty, Eval, Execute, Exit, Exp
F, G, H
False, Filter, For, FormatCurrency, FormatDateTime, FormatNumber, FormatPercent, Function GetLocale, GetObject, GetRef, Hex, Hour
I, L, M
If, Is, InputBox, Instr, InStrRev, Int, IsArray, IsDate, IsEmpty, IsNull, IsNumeric, IsObject, Join, LBound, LCase, Left, Len, LoadPicture, Log, LTrim, Maths, Mid, MInute, Month, MonthName, MsgBox
N, O
Next, Nothing, Now, Null, Oct, On Error
P, R
Private, Property, Public, Randomize, ReDim, Rem, RTrim, Replace, RGB, Right, Rnd, Round
S, T
ScriptEngine, ScriptEngineBuildVersion, ScriptEngineMajorVersion, ScriptEngineMinorVersion, Second, Select, Set, SetLocale, Sgn, Sin, Space, Split, Sqr, Stop, StrComp, String, StrReverse, Sub, Tan, Then, Time, Timer, Timeserial, TimeValue, Trim, True, TypeName
U, V, W, X, Y
UCase, Unescape, While, Wend, With, VarType, Weekday, WeekdayName, Year