Functions

A Function is a set of lines of code grouped together into a discrete unit. If you haven't already assigned a Script to an Event, when you select that Event in the Script Editor, it will display start and end lines for the main Function for that Script and in some cases, suggested Methods to be included.

The main Function is the one that is executed first when the Script is run.

You can create additional Functions within your Script which can then be called from within the main Function or from within other Functions. When a called Function ends, control returns to the calling Function at the position where it left off.

 

The syntax for a Function definition is:

Function functionname(param1,param2…)

[code statements]

End Function

 

A main Function is named after the Event to which it will be assigned, e.g. OnLoad. For this reason, the Event names are reserved words, i.e. they cannot be used for your own Functions or as variable names. In addition, the main Functions don't have any parameters and don't return a value when they end.

Other Functions that you write, however, can have parameters and can return a value, but these aren't essential. To create your own Function, simply type it in using the syntax above, below the main Function's End Function statement. To include parameters, enter the names of each parameter, separated by commas, in a list in parenthesis after the Function name.

For example:

Function OnLoad()

[code statements]

End Function

 

Function MyFunction(FirstName, Surname)

[code statements]

End Function

If a Function has no parameters, you must still include the parentheses at the end, but leave them empty as shown above for the OnLoad Function.

 

To call your new Function, you simply type in its name within the Script at the point at which you want to run it, e.g.:

Function FirstJob()

Dim JobRef

[code statements]

JobRef = GetJob()

[code statements]

End Function

In this example, the FirstJob Function calls a second Function, GetJob, which will be a Function you have defined elsewhere.

 

To call a Function which does not return a value, you just include a line which contains the name of your Function and any required parameters in brackets, e.g. MyFunction(FirstName, Surname).

To return a value from a Function you define, when you call the Function, you need to include a variable for the Return Value to be placed into, e.g. Rtn = MyFunction(FirstName, Surname). Within your Function you then set an undeclared variable with the same name as the Function to the value you want to return to the calling Function.

For example, in the following code we will create two functions – MyFunction, which returns "True" or "False" by setting the undeclared variable MyFunction to equal the required return value, and MyFunction2, which doesn't return a value:

Function OnLoad()

Dim Rtn

Dim FirstName

Dim Surname

[code statements]

Rtn = MyFunction(FirstName, Surname)

MyFunction2

[code statements]

End Function

 

Function MyFunction(FirstName, Surname)

If FirstName = "Ann" Then

MyFunction = "True"

Else

MyFunction = "False"

End If

End Function

 

Function MyFunction2()

[code statements]

End Function

 

In this example, if the name passed into the Function, MyFunction, includes the first name "Ann", then MyFunction will return the string "True" to the OnLoad Function, otherwise it will return "False". The returned value will be placed into a variable called Rtn. In this example, we used the '=' operator to cause the value of Rtn to be set equal to the return value.

The MyFunction2 Function has no parameters and is run without returning any value. Notice that because it has no parameters you can omit the () from the end of the call, if you prefer. The () must be included, however, in the function declaration, i.e. the Function MyFunction2() line.

You will notice the three 'Dim' statements at the beginning of the function – these are used to define variables. We also used the If statement to allow us to perform different actions depending upon the value of the FirstName parameter and, as mentioned earlier, we used the '=' operator. All these are discussed further in the following topics: Variables, Statements and Operators.

 

The scope of user-defined Functions depends upon where you define them: