Subroutines and Functions

Old Content - visit altium.com/documentation

Parent page: VBScript

VBScript subroutines and Functions

This section provides an overview of using subroutines and procedures in Altum Designer VisualBasic scripts.

Passing Parameters to Procedures

When a function or subroutine (a procedure/method) that can accept parameters is defined in a script, variables can be passed to the function or subroutine in two ways: by reference or by value, using ByRef or ByVal respectively.

To declare the method that parameters are passed to, use the ByRef or ByVal keywords in the parameter list when defining the function or subroutine in a Sub or Function statement. For example, the following code fragment defines a subroutine that accepts two parameters. The first is passed by value and the second by reference:

Sub Test (ByVal Param1 As Integer , ByRef B As String)

The difference between the two methods is that ByRef passes a reference to the variable and allows the subroutine/function to make changes to the actual variable that is passed in as parameters. This is the default method of passing parameters and is used if the method is not explicitly declared.

ByVal passes the value of the variable only. The subroutine or function can use this value, but the original variable passed is not altered.

The following examples illustrate the differences between methods. The main procedure is as follows:

 Sub Main   Dim X, Y   X = 45 : Y = "Number"   Test X, Y   ' Call to a subprocedure called Test.   MsgBox X    MsgBox Y End Sub

The above procedure includes a call to a subprocedure Test — see below.

If the subroutine is defined as follows:

 Sub Test (ByRef A, ByRef B)   B = B & " = " & A : A = 10*A End Sub

Then the variables X and Y in the main procedure are referenced directly by the subroutine. The result is that the values of X and Y are altered by the subroutine, so that after Test is executed; X = 450 and Y = "Number = 45". This is the default behaviour when the method is not explicitly declared.

If, however, the subroutine is defined as follows:

 Sub Test (ByVal A, ByVal B) B = B & " = " & A : A = 10*A End Sub

Then after Test is executed the main procedure reports; X = 45 and Y = "Number" — that is, they remain unchanged.

Alternatively, if the subroutine is defined as follows(mixed methods):

 Sub Test (ByRef A, ByVal B)   B = B & " = " & A : A = 10*A End Sub

Then after Test is executed, X = 450 and Y = "Number", since Y was passed by value, it remains unchanged.

You can override the ByRef setting of a function or subroutine by putting parentheses around a variable name in the calling statement.

Calling Test with the following statement:

Test (X), Y

...would pass the variable X by value, regardless of the method defined for that parameter in the procedure definition.

Date and Time routines

The VBScript language supports a set of Date/Time routines as outlined below:

Date

Day

Hour

IsDate

Minute

Month

Now

Second

Time

Year

 

 

File IO routines

The VBScript language supports the following set of File IO routines:

Dir

FileLen

FileTimeDate

FileCopy

Kill

Name

RmDir

MkDir

 

Math Routines

The VBScript language supports the following set of Math routines:

Abs

Atn

Cos

Exp

Log

Not

Oct

Rnd

Sin

Sqn

Tan

 

String Routines

The VBScript language supports a range of String routines as outlined below:

Asc

Chr

Format

InStr

InStrRev

LCase

Len

Left

Mid

Right

Str

Trim

LTrim

RTrim

UCase

Server Process routines

The server process routines are used when dealing with processes in scripts, especially where there is a need to extract (get) or set strings for the process parameters.

To execute processes and parameters in scripts, use the following functions:

AddColorParameter

AddIntegerParameter

AddLongIntParameter

AddSingleParameter

AddWordParameter

GetIntegerParameter

GetStringParameter

ResetParameters

RunProcess

Useful functions

SetCursorBusy

ResetCursor

CheckActiveServer

GetActiveServerName

GetCurrentDocumentFileName

RunApplication

SaveCurrentDocument

 

 

Useful Dialogs

ConfirmNoYes

ConfirmNoYesCancel

ShowError

ShowInfo

ShowWarning

 

You are reporting an issue with the following selected text and/or image within the active document: