Section 9.5. VBScript

9.5. VBScript

While WSH is language independent, in this chapter we use Visual Basic Script (VBScript) for demonstrating its capabilities. This section provides a basic introduction to VBScript programming.

The concepts explained in this section, especially those related to the creation and manipulation of objects, apply to all scripting languages implemented in WSH. Even if you have worked with other languages such as Perl but have limited exposure to the concept of objects, you should read through it.

Scripting languages such as VBScript are interpreted. That is, the commands in a script are translated into a low-level computer language and executed at the same time. This differs from standard applications ( .exe files), which are compiled by the designers long before being executed. Although interpreted scripts are inherently slower than compiled applications, interpretations provide the advantage of not requiring a compiler or any type of specialized authoring environment.

A script is composed of a number of elements. Variables are created to temporarily store values and object information. Commands, known as functions or methods , are executed to perform various predefined operations. Complex routines are built up with the aid of programming statements (such as conditional statements that are used to determine if a certain operation is to be executed based on a condition), and loops (which allow operations to be repeated a set number of times).

9.5.1. Comments

It is important to add comments to your scripts, especially larger ones. Comments document the operation of the script, but are ignored when the script is executed. To add a comment in VBScript, add a single quote (') on a new line followed by text, which is the comment. You can add comments at the end of other statements by adding the single quote followed by the comment. For example:

 'this is a comment on its own line strName="Fred"   'this comment is at the end of a statement 

9.5.2. Continuation Character

If a statement is longer than one line, it can be continued onto another line by using an underscore as the last character on the line. For example:

 Wscript.echo "This is an unnecessarily very long message" & _              " to the reader." 

9.5.3. Variables

And you thought you were done with variables when you finished algebra. A variable is used to store information for use during the processing of the script. This might be text information such as a name , number, date, or a reference to an object.

A variable is identified with a name. A variable name can be any combination of letters or numbers , but cannot contain spaces. An example of a name could be startdate or employeewage .

Variable names do not have to be descriptive, but it's good practice to create human-readable names. If you open up a script you wrote six months ago, you'll want to be able to understand what's going on. Variable names are case insensitive; that is, shoesize , ShoeSize , and SHOESIZE are all identical.

The usual practice is to prefix variable names with a few characters to identify the type. This is not required, but it does make it easier to remember what type of data a given variable holds. There is no standard naming convention for variables, but it's best to be consistent.

Table 9-2 lists the prefixes that are used throughout this chapter to identify data types.

Table 9-2. Common variable name prefix types and examples

Prefix	Type	Example
str	String or text. This can be any combination of letters or numbers, including any character that can be entered from your keyboard.	strName
dat	Date.	datStartDate
b	Boolean. A boolean variable is a switch or flag variable; its value is either True (-1) [1] or False (0).	bFlag
num	Number	numSalary
obj	Object.	objMailMessage
int	Integer. Whole number, no decimals.	intCounter
any	Any type. Can be any of the above mentioned data types.

^[1] True is defined as -1, but any positive number will also be interpreted at True.

You do not have to explicitly declare variables in VBS. This means that when you create a script, you do not have to tell the script about the existence of a variable, or declare what type of data a variable will hold, before using it. This is contrary to other programming languages, such as C++. However, it is always wise to declare variables before using them for clarity and debugging purposes. To declare a variable, use the Dim directive followed by the variable name:

 dim   variablename   

To force the explicit declaration of variables, add the statement Option Explicit at the beginning of your script. This will cause VBScript to generate an error if it encounters a variable that hasn't been declared with dim . Why would you want to do this and create more work for yourself? Because of typos. If you misspell a variable name and you're not using Option Explicit , VBScript won't catch it; instead the script simply won't work as expected, and you'll have to carefully comb through the script file looking for errors.

To assign a value to a variable in VBScript, enter the variable name followed by an equals sign and the value you wish to assign:

   variablename   =   value   

Different types of data are assigned in different ways.

Text values, which are referred to as strings in programming jargon, need to be surrounded by quotes:

 strEmpoyeename = "Fred Smith" 

Numeric values don't need to be surrounded by anything, but should not include formatting characters such as commas:

 intEmployeeage = 45 numEmployeesalary = 35000.50 

Dates must be surrounded by hash symbols ( # ):

 datBirth = #1/5/69#  'date format interpreted depending on system                       'settings datBirth = #January 5, 1999#  datBirth = #5-Jan-1999# 

When assigning values to variables, you can perform calculations that involve other values or variables:

 intAge = intAge + 1 'increase the intAge variable by one numTotal = intQuantity * numPrice 'multiply quantity by price 

You can concatenate (combine) strings using the ampersand operator:

 strFirstName = "Fred" strLastName = "Smith" strFullName = strFirstName & " " & strLastName 

Since all variables in VBScript are the same type (they're all "variants" for VB programmers), the ampersand operator can also combine different types of data in one string:

 'combine a string and a number strNameAndAge = strFullName & " is " & intAge & " years old" 

Note (in both of the previous examples) how spaces are used to ensure that text doesn't run together.

9.5.4. Object Variables

Objects are also stored in variables. Objects are assigned values just like other variable types, but you must use the Set statement when assigning an object a value:

 Set objectA = objectB 

As mentioned earlier, an object is similar to a black box. This black box exposes functions and information to the environment in which it is created. When you create an object, it is referred to as an instance of the object. You can have multiple instances of any given object. Each object instance is independent of other instances of the same object.

For example, we have a mail message object. This object stores information and performs email-related operations. It would store information such as the message body, subject, and recipients. It would also contain the code to instruct your email program to send the message.

Each instance of an object stores its own set of variables. These variables are known as object properties.

To access a property, use the object instance's name followed by a period, then the name of the property:

 objMailmessage.subject= "Message subject"  'set the message subject objMailmessage.text = "This is a message to fred"  'set message body 

An object property might only allow you to read a value (read-only), write (write-only), or both. For example, the size of a mail message is a read-only value.

 intSize = objMailmessage.size  'show the size of the message 

Object actions are performed using methods. A method performs a specific operation. When you execute or call a method, it is referred to as invoking the method. To invoke a method, enter the object name followed by a period and the method name (no equal sign).

 objMailMessage.Send( ) ' invoke the send method 

Before you can do any object-related operations, you must first create an instance of an object. Any scripting language implemented in the WSH environment automatically creates an instance of one object, the Wscript object. The Wscript object exposes a couple of basic methods, one of which is CreateObject .

Here is the syntax of the CreateObject method:

 Set objInstance = Wscript.CreateObject(strObjectname) 

For example, create a network object instance:

 Set objMail = Wscript.CreateObject("Wscript.Network") 

Another method available through the Wscript object is the Echo method:

 Wscript.Echo anyValue 

The Echo method displays information specified in the anyValue parameter:

 Wscript.Echo "Hello World" 

The Wscript object model, its methods, and its properties will be covered in more detail later in the chapter.

9.5.5. Conditional Statements

When creating scripts, it is often necessary to check for a certain condition. If it is met, perform specific operations; if not, do something else or nothing at all.

A condition is the comparison of one or more expressions. The comparisons are made using standard mathematical operators: = , > , < , >= , >= , and <> . A condition evaluates to True if the condition is met; otherwise , it's False.

 4>5  false 5>4  true "Fred" = "Joe"  false 10<=10  true 

You might need to test more than one condition at a time. For example, in a personnel application, you might want to perform an operation only if the age is greater than 50 and the employee earned $40,000 or more dollars a year. To check multiple conditions, use the Boolean AND and/or OR operators (see Table 9-3 and Table 9-4). These operators combine two conditions, and the outcome of the operation returns either True or False.

Table 9-3. AND operator condition examples and results

Age	Salary	A > 50	Salary >= 40000	A > 50 AND Salary >= 40000
45	35000	False	False	False
52	39000	True	False	False
30	42000	False	True	False
56	43000	True	True	True

Table 9-4. OR operator condition examples and results

Age	Salary	A > 50	Salary >= 40000	A > 50 OR Salary >= 40000
45	35000	False	False	False
52	39000	True	False	True
30	42000	False	True	True
56	43000	True	True	True

The following set of conditions will return True if the age is greater than 40, the salary is greater than or equal to 50000, or the title is Manager.

 Age>40 Or Salary>50000 Or Title ="Manager" 

The following set of conditions will return True only if the age is greater than 40, the salary is greater than or equal to 50000, and the title is Manager.

 Age>40 And Salary>50000 And Title="Manager" 

You can also combine any number of AND and/or OR conditions. When doing so, you have to be careful of the order in which you write the conditions. As in algebra, there is a precedence as to what operator is performed first. In the mathematical expression 1+2*3, the multiplication is performed before the addition and the result is 7. With Boolean operators, AND has precedence over the OR operator.

The following condition will return True if the salary is greater than 50000 and the title is Manager, or the age is greater than 40.

 Age>40 Or Salary>50000 And Title ="Manager" 

This is not quite what you'd expect. What if you wanted the condition to return True if the age is greater than 40 or the salary is greater than 50000, and the title had to be Manager? Going back to our math example, 1+2*3, what if we wanted the 1+2 to be executed before the 2*3? We would surround the 1+2 in parentheses: (1+2)*3=9. The same applies to conditional expressions. Any expressions surrounded in parentheses are executed first.

 (Age>40 Or  Salary>50000) And  Title ="Manager" 

To test a condition in a script, use the If Then Else statement.

 If condition Then  'do something if true End If 

If a condition is met, the code after the Then statement is executed. The following example displays a message if the value of the intAge variable is greater than 10:

 intAge= 5 If intAge > 10 Then     Wscript.Echo "The person is older than 10 years old" End If 

If you wish to perform an operation if the statement is not true, include the Else statement after the Then statement and before the End If statements.

 intAge= 5 numSalary = 65000 strTitle = "Manager" If (Age>40 Or numSalary>50000) And strTitle ="Manager" > 10 Then     Wscript.Echo "A Manager either over 40 or earns over 50000" Else     Wscript.Echo "Either not a manager" & _                  " or less than 40 with lower salary" End If 

9.5.6. Functions and Subroutines

When creating scripts and with programming in general, it is important to break up larger programs into smaller parts and create reusable functions wherever possible. Large scripts can be unwieldy and difficult to read and debug.

To break up scripts into smaller parts, you can create subroutines and functions.

Subroutines allow smaller script elements to be created. To create a subroutine, enter the Sub statement, followed by a list of parameters (if required). Then add all of the statements to be executed within the subroutine, followed by an End Sub :

 Sub   subname   ([   parameter1   ,   parameterX   ])   statements   ... End Sub 

All of the code that belongs to the subroutine is contained between the Sub and End Sub routine statements.

 Sub HelloWorld( )     Wscript.Echo "Hello World" End Sub 

To execute a subroutine from somewhere else within the script, just type its name like you would a built-in command. For example, to execute the HelloWorld routine above, add HelloWorld on its own line anywhere in your script.

Subroutines can also have parameters passed to them. Include all parameters within the parentheses on the subroutine declaration. Separate the parameters with commas:

 Sub showhello(strMessage, strMessage2)     Wscript.Echo strMessage & " " & strMessage2 End Sub showhello "Hello", "World" 

A function is basically the same as a subroutine, except that it is capable of returning a value. The value returned is based on a calculation of parameters passed to the function:

 Function Squared(numValue)     Squared = numValue * numValue End Function  Wscript.Echo Squared(5) 

It's up to you to choose whether you want to make something a subroutine or function; some programmers create functions exclusively and just ignore the returned values of the functions that don't have them.

While you can create your own functions, VBScript has hundreds of built-in functions that perform certain operations, such as mathematical, string, and logic operations:

 datToday= Date( ) 'return todays date strName = Ucase(strName) ' convert string to upper case 

For more information on VBScript's built-in functions, see Section 9.2, earlier in this chapter.

9.5.7. Variable Scope

When you start declaring variables in different routines, you will encounter scope issues. These scope issues can cause problems if you are not careful how and where you declare your variables.

Both subroutines and functions can have variable declarations inside the routines; these variables have no meaning outside of the routines, and are considered "local." This is useful for larger scripts where it is not practical to declare all variables in one spot, as well as for debugging purposes.

If you create a variable in a subroutine, you cannot access the variable outside of the subroutine. However, if you create several "local" variables with the same name, but in different routines, they will be treated like separate variables and won't cause a conflict. Variables that are declared in the main portion of the script (outside of subroutine and function blocks) are considered "global" and have meaning in all parts of the script.

 Option Explicit 'force explicit declaration of variables Dim strGlobal, strSameName strGlobal = "I can see everywhere" strSameName = "Global local" Wscript.Echo strLocal 'this won't work - error will occur Sub one     Dim strLocal, strSameName     strSameName = "Inside one "     Wscript.Echo strGlobal 'this works End Sub 

9.5.8. Loops

Often a script needs to repeat an operation a set number of times. The For...Next statement provides this ability. Its syntax is as follows :

 For   intVariable   =   start   To   end   [Exit For] Next 

The code between the For and Next statements is executed the number of times specified between the start and end values:

 For intCounter = 1 To 10      intValue = intValue * 2   'multiply the variable intValue by two Next 

The Do While Loop provides the ability to repeat operations a set number of times based on a condition.

 Do While   condition   [Exit Do] Loop 

The code between the Do While and Loop statements is repeatedly executed while the condition is true.

 Do While intCounter < 100     Wscript.Echo intCounter     intCounter = intCounter + 1 Loop 

The Exit For and Exit Do statements are used to leap out of the loops before the loops conclude, and while they can appear anywhere, they're typically used in conjunction with the if statement.

9.5.9. Collections

An object exposes methods and properties to the programming environment. The properties can be of any data type, including an object. This can include a special type of an object known as a collection . A collection is an object that contains a list of related objects.

Table 9-5 lists a number of default properties that a collection object always exposes.

Table 9-5. Object collection properties

Property	Description
Count	Returns the number of items contained in the collection.
Length	Same as the Count property. Not all collections use this property.
Item	Returns a specified item from the collection.

We will use a fictitious Persons collection to demonstrate how to reference values from a collection. The Persons collection contains Person objects. The Persons object contains Name , Social Security , and PhoneNumber properties.

objPersons is an instance of a Persons collection object:

 'list the number of Person objects in the Collection Wscript.Echo objPersons.Count 

To get an object stored in a collection, reference the Items property. The Items property returns the n th item in the collection:

 objPerson =objPersons.Item(0)   'returns the first item 

Many collections will return an item based on a key value used to identify objects within the collection:

 anyValue = objCollection.Item(strKey) 

For example, in the case of the Persons collection, we can reference Person objects based on the social security number, since it would uniquely identify the object within the collection. This method of referencing depends on how the object was implemented; not all collections will support this.

 objPerson = objPersons("123-456-789") For intCounter = 0 To objPersons.Count - 1     Wscript.Echo objPersons(intCounter).Name Next 

VBScript's special version of the For statement, For Each , can be used to iterate through a collection:

 For Each objObject In objObjects Next 'list the name for all of the Person objects in the collection. For Each objPerson In objPersons     Wscript.Echo objPerson.Name Next 

Note that most collections start with a zero offset, so the first item is referenced as zero (0), the second is referenced as one (1), and so on.

9.5.10. Error Handling

When you are executing a script, there is always the potential of running into errors. Errors may be due to bugs in your script as well as bugs in external objects or programs you reference.

When an error occurs in WSH, the script will terminate execution and display the error message. This may not be desirable, especially in scripts where you want to continue executing even if certain errors occur.

In order to implement error handling, we need to be able to have a script continue processing. This is done using the On Error Resume Next statement. Any errors encountered after this statement in a script are ignored.

Errors can then be "trapped" by checking the Err object. The Err object returns a nonzero value if an error occurs. The Err object also exposes a Description property, which contains a description of the last error:

 On Error Resume Next intValue = 5 numDiv = intValue/0 'this will generate an error If Err Then     Wscript.Echo "Error# " & Err & " occurred. " _         & "Description " & Err.Description End If 

9.5.11. Constants

When creating a script, you may want to store some values using symbolic names. These are called constants .

Constants are similar to variables, but you cannot modify a constant during the execution of the script. You can represent string and numeric values using constants.

It's often wise to define constant values at the start of your program, rather than repeatedly entering the same value when you're writing your script. This way, if you later need to change the value, you only need to change it in one place, rather than searching through the program for multiple instances of the value.

To create a constant, enter the Const statement followed by the constant name and an assigned value:

 Const Pi = 3.14 Const MyFolder = "d:\Shared Documents\Milhouse" Const CompanyName = "Acme Inc" Const StartDate = #1/1/99# 

Constants are referred to in the same way as other variables:

 Wscript.Echo "Company is " & CompanyName