Previous Section Table of Contents Next Section

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."

TIP

When you include a system icon, Windows will play any associated event sounds when your dialog box is displayed. This feature makes your script seem much more professional and integrated with the operating system.


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.

  1. Buttons. Comprised of values 0 through 5, these control which buttons are displayed on the dialog box. You can only pick one from this set.

  2. Icons. Values 16 through 64 control the icon that displays, and you can pick only one. An icon value of 0 displays no icon. You can choose only one of these options.

  3. Defaults. Consisting of values 0, 256, 512, and 768, these options control which of the displayed buttons will be selected if the user presses Enter, rather than clicking on a button. Choose only one of these options.

  4. Modality. Values 0 or 4096 control how your message box affects the rest of Windows. The default, Application modal, means your script stops executing until the user clicks a button on the message box. Making the box system modal will display the box on top of all other applications, requiring the user to answer the dialog before doing anything else on Windows (note that not all versions of Windows support this functionality).

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

NOTE

If your dialog box displays a Cancel button, you can press the Esc (Escape) key on your keyboard. Doing so is the same as clicking the Cancel button and VBScript will return vbCancel.


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"

TIP

I'm using a lot of underscore characters in this example to make a very long statement spread across several lines of text. That's a requirement when printing scripts in a book like this, but you should consider using this technique even in a script editor like Notepad or PrimalScript. You'll find that you don't have to do as much horizontal scrolling, making your scripts easier to edit.


You should see something like the dialog box in Figure 6.1

Figure 6.1. Complex message box

graphics/06fig01.gif

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.

NOTE

Echo is actually a method of the built-in WScript object. For more information on objects and methods, read Chapter 5. I'll cover more of the built-in scripting objects in Chapter 11.


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.

Figure 6.2. WScript.Echo executed within WScript.exe

graphics/06fig02.gif

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.

Figure 6.3. WScript.Echo executed within Cscript.exe

graphics/06fig03.gif

    Previous Section Table of Contents Next Section