Data Collection, Notification, and Error Reporting

In this chapter, you will learn how the VBScript InputBox() and MsgBox() functions display pop-up dialog boxes that can be used to collect user input and to display output. You will also learn how to control the presentation of text within these pop-up dialog boxes, as well as how to interrogate the input specified by the user. In addition, this chapter will present information on error handling, including how to generate more user-friendly error messages.

Interacting with Users

Depending on the programming environment for which you are developing your VBScripts, you have a number of different options for displaying output and interacting with users. For example, within HTML pages you can display output using methods provided by the Window and Document objects. These methods are described in Table 6.1.

When developing scripts for the WSH, programmers have the option of displaying output using methods provided by the WScript and WshShell objects. These methods are specified below.

• Echo(). A method belonging to the WScript object that displays text messages in either the Windows console or in a pop-up dialog box
• Popup(). A method belonging to the WshShell object that displays text messages in pop-up dialog boxes with control over icon and button selection and the ability to determine the button clicked by the user

In addition to the environment-specific output options provided by Internet Explorer and the WSH, VBScript provides a pair of functions that are always available for displaying output and collecting user input. These two functions are described below.

• InputBox(). Displays a pop-up dialog box that collects text input from the user using a text entry field
• MsgBox(). Displays a pop-up dialog box that contains a text message, one or more buttons, and an optional icon

The features and capabilities of the InputBox() and MsgBox() functions will be further explored throughout the rest of this chapter.

The InputBox() Function

The VBScript InputBox() function provides the ability to prompt the user to type data input during script execution. This allows you to develop scripts that can interact directly with the user. The InputBox() function displays a pop-up dialog box that has the following capabilities:

• A text field used to collect user input
• The ability to display a text message up to 1,024 characters long
• OK and Cancel buttons that allow the user to control the pop-up dialog box

Defining the InputBox() Function

The syntax of the InputBox() function is outlined below.

Response = InputBox(Prompt[, Titlebarmsg][, Default][, Xpos] [, Ypos][, Hhelpfile, Context])

Response is a variant with a string subtype that stores the text supplied by the user. Prompt is a text message up to 1,024 characters long that provides instructions and directions for the user. Titlebarmsg is optional. When supplied, it displays its text in the pop-up dialog box's title bar. If omitted, the word "VBScript" will be displayed in the title bar. Default is optional. When used, it supplies a default answer that is automatically displayed in the pop-up dialog box's text field. Xpos and Ypos are optional measurements specified as twips. When used, Xpos specifies the distance from the left side of the display to the left side of the pop-up dialog box. Ypos specifies the distance from the top of the pop-up dialog box to the top of the display. Helpfile and Context are optional. They specify the location of an external file where context-sensitive help is available.

The following statement demonstrates how to use the InputBox() function.

strUserName = InputBox("Please enter your name") MsgBox ("Greetings " & strUserName)

The first statement in this example displays the pop-up dialog box shown in Figure 6.1. As you can see, it displays a message and waits for the user to either type in a name and click on the OK button or abort the operation by clicking on the Cancel button.

Figure 6.1: Using the InputBox() function to collect data input from the user

The InputBox() function returns the text typed by the user when the OK button is clicked. However, if the user clicks on OK without entering any text, or if the user clicks on the Cancel button, a zero-length string is returned (that is, ""). In the previous example, the data typed by the user is saved as a variant with a string subtype in a variable called strUserName. Figure 6.2 shows the pop-up dialog box displayed by the second statement shown above.

Figure 6.2: Greeting a user by name

InputBox() function parameters are position sensitive. If you do not use a specific parameter, you must substitute a comma in order to continue to add other parameters that follow the omitted parameter. For example, the following statements display the pop-up dialog box shown in Figure 6.3. This example will display a message and a default answer without specifying any message text for display in the pop-up dialog box's title bar.

Figure 6.3: Using the InputBox() function to display a pop-up dialog box with a default answer

strFileName = InputBox("Please specify a temporary file name.", ,"C:Temp")

Input Validation

Users can be completely unpredictable. It is therefore essential that you interrogate and validate all data returned by the InputBox() function to ensure that it complies with the requirements of your VBScripts. For example, you may write a script in which you intend to collect the user's name. However, instead of typing a name, the user might perform one of the following actions:

• Click on the Cancel button
• Press the Escape key
• Click on OK without typing any text

Each of these actions results in a zero-length string. The following statements demonstrate how to check for the presence of data when using the InputBox() function.

strUserName = InputBox("Please enter your name.", "User Questionnaire") If strUserName = "" Then MsgBox "You did not provide any information!" Else MsgBox "Greetings " & strUserName End If

The second statement checks to see whether the data returned by the InputBox() function and stored as strUserName is equal to "".

The following example shows another way to see whether the user has provided any data to the InputBox() function.

strChoice = InputBox("What do you prefer: Games, Utilities or Other?") If Len(strChoice) = 0 Then MsgBox "You did not enter any data." End If

In this example, the VBScript Len() function is used to see whether the value stored in strChoice is zero-length. Sometimes it may be appropriate to supply a default answer in the event that the user fails to provide any data, as demonstrated below.

strChoice = InputBox("What do you prefer: Games, Utilities or Other?") If Len(strChoice) = 0 Then strChoice = "Other" End If

In this example, the value of strChoice is automatically set equal to Other in the event that the user fails to type any data. There will be times in which supplying a default answer will not suffice. In these circumstances, you can wrap the InputBox() function inside a loop that iterates until the user provides a proper response. For example, the following statements use a Do…While loop to force the user to type quit when prompted by the InputBox() function in order to exit the loop.

Do While UCase(strChoice) <> "QUIT" strChoice = InputBox("What do you want to do?") If UCase(strChoice) <> "QUIT" Then MsgBox "Invalid option. Please specify your selection again." Else Exit Do End If Loop

In this example, the UCase() function is used to convert all user responses to uppercase. The user's response is then checked to see if the correct input has been supplied.

VBScript provides you with tools for controlling the format of the prompt message displayed by the InputBox() function. You can use any of the VBScript constants listed in Table 6.2 to format the text output.

The following example demonstrates how to display a menu of options using the InputBox() function and then to select the appropriate action based on the user's selection.

intAnswer = InputBox("Please enter the number of one of the " & _ "following options:" & vbCrLf & _ vbCrLf & vbTab & "-- Choices --" & vbCrLf & vbCrLf & _ "1. View copyright information." & vbCrLf & _ "2. View information about the script." & vbCrLf & _ "3. View help information." & vbCrLf, "Menu List") If IsNumeric(intAnswer) Then Select Case intAnswer Case 1 MsgBox "Copyright 2003, Jerry Lee Ford, Jr." Case 2 MsgBox "This script demonstrates how to format text in " & _ "InputBox() dialogs" Case 3 MsgBox "For additional assistance visit " & _ "msdn.microsoft.com/scripting" Case Else MsgBox "Invalid selection." End Select Else MsgBox "The only valid options are 1, 2 or 3." End If

Data Coercion

VBScript only supports the variant data type. However, it supports multiple variant subtypes. VBScript does its best to determine the type of data stored in a variable in order to associate it with the correct data subtype. Sometimes VBScript will not identify the data subtype in the manner in which you desire. To remedy this situation, VBScript provides two ways of changing data subtypes, implicit coercion and explicit coercion.

Implicit Coercion

The InputBox() function only returns string data regardless of what the user enters into its text field. However, VBScript provides ways around this. In most cases, VBScript is able to automatically convert data stored in variables as required by the situation. For example, if a user enters the number 66 as input into the text field of an InputBox() pop-up dialog box, VBScript will treat it as a string equivalent to "66". If a mathematical operation is performed that uses the variable, VBScript will automatically convert its subtype to numeric. This is known as implicit coercion.

Using implicit coercion, the following VBScript is able to automatically convert any number entered by the user from a string to a numeric value.

dblAnswer = InputBox("Enter the number", "Implicit Coercion Example") MsgBox TypeName(dblAnswer) dblAnswer = 100 + dblAnswer MsgBox TypeName(dblAnswer)

When executed, the second statement in this example displays the output shown in Figure 6.4, proving that the InputBox() function always returns a string value.

Figure 6.4: The InputBox() function always returns a string value

The third line in the script performs a mathematical operation, adding 100 to the number entered by the user. Using implicit coercion, VBScript automatically converts the value of the variable to a variant with a subtype of double. The output displayed by the last line in the script, shown in Figure 6.5, proves that the variable has been converted.

Figure 6.5: VBScript automatically attempts to convert a variable from one subtype to another as required by the situation

Explicit Coercion

While VBScript does its best to automatically adjust the subtype of a variable as each situation requires, there may be occasions when it fails to make the adjustment as you might expect. When this happens, you can attempt to use explicit coercion to force subtype conversion. VBScript provides a large number of conversion functions, as listed in Table 6.3.

The following example demonstrates the application of the CInt() conversion function.

intUserNumber = InputBox("Type a number between 0 and 9", _ "Type Your Answer") If IsNumeric(intUserNumber) = "True" Then intUserNumber = CInt(intUserNumber) If Len(intUserNumber) = 1 Then MsgBox "You entered " & intUserNumber Else MsgBox "Invalid selection!" End If Else MsgBox "Invalid non-number" End If

The InputBox() function is used to prompt the user to type a value between 0 and 9. To make sure that the user types a number and not a letter or special character, the IsNumeric() function is used. If a number is typed, then the value returned by this function will be equal to True. In this case the CInt() function is used to explicitly coerce the input value to an Integer value. While not strictly required in this example, the use of the CInt() function makes the programmer's intentions clearer.

Type Mismatch

If VBScript attempts to perform an operation on a variable that is not supported by its subtype, an error occurs. VBScript cannot perform arithmetic comparison of non-numeric data. For example, the following script prompts the user to type a numeric value between 1 and 9.

intAnswer = InputBox("Enter the number between 1 and 9", "Menu List") If intAnswer > 0 Then If intAnswer < 10 Then MsgBox "You entered " & intAnswer End if End If

If the user types a number between 1 and 9, a message is displayed. If the user types a number outside of this range, nothing happens. However, if the user types a letter or special character instead of a numeric value, a Type Mismatch error occurs, as demonstrated in Figure 6.6.

Figure 6.6: A Type Mismatch error occurs when VBScript attempts to perform a operation on a variant that is not supported by its subtype

To avoid the occurrence of Type Mismatch errors, you need to perform input validation. This typically involves testing variables to determine their subtype assignment using the TypeName() function or any of the subtype testing functions listed in Table 6.4.

The MsgBox() Function

The InputBox() function provides a convenient way to collect data whose value cannot be determined in advance from users. Often, however, you need to present the user with a limited range of choices from which you want to allow only one selection. You can accomplish this type of user interaction using the MsgBox() function. Like the InputBox() function, you can use VBScript string constants to control the presentation of the text displayed by the MsgBox() function. In addition, you have control over what types of buttons and icons are displayed.

Defining the MsgBox() Function

The syntax of the MsgBox() function is outlined below.

MsgBox(Prompt[, Buttons][, TitleBarMsg][, Helpfile, Context])

Prompt is a text message up to 1,024 characters long that provides instructions and directions to the user. Buttons is a value specifying which buttons and icons should appear in the pop-up dialog box. Titlebarmsg is optional. When supplied, it displays its text in the pop-up dialog box's title bar. If omitted, the word "VBScript" will be displayed in the title bar. Helpfile and Context are optional. They specify the location of external files where context-sensitive help is available.

The MsgBox() function provides the ability to customize four pop-up dialog box features. These features are outlined below.

• The combination of buttons to be displayed
• The icon to be displayed
• The default button
• The modality of the pop-up dialog box

Each of these options is described in the tables that follow. You have the chance to specify one option from each table when using the MsgBox() function to display a pop-up dialog box. Table 6.5 lists the different buttons that can be displayed by the MsgBox() function.

The following example demonstrates how to create a pop-up dialog box that displays an OK button.

MsgBox "Click on OK to continue."

Since the vbOKOnly constant represents the default selection for the MsgBox() function, it does not have to be specified. However, you can specify it as shown below and achieve the same results as shown in Figure 6.7.

Figure 6.7: Using the MsgBox() function to display a pop-up dialog box with an OK button

MsgBox "Click on OK to continue.", vbOKOnly

Alternatively, you can substitute the numeric value of the vbOKOnly constant as shown below.

MsgBox "Click on OK to continue.", 0

Table 6.6 lists the different icons that can be displayed by the MsgBox() function.

The following example demonstrates how to create a pop-up dialog box that displays OK and Cancel buttons as well as the question mark icon.

MsgBox "Click on OK to try again.", vbOKCancel + vbQuestion

Alternatively, you could rewrite this statement as shown below.

MsgBox "Click on OK to try again.", 1 + 32

You could also rewrite it as follows.

MsgBox "Click on OK to try again.", 33

The format of the first example is the clearest and easiest to read. Regardless of which of the above formats you use, the output shown in Figure 6.8 will always be the same.

Figure 6.8: Using the MsgBox() function to prompt the user for instructions

Table 6.7 provides a list of constants that you can use to specify a pop-up dialog box's default button.

The following example demonstrates how to create a pop-up dialog box that displays Yes, No, and Cancel buttons. In addition, the Cancel button has been set up as the default button.

MsgBox "Please select an option.", vbYesNoCancel + vbDefaultButton3

Figure 6.9 shows how the pop-up dialog box appears when this statement is executed.

Figure 6.9: Using the MsgBox() function to present the user with multiple options

Table 6.8 provides a list of constants that you can use to specify the modality of a pop-up dialog box produced by the MsgBox() function.

The following example demonstrates how to create a pop-up dialog box that displays Retry and Cancel buttons as well as the exclamation mark icon. In addition, the Cancel button has been set up as the default button and the pop-up dialog box has been set as the application model.

MsgBox "Click on Retry to try again.", vbRetryCancel + vbExclamation + vbDefaultButton2 + vbApplicationModal

Figure 6.10 shows how the pop-up dialog box appears when this statement is executed.

Figure 6.10: Using the MsgBox() function to create an application modal pop-up dialog box

Interrogating Results

In order to determine which button the user clicked on, you need to use the MsgBox() function, as demonstrated below.

intChoice = MsgBox("Would you like to continue?", vbYesNo, _ "Confirmation dialog")

Here the numeric value of the button that the user clicks on is returned by the MsgBox() function and is stored in a variable called intChoice. Table 6.9 outlines the possible values that the MsgBox() function can return. In the case of the previous example, a value of 6 is returned if the user clicks on the Yes button and a value of 7 is returned if the user clicks on the No button.

Handling VBScript Errors

Errors can occur in VBScripts for a variety of reasons, including syntax errors, invalid user input, and unavailable system resources. VBScripts automatically terminate their execution and display an error message when an error occurs. With proper planning and testing most, but not all, errors can be eliminated. Unfortunately, VBScript errors tend to be fairly cryptic and only serve to confuse most users.

In Chapter 2, "Errors, Constants, and Variables," you learned about VBScript syntax errors. Another category of errors that can occur within VBScripts is run-time errors. Run-time errors occur when a VBScript statement attempts to perform an invalid action, such as trying to access a crashed hard disk drive. Run-time errors can be difficult to track down because, unlike syntax errors, they are not automatically detected during script interpretation. Instead they only occur if the portion of code that contains them executes. Unless every part of a VBScript is tested, it is possible that run-time errors may not be caught. In many cases, you can add programming logic to your VBScripts that anticipates and recovers from run-time errors. However, there will be occasions, such as when a disk drive crashes or the network goes down, that are beyond your ability to control or anticipate. In these circumstances, the best you can usually do is to present the user with a custom error message that clearly explains why the script has ended without accomplishing its task.

Deciding Not to Take Action

Many VBScripts consist of only a handful of statements and are written within minutes in order to quickly automate the execution of a particular common task. Under these circumstances, it is often best to omit any error handling logic and to allow errors to simply occur, since the time required to anticipate them and write code that attempts to deal with them would be prohibitive. This is usually acceptable when programmers develop small utility scripts that only they will use. In the event that the scripts will be shared with other users, instructions can be provided that ask the user to report any problems that they may experience with the scripts.

Telling VBScript to Ignore Errors

Another option for dealing with run-time errors is to tell VBScript to ignore them and to continue processing. This can be an effective technique in many cases. The following example prompts the user to type in three numbers, which are then added together.

intNoOne = CInt(InputBox("Enter the first number")) intNoTwo = CInt(InputBox("Enter the second number")) intNoThree = CInt(InputBox("Enter the final number")) intTotal = intNoOne + intNoTwo intTotal = intTotal + intNoThree MsgBox intTotal

Everything works correctly if the user types in three numbers as requested. But often users do not behave as expected. If, for example, the user types the number 3 followed by the number 3 and then the word three, a run-time error would occur. However, if you modify the script by adding the following statement as its first line, VBScript will ignore the error and display a value of 6 (that is, the value of intTotal prior to the statement where the error occurred).

On Error Resume Next

While sometimes effective, this approach should be used with caution. There are few situations in which ignoring an error in one part of a script does not result in another error later in the script's execution. In addition, there will be some errors that the statement will be unable to ignore and prevent from terminating script execution.

When added to the beginning of a script, the On Error Resume Next statement is in effect for the entire script. If you wish, you can later disable the effects of this statement; you may do so by adding the following statement to your VBScript:

On Error GoTo 0

Developing Error Handling Routines

Another option for dealing with run-time errors is to try to develop error-handling routines that deal with them. In order to be able to effectively implement error handlers, you need to be able to anticipate the locations within your scripts where errors are likely to occur and to be able to devise the appropriate logic to deal with the situation. Examples of possible error recovery actions include:

• Requesting that the user report the error
• Giving the user instructions on what to do next
• Providing more descriptive error messages
• Attempting to automatically perform a corrective action
• Giving the user another try if data entry is involved
• Apologizing to the user for the error

In order to create error handling routines, you need to know how to work with the VBScript Err object. This VBScript object provides access to error messages as well as to the methods that can be used to deal with them. The Err object has three properties that provide the following information about an error event:

• Number. The error number of the last error event
• Description. The description of the last error event
• Source. The source object that caused the error

Each of these properties can be modified, allowing you to reword them and make them more understandable before allowing them to be displayed to the user. The following example demonstrates how to create a custom error-handling routine.

On Error Resume Next BogusProcedure() If Err > 0 then Err.Number = 9000 Err.Description = "This script has attempted to execute a " _ "procedure that has not been defined by the programmer." MsgBox "Error: " & Err.Number & " - " & Err.description End if

The first step in setting up an error handler is to add the On Error Resume Next statement to the beginning of the script or procedure. Then you must add a statement that checks for an error immediately after a statement where you think an error might occur. You can check for a specific error or for any error by determining whether the error number assigned to the error Err.Number is greater than 0. You can check for errors at any point in your VBScript where you think they may occur and take different actions based upon each situation. In the case of the previous example, the error handler provides the user with a more descriptive error message.

Figure 6.11 shows the output displayed by the previous example.

Figure 6.11: VBScript provides the ability to recognize and react to error events

Table 6.10 provides a list of VBScript run-time errors.

Clearing Out Errors

The Err object provides two methods that you will find useful. The first method is the Clear() method. If an error occurs within a script and is handled, allowing the script to continue, and later a new error occurs, the information about the new error will overwrite the information stored by the Err object about the previous error. However, if your script later checks for an error and a new error has not occurred, the information about the old error will be reported again. To prevent this behavior, use the Clear() method to delete the information for a previously handled error. To use the Clear() method, place it at the end of your error-handling routine, as demonstrated below.

If Err > 0 then Err.Number = 9000 Err.Description = "This script has attempted to execute a procedure " _ "that has not been defined by the programmer." MsgBox "Error: " & Err.Number & " - " & Err.description Err.Clear End if

Raising Errors

The Err object's Raise() method provides the ability to simulate errors when testing your error handlers. To use this method, place it in your code just before your error handler, as demonstrated below.

Err.Raise(92)

This statement simulates a "For loop not initialized" error. Without the Raise() method, the only way to test your error-handling routines would be to deliberately introduce an error situation into your code or to simulate environmental problems such as disk drive and network outages.

Summary

This chapter described the ins and outs of working with the VBScript InputBox() function. This included how to format text displayed within pop-up dialog boxes, as well as how to interrogate and validate the data that the InputBox() function collects. You also learned about VBScript implicit variable coercion and how to manually perform explicit variable coercion. The chapter covered how to work with the MsgBox() function, including a review of how to specify buttons, icons, the default button, and modality. In addition, you learned how to determine which button the user selected. This chapter also showed you how to trap and reformat error messages to make them more descriptive and understandable to the user.