Procedures

In this chapter, you will see how VBScript procedures can be used to improve the overall organization and manageability of your scripts. You will learn about the two types of procedures supported by VBScript, subroutines and functions. This chapter will cover how to use procedures to control variable scope by defining local and global variables. You will also learn how to create event handlers that react to browser events and will examine the types of browser events to which VBScript can react. Finally, you will examine VBScript's complete collection of built-in functions.

Organizing VBScript into Procedures

VBScript procedures provide the basic building blocks of VBScript organization. Procedures allow you to create modular scripts that organize statements into logical groups that can be executed as a unit. VBScript supports two different types of procedures:

• Function. A type of procedure that can return a result back to its calling statement
• Subroutine. A type of procedure that does not return a result back to its calling statement

Procedures have two main benefits: First, they provide a means of organizing VBScripts into a more manageable format. Second, procedures allow you to create reusable code and reduce the overall size of scripts.

Enhanced Script Maintenance

Procedures allow you to create scripts that are easier to maintain by allowing you to group related statements together and to execute them as a unit. Therefore, as a general rule, you should use procedures as the primary organization construct for your VBScripts. By developing modular code using VBScript, you make your scripts easier to read and maintain. For example, by grouping related statements together in a procedure, you make them easier to find. You also make the script easier to update, allowing individual modules or procedures to be updated without having to make substantial changes to other parts of the script.

By making scripts easier to manage, procedures allow you to add more complexity without necessarily making them more difficult for you to work with or maintain. As suggested in Chapter 2, "Errors, Constants, and Variables," when developing scripts that will be run using the WSH, consider developing a VBScript template similar to that in the following example.

'************************************************************************* 'Script Name: ScriptName.vbs 'Author: Author Name 'Created: mm/dd/yyyy 'Description: Place a brief description of the script here '************************************************************************* 'Initialization Section 'Main Processing Section 'Procedure Section

Using this template, you would place all subroutines and functions in the Procedure section. This provides a consistent organization to your scripts by providing a predictable location for storing and finding procedures. The important thing is to group your procedures together where you can easily find them in your VBScripts. Most VBScript programmers choose to store their subroutines and procedures at the end of their scripts.

When developing VBScripts that are embedded inside HTML pages, most programmers generally locate their subroutines and functions in a VBScript placed in the HEAD section. This helps to ensure that all procedures have been initialized before being called upon by VBScripts or event handlers located in the HTML page's BODY section.

Reusable Code

Functions and subroutines help make for smaller scripts by allowing the creation of reusable modules of code that can be called upon as many times as necessary from any location within a script. Therefore, functions and subroutines should be used in any situation where a particular task needs to performed more than once within a script.

Procedures also make script maintenance easier because you only have to modify the code located in one procedure instead of making the same change over and over again to code that would otherwise be duplicated throughout a script.

Subroutines vs Functions

Subroutines and functions perform nearly identical roles within VBScripts. Both provide a means for grouping and executing collections of related statements. Both provide a means of limiting variable scope, which is discussed later in this chapter. They even share a similar syntax. Where they differ is in their ability to return data back to the statement that calls them. Functions provide this capability, whereas subroutines cannot return a result back to their calling statement.

Subroutines

Subroutines are used to execute a collection of statements without returning a result to a calling statement. Once executed, a subroutine returns processing control back to the statement that follows its calling statement.

Subroutines are created using the VBScript Sub statement. The Sub statement defines the name of the subroutine and any arguments that it expects to receive. The syntax for the Sub statement is shown below.

[Public | Private] Sub name [(arglist)] statements End Sub

Public and Private are optional keywords. The Public keyword specifies that the subroutine can be called upon by other procedures located within the script. The Private keyword specifies that the subroutine cannot be called upon by other procedures within the script. Name is the name assigned to the subroutine and must be unique within the script. Arglist is a list of comma delineated arguments that can be passed to the subroutine when it is called.

To call a subroutine, you type its name in the following format:

SubroutineName()

The closing parentheses characters () are required. You can call a subroutine and pass it arguments by specifying the arguments, separated by commas, within the parentheses, as demonstrated below.

SubroutineName(arg1, arg2, arg3, ... argn)

For example, the following VBScript statement defines a subroutine called AboutRoutine().

Sub AboutRoutine() MsgBox "UserAcctMgr.vbs" & vbCrLf & vbCrLf & _ "Copyright Jerry Ford 2003" & vbCrLf & vbCrLf & _ "For more information about UserAcctMgr.vbs please contact " & _ "jlf04@yahoo.com", ,"About Sample Script" End Sub

This subroutine might be included as part of a larger script to provide information about the script. When called, AboutRoutine() uses the MsgBox() function to display information about the script. This subroutine has not been designed to accept any arguments as input and can be called from anywhere in the script using the following statement.

AboutRoutine()

When executed, this subroutine displays the pop-up dialog box shown in Figure 4.1.

Figure 4.1: Using a subroutine to display information about a script

The following example demonstrates how to define a subroutine that accepts and processes one argument when called upon to execute.

Sub DisplayMsg(strMsgText) MsgBox strMsgText, , "VBScript Subroutine Demo" End Sub

This subroutine could be added to any VBScript to provide a generic message display procedure. It accepts a single argument, which in the case of this example would be a text string passed to it by its calling statement. For example, the following statement could be used to execute the DisplayMsg() subroutine, which results in displaying the pop-up dialog box shown in Figure 4.2.

Figure 4.2: Viewing a message displayed using a generic message display subroutine

DisplayMsg("This message will be displayed by a message display subroutine.")

Functions

Functions are similar to subroutines, except that they also provide the ability to return a result to their calling statements. The syntax for functions is outlined below.

[Public | Private] Function name [(arglist)] statements End Function

Public and Private are optional keywords. The Public keyword specifies that the function can be called upon by other procedures located within the script. The Private keyword specifies that the function cannot be called upon by other procedures within the script. Name is the name assigned to the function and must be unique within the script. Arglist is a list of comma delimitated arguments that can be passed to the function when it is called.

For example, the following function represents a rewrite of a previous subroutine that displays information about a script in a pop-up dialog box.

Function AboutRoutine() MsgBox "UserAcctMgr.vbs" & vbCrLf & vbCrLf & _ "Copyright Jerry Ford 2003" & vbCrLf & vbCrLf & _ "For more information about UserAcctMgr.vbs please contact " & _ "jlf04@yahoo.com", ,"About Sample Script" End Function

This function can be called using the following statement from anywhere within the script that defines it.

AboutRoutine()

When used in this manner, there is no advantage to using a function over a subroutine. The advantage of using a function in place of a subroutine is the function's ability to return a result to its calling statement. In order to return a result back to its calling statement, a function must define a variable with the same exact name as the function and then assign the result that is to be returned to that variable. When the function stops executing, the value is then returned to the calling statement. For example, the following function might be used to collect the name of a file from the user.

Function GetFileName() GetFileName = InputBox("Please type the name of the file you wish to open.") End Function

The name of the function is GetFileName(). It uses the VBScript InputBox() function to collect the name of a file from the user and assigns the file name typed by user to a variable named GetFileName. Note that the name of the variable is exactly the same as the name of the function (less the parentheses). To execute this procedure, the calling statement can reference it, as shown below.

strFileName = GetFileName()

In this example, the name of the file that is returned by the function is assigned to a variable name strFileName. Another way to call the function would be to include a reference to it within a VBScript statement, as shown below.

MsgBox "Click on OK to delete " & GetFileName()

In this example, the MsgBox() function includes a reference to the GetFile-Name() function and substitutes the results returned by that function into the message that it has been set up to display.

Functions can also accept arguments passed to them at run time, as demonstrated below.

Function DisplayMsg(strMsgText) MsgBox strMsgText, , "VBScript Subroutine Demo" End Function

Controlling Variable Scope

Procedures provide VBScript with the ability to localize or isolate variables. Any variable defined outside of a procedure is global in scope, meaning that it can be referenced from any location within the script. A variable with a local scope, on the other hand, is one that is defined within a procedure and can be accessed only from within that procedure. Local variables exist only as long as the procedure that defined them is executing.

By localizing variable values, you eliminate the possibility of accidentally modifying a variable outside of the procedure where it was created. As a programming technique, it is generally preferable to localize variables as much as possible. The following example demonstrates the differences between local and global variables.

'************************************************************************* 'Script Name: Script 4.1.vbs 'Author: Jerry Ford 'Created: 01/04/2003 'Description: This script demonstrates global and local variable scopes '************************************************************************* 'Initialization Section Option Explicit Dim X, Y 'Main Processing Section X = 10 GetNewNumber() MsgBox "X = " & X & " Y = " & Y 'Procedure Section Function GetNewNumber() Dim Y Y = 20 End Function

In this script, two variables are defined, X and Y. The X variable and its value are both defined in the script's Main Processing Section and are global in scope. Next, the script executes the GetNewNumber() function, which defines the Y variable and sets its value. Once the GetNewNumber() function is finished, processing control returns to the Main Processing Section, which then uses the VBScript MsgBox() function to try and display the values assigned to X and Y. However, only the value of X can be displayed because the Y variable no longer exists.

Figure 4.3 shows the output produced when this script is executed by the WSH.

Figure 4.3: A demonstration of variable scope within and outside of VBScript procedures

Browser Event Handling

Within the context of client-side Web page development, VBScript procedures have a special role in building event handlers that respond to browser events. This adds interactivity to Web pages and allows front-end processing to be performed on the client computer. An event is an occurrence of an action within a browser. For example, a mouse click on an image, button, or link represents a click event. Other examples of events include double-clicking on Web page objects, typing text into form elements, clicking on form buttons, and moving the pointer over and off of objects. Browser events also occur when Web pages load or unload.

To react to an event, you must add event handlers to your scripts. An event handler is a trap that recognizes when an event occurs and executes one or more VBScript statements. For example, if a visitor clicks on a form's submit button, the click event associated with that button can be used to trigger the execution of an event handler that performs form validation.

By defining functions and subroutines and storing them in the head section of an HTML page, you can create a library of event handlers that can be associated with any object on a Web page.

Examining Events and Event Handlers

Table 4.1 provides a list of browser events for which you can define event handlers. Table 4.1 also provides the name of the event handler associated with each event and a description of the event and event handler. As you can see, event handlers are named by adding on to the beginning of the event name with which it is associated.

Setting Up Event Handlers

Events are associated with specific objects. Likewise, event handlers are associated with specific events and objects. When an event occurs, its associated event handler, if one has been written, is automatically executed. There are three different ways in which to set up the execution of an event handler. The first option is to embed the event handler inside an HTML tag, as demonstrated below.

In the case of this example, the onLoad event is automatically triggered when the HTML page is loaded by the browser, displaying a pop-up message. While convenient for performing tasks that require minimal coding, this option is limited. Another option provided by VBScript is to set up event handlers, as demonstrated below.

The third and most commonly used option is to define event handlers that call procedures stored within VBScripts located within the HTML page's HEAD section, as demonstrated below.

Sub SubmitButton_onMouseOver window.status = "Click here to submit your request." End Sub

When used in conjunction with event handlers, procedure names are created by combining the name of an object button and the name of the appropriate event handler. For example, the previous subroutine is automatically triggered whenever the pointer is moved over a form button named SubmitButton on the HTML page. When executed, it displays a text message in the browser's status bar located at the bottom of the browser.

To further demonstrate the use of VBScript procedures as constructs for storing statements that are called by event handlers, look at two more examples. In the first example shown below, an HTML page has been set up that contains a VBScript in its HEAD section. This VBScript defines a single function called ShowGreetingMsg(). This function will execute when called by the onLoad event handler specified in the

tag example, as highlighted below.

Script 4.2 - onLoad event handler exampleonLoad=ShowGreetingMsg()> onLoad event handler example

Figure 4.4 shows the output produced when this HTML page is loaded by Internet Explorer.

Figure 4.4: A pop-up dialog box displayed by a function that has been called by a VBScript event handler

Another popular use of event handlers is in the creation of animated rollover effects, which change the appearance of a link, image, or object in some manner whenever the pointer is moved over or off of the object. Rollovers can be created using the onMouseOver and onMouseOut events, which are listed below.

• onMouseOver. Triggered whenever the pointer is moved over an object
• onMouseOut. Triggered whenever the pointer is moved off of an object

For example, the following script demonstrates how to set up an HTML page with two rollover links. One is for the Premier Press Web site and the other is for Microsoft's Web site.

Script 4.3 - A demo of how to creak a link rollover<a href="http://www.premierpressbooks.com" name="Premier">Premier</a>

<a href="http://www.microsoft.com" name="Microsoft">Microsoft</a>

In order to set up a rollover for each link, two functions must be set up as event handlers for each link. The first function defines the statements to be executed for the onMouseOut event handler and the second function defines the statements to be executed for the onMouseOver event handler. Notice that unlike the previous example in which the

tag explicitly called the function specified by the onLoad event handler, the functions in this example are automatically associated with links because of the manner in which their names were formulated.

When executed, these functions modify the color of the text used to display each link, depending on which event handler is being executed. Figure 4.5 shows the output produced when this HTML page is loaded by Internet Explorer. However, it is difficult to see how the rollover links work from an examination of Figure 4.5. To get a better understanding, create and run this script yourself.

Figure 4.5: Creating rollovers using event handlers

Built in Functions

In this chapter, you learned how to create your own custom functions. Using functions, you can create modular scripts and group related VBScript statements together in some logical manner. VBScript also provides a large collection of ready-to-use built-in functions that you can reference from your VBScripts. Using built-in VBScripts saves you the time and trouble required to reinvent a function to perform a task for which Microsoft has already provided a solution. This speeds up script development time while making for smaller scripts that are easier to manage. Table 4.2 provides a list of VBScript's built-in functions.

As a quick example of the benefit of using a built-in VBScript function to save time and simplify your VBScripts, look at the following custom function, which consists of five VBScript statements.

Function SqrRootSolver() intUserInput = InputBox ("Type a number", "Custom Square Root Function") X = 1 For Counter = 1 To 15 X = X - ((X^2 - intUserInput) / (2 * X)) Next MsgBox "The square root of " & intUserInput & " is " & X End Function

The five statements contained in the function ask the user to type a number and then use a For…Next loop to determine the square root of that number using some fairly sophisticated math. Figures 4.6 and 4.7 demonstrate the operation of this function.

Figure 4.6: Creating a custom function that determines the square root on an input number

Figure 4.7: Displaying the results of the square root calculation

Using VBScript's built-in Sqr() function, you can perform the same task with just two lines of code, as shown below.

UserInput = InputBox ("Type a number", "Square Root Calculator") MsgBox "The square root of " & UserInput & " is " & Sqr(UserInput)

Not only does using the built-in VBScript Sqr() function reduce the number of lines of code, but it also greatly reduces the complexity of the script, thus reducing the amount of time that it takes to develop it.

Summary

In this chapter, you learned how to enhance your VBScripts by organizing them into subroutines and functions. This included developing an understanding of the differences between these two types of procedures and how to leverage the power and convenience provided by VBScript's built-in collection of functions. In addition to making scripts easier to read and maintain, procedures provide a mechanism for limiting variable scope. You also learned how to call VBScript procedures using event handlers in order to develop VBScripts that can react dynamically to both user and browser activity.