Displaying Messages

VBScript displays messages using the Windows standard message box, which is a short dialog box that has a few display options to customize its behavior and appearance. VBScript exposes this functionality through the MsgBox statement and the MsgBox() function.

The MsgBox Statement and Function

MsgBox is one of the few VBScript elements that can act as both a statement and a function. As a statement, MsgBox just displays a message box to your specifications. As a function, however, MsgBox can act as a form of user input, allowing simple Yes/No choices that can affect the behavior of your scripts.

The basic MsgBox statement accepts up to three parameters: a message, a numeric value designating which system icons or buttons should be displayed, and a message box title. It looks something like this:

MsgBox "The script has finished running.", _

 1, "Notice"

This command will display a message box that contains the text "The script has finished running." The box will include an OK button and a Cancel button, and the title of the box will contain "Notice." If you don't care about the title of the dialog or the buttons it displays, you can take a shortcut and just include your message.

MsgBox "The script has finished running." & _

 " Please check the server for the new user accounts."

The default message box title will be displayed, and the default button configuration-an OK button and a Cancel button with no icon-will be displayed.

Your scripts will look cooler, though, if you customize them a bit. For example, you might display an information icon on the message box, which helps cue the user that the message isn't an error or a question, but a simple informative message. You might also display just an OK button; a Cancel button doesn't really make sense because when the script is done, there's nothing left to cancel.

MsgBox "The script has finished running.", _

 64, "Thank you."

That middle parameter-the number 64, in this case-controls the icons and buttons that display on the dialog box. Table 6.1 shows the options you have available, along with their corresponding values.You can pick from four classes of options.

Table 6.1. MsgBox display options

Display	Value	Constant
OK button	0	VbOKOnly
OK and Cancel buttons	1	VbOKCancel
Abort, Retry, Ignore buttons	2	vbAbortRetryIgnore
Yes, No, and Cancel buttons	3	vbYesNoCancel
Yes and No buttons	4	VbYesNo
Retry and Cancel buttons	5	vbRetryCancel
Critical error icon	16	vbCritical
Question mark icon	32	vbQuestion
Exclamation mark icon	48	vbExclamation
Information ("i") icon	64	vbInformation
Make the first button the default	0	vbDefaultButton1
Make the second button the default	256	vbDefaultButton2
Make the third button the default	512	vbDefaultButton3
Make the fourth button the default	768	vbDefaultButton4
Application modal	0	vbApplicationModal
System modal	4096	vbSystemModal

To come up with the appropriate value for the second MsgBox parameter, you just need to add up the values for each class of option that you want to display. For example, to display a message box that has a Yes and No button, a question mark icon, and has the No button as the default, you would add values 4, 32, and 256, for a total of 292: MsgBox "Are you sure?", 292, "Delete file" would be the VBScript command. Note that the message box will be application modal, because option value 4096 wasn't added in.

You're unlikely to remember all of these numeric values. I certainly never can. Fortunately, VBScript defines several constants to represent each value. Just use the constant in place of the value. For example, to display that same "Are you sure?" dialog box using constants:

MsgBox "Are you sure?", _

 vbYesNo + vbQuestion + vbDefaultButton2 + vbApplicationModal, _

 "Delete file"

That's much easier to remember with a little practice.

There's still a problem with this MsgBox statement, though. Remember from Chapter 5 that statements cannot return a value-only functions can do that. So how does this script know if the user clicked the Yes or No button? As written, it wouldn't. Instead, write the MsgBox as a function and assign the return value to a variable.

Dim vResult

vResult = MsgBox("Are you sure?", _

vbYesNo + vbQuestion + vbDefaultButton2 + vbApplicationModal, _

 "Delete file")



If vResult = 7 Then

 'put code here to handle

 'the user saying NO

End If

Notice that this example places the MsgBox parameters inside parentheses, like any other function. The result is stored in variable vResult. An If…Then construct examines the contents of vResult and ends the script if the variable contains a 7. The value 7 happens to be what MsgBox() returns if the user clicks the No button.

Fortunately, you don't have to remember that 7, either. VBScript also defines constants for the return values, as shown in Table 6.2.

Table 6.2. MsgBox return values

User Clicked	Value	Constant
OK	1	vbOK
Cancel	2	vbCancel
Abort	3	vbAbort
Retry	4	vbRetry
Ignore	5	vbIgnore
Yes	6	vbYes
No	7	vbNo

To rewrite the example using the constants:

Dim vResult

vResult = MsgBox("Are you sure?", _

vbYesNo + vbQuestion + vbDefaultButton2 + vbApplicationModal, _

 "Delete file")



If vResult = vbNo Then

 'put code here to handle

 'the user saying NO

End If

You can take one more shortcut. You don't have to first assign the MsgBox() return value to a variable; you can use MsgBox() as part of the If…Then construct's logical evaluation.

If MsgBox("Are you sure?", _

vbYesNo + vbQuestion + vbDefaultButton2 + vbApplicationModal, _

 "Delete file") = vbNo Then

End If

This is a much more compact piece of script, keeps your script nice and easy to read, and performs the same as the previous, longer example.

More Complex Messages

MsgBox doesn't limit you to a line or two of text. Try running the following script snippet.

MsgBox "This is a warning message. " & _

 vbCrLf & vbCrLf & _

 "You have chosen to delete this user or group " & _

 "the domain:" & vbCrLf & vbCrLf & _

 vbTab & "JohnDoe" & vbCrLf & vbCrLf & _

 "Are you sure this is what you want to do?", _

 vbYesNo + vbExclamation + vbDefaultButton2, _

 "Delete user"

You should see something like the dialog box in Figure 6.1

I've used two powerful VBScript constants in this example: vbCrLf and vbTab. vbCrLf inserts a carriage return and linefeed character, forcing MsgBox to begin a new line of text. Putting two vbCrLfs in a row puts a blank line in between, helping to emphasize the message. vbTab inserts a tab character, indenting the first line of a paragraph. I used it in this example to make the user account name stand out a bit from the rest of the message. Using these constants, you can create simply formatted messages that have more impact and convey more information than a simple line or two of text can.

MsgBox Best Practices

You should get into the habit of following Windows user interface conventions when using MsgBox. To begin, select the appropriate icons for your message boxes.

• Always use an icon. They help visually cue users as to the importance and nature of your message.

• Use the information icon to display non-error, non-warning messages that don't require a choice, such as a message that the script has finished running.

• Use the question mark icon whenever you're asking for a decision that doesn't have potentially devastating consequences. For example, you might use this icon when you're asking if the user wants to create a new user home directory in addition to the user's domain account.

• Use the exclamation mark icon to warn the user of a condition that has occurred when the condition won't stop the script from running. For example, if a script tries to connect to a server to create a home directory but is unsuccessful, an exclamation mark is appropriate if the script continues to create the user's domain account and perform other tasks. Also, use the exclamation mark when asking the user to make a potentially dangerous choice, such as confirming a user account deletion.

• Use the critical icon when the script will stop running due to some condition it encountered.

You should also select buttons that are appropriate to the task. For example, don't ask a Yes/No question and then display Abort, Retry, and Ignore buttons. The buttons don't provide answers that correspond to the question you asked.

Finally, always set the default button to be the least dangerous choice. If you're asking whether or not to delete a user account, make the No button the default. That way, if the user accidentally hits Enter without thoroughly reading your warning, nothing bad will occur.

Go Generic with WScript.Echo

In Chapter 2, I introduced you to WScript and Cscript, the Windows and command-line scripting hosts. MsgBox will work from within either one, although it will always pop up with a graphical message box, even when running under Cscript.

If you're writing scripts intended entirely for the command line and Cscript, you can use another technique to produce output: WScript.Echo. Despite its name, this command can be used within either graphical WScript or command-line Cscript scripts. When used in a WScript script, WScript.Echo displays a graphical message box. When used under Cscript, it outputs text to the command line.

WScript.Echo is easy enough to use.

WScript.Echo "Hello, world! " & _

"It's nice to see you."

Under WScript, you'll see a message box like the one in Figure 6.2. Notice that you cannot control the icons, buttons, or title of this message box as you can with the MsgBox statement or function; WScript.Echo is much more simplistic.

Execute the exact same script in Cscript and you'll see something like Figure 6.3. WScript.Echo doesn't provide any means for collecting input, as the MsgBox() function does; its entire purpose is to display messages. Because it functions in both a graphical and command-line environment, it's ideal for scripts that need to run in either environment. It's also the only easy way to create command-line output for Cscript scripts.