VBScript

Last week I introduced you to functions and procedures within VBScript,
and the differences between the two. This week we create a function and
discuss the syntax.

To explain this topic, we need to define what our function will do.
Let's look at a very basic function that will take three numbers, add
them together and return a result to the calling line of code. Remember
that functions have the ability to return values, whereas procedures
cannot. Since our function needs to return a value, we need to define
it using the 'Function' keyword as opposed to the 'Sub' keyword.

Here is the code for the above example:

------------------- Begin code snippet -------------------

Dim Result, num1, num2, num3

num1 = 3
num2 = 4
num3 = 5

Result = add(num1, num2, num3)
WScript.Echo(num1 & " + " & num2 & " + " & num3 & " = " & Result)

'Function to add 3 numbers together
Function add(num1, num2, num3)
Dim tempResult
tempResult = num1 + num2 + num3
add = tempResult
End Function

-------------------- End code snippet --------------------

If you copy the above code snippet into a text file, save it as
c:\scripts\functions.vbs, open a command prompt and then type the
following:

cscript c:\scripts\functions.vbs

you will see the following output:

------------------- Begin output -------------------

Microsoft (R) Windows Script Host Version 5.6
Copyright (C) Microsoft Corporation 1996-2001. All rights reserved.

3 + 4 + 5 = 12
--------------------- End Output -------------------

Let's step through the code to see what is happening. In the first part
of our script we define 3 variables (num1, num2, and num3) and assign
each of them a value. Next we call our function and assign the return
value from the function to the variable 'Result'. At this point the
script jumps to the code for the function and execution continues within
the function. Looking at the function, we see that it accepts three
parameters (numA, numB, and numC). Since we called our function with
the call 'Result = add(num1, num2, num3)', the function assigns the
three new variables as follows:

numA = num1
numB = num2
numC = num3

So now the function can manipulate numA, numB, and numC without
impacting the original variables num1, num2, and num3. The function
then takes the three variables, adds them together, and assigns the
result to tempResult. Now, the second to last line of code in this
function is key to the usage of functions. The statement is 'add =
tempResult', which basically tells the your script to have the 'add'
function return a value equal to the value contained in the variable
'tempResult'. In this case the value is '12'. Now when we hit the line
that says 'End Function' our function terminates and the program control
is returned to the calling line of code which was 'Result = add(num1,
num2, num3)'. Now since the 'add' function returned a value to this
section of code, you can actually picture this line to look like 'Result
= 12', and then the code continues from there and displays the result in
the format we have specified.

As you can see, functions and their counterpart, procedures, are a very
useful features in VBScript.

Next week we will begin discuss a discussion on error handling withing
VBScript.