Subroutines and Functions

Writing a long or complicated script may be easier to manage if you divide the script into smaller pieces called procedures. A procedure is a separate sequence of instructions that you can call from multiple places within your script. The BASIC language provides many predefined procedures for performing frequently needed tasks, and, in fact, the methods provided by the Surfer automation objects are themselves procedures.

When you call a procedure, the instructions in the procedure are executed. When the procedure finishes its task, it returns control to the instruction that called the procedure. The Scripter BASIC language distinguishes two types of procedures: functions and subroutines. Functions return a value, whereas subroutines do not.

Subroutines and functions may accept one or more values, called arguments. Arguments are passed to a procedure by listing them after the procedure name. If there is more than one argument, the arguments must be separated by commas. For example:

x = Cos (0) 'Returns the cosine of the argument (returns 1)

a$ = Left("AgAuPb",2) ' Returns the left-most characters (returns "Ag")

Wait 5 ' Waits for 5 seconds

Cos, Left, and Wait are procedures built-in to the BASIC language. Cos and Left are functions which return values to the caller. Wait is a subroutine, and, by definition, it does not return a value. The Wait subroutine waits for the number of seconds specified by its argument (5 seconds in this example) before returning control to the calling location.

The arguments passed to a function must be enclosed in parentheses if the function's return value is used. If the function's return value is not used, the arguments may be listed without enclosing them in parentheses. Arguments passed to a subroutine are never enclosed in parentheses.

Writing Subroutines

To define subroutines within a script, use the Sub statement. Subroutine and function definitions cannot be nested within other procedures. That is, the Sub statement must appear after the End Sub statement of any preceding subroutine definitions. The syntax for a subroutine definition is:

Sub name ( arguments )

statements

End Sub

Where name represents the name you want to give the subroutine, arguments represents a list of arguments names and types, and statements represents the instructions that comprise the body of the subroutine. There is no limit to the number of instructions you can include between the Sub and the End Sub lines. Consider the definition of a Main procedure and another subroutine:

Sub Main

MultipleBeep 25 ' call the MultipleBeep subroutine

End Sub

Sub MultipleBeep (count As Integer)

For i = 1 To count

Beep

Wait 0.5 ' Wait one-half second between beeps

Next

End Sub

Each time the MultipleBeep procedure is called, the instructions between its Sub and End Sub statements are executed.

If the subroutine accepts arguments, the arguments are defined following the subroutine name using a format similar to the Dim statement. The argument definition list must be enclosed in parentheses, and argument definitions are separated by commas if there is more than one. When a subroutine is called, the variables listed in the argument list are automatically assigned the values passed in from the calling procedure.

Writing Functions

Functions are defined using the Function statement much the same as subroutines are defined with the Sub statement. Like subroutines, function definitions cannot be nested within other procedures. Unlike subrouties, functions can return a value to the calling procedure. The syntax of a function definition is:

Function name ( arguments ) As type

statments

End Function

Where name is the function name you want to use, arguments is a list of arguments names and types, type is the type of the value returned by the function, and statements represents the instructions in the body of the function. To return a value from a function, assign a value to a variable with the same name as the function itself. For example:

Function hypotenuse (a As Double, b As Double) As Double

c = a * a + b * b ' The built-in Sqr function computes the square root

hypotenuse = Sqr (c) ' Set the function's return value

End Function

You define the list of arguments accepted by a function the same way as you define the arguments accepted by subroutines.

Built-in Functions and Procedures

Numerous useful functions and subroutines are built into the Scripter BASIC language. These routines can help you perform some of the most commonly required programming tasks. Functions for processing strings, performing mathematical calculations, error handling, working with disk files, and many others are available.

If you are not already familiar with the Visual BASIC for Applications programming language, it will be worth your time to review the list of available subroutines. This list is found by selecting Help | BASIC Language Help in Scripter.

Next: Using Surfer Objects