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 pre-defined procedures for performing frequently needed tasks, and, in fact, the methods provided by the Grapher 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:
'Returns the cosine of the argument (returns 1)
x = Cos(0)
'Returns the left-most characters (returns "Ag")
a$ = Left("
'Waits for 5 seconds
Wait 5
Cos, Left, and Wait are procedures built-in to the BASIC language.
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:
Subname ( arguments )
statements
End Sub
where name represents the name you want to give to 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 subroutines, functions can return a value to the calling procedure. The syntax of a function definition is:
Functionname ( arguments ) Astype
statements
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 are 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
'The built-in Sqr function computes the square root
c = a * a + b * b
'Set the function's return value
hypotenuse = Sqr(c)
End Function
The list of arguments accepted by a function is defined 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 routines. This list is found by selecting Help | BASIC Language Help in Scripter.