EarthWeb sites:

Appendix B

VBScript Language Reference

by David Blankenbeckler

• Summary of Reserved Words
• Literals
• Operators
  • Assignment
  • Comparison
  • Arithmetic
  • String
  • Logical
  • Bitwise Logical
• Statements
  • Conditionals
  • Loops
• Procedures
• Built-in Functions
  • Math
  • Dates and Time
  • String Manipulation
  • User Interface
  • Data Type

This appendix is a summary and quick reference for the VBScript language.

Language keywords and symbols are shown in a monospaced font. Arguments and other parts to be substituted are in italic monospace.

Optional parts are indicated by brackets. If there are several options that are mutually exclusive, they are shown separated by pipes (|) like this:

[ public | private | protected ] type varname

Summary of Reserved Words

The following words are defined as part of the VBScript language and cannot be used as variable names:

Literals

Literals in VBScript are represented as follows:

Operators

The VBScript operator is grouped into the following categories: assignment, comparison, arithmetic, string, logical, and bitwise.

Assignment

The following assignment operator is supported in VBScript:

Comparison

The following comparison operators are supported in VBScript:

Arithmetic

The following arithmetic operators are supported in VBScript:

String

The following string operator is supported in VBScript:

Logical

The following logical operators are supported in VBScript:

Bitwise Logical

The following bitwise logical operators are supported in VBScript:

Statements

VBScript statements are divided into two categories: conditional and looping.

Conditionals

Conditional statements provide the ability to perform steps based on the outcome of a comparison. VBScript provides this support through the If...Else and Select Case statements.

If...Else

The syntax for the If...Else statement is as follows:

If condition Then

'   statements for true condition

[Else]

'   statements for false condition

End If

Select Case

The syntax for the Select Case statement is as follows:

Select Case expr

   Case n

      ' statements for this case

   Case m

      ' statements for this case

   '... additional case statements as necessary

   [Case Else]

      ' statements for the default case

End Select

Loops

Loop statements provide a means for looping through a section of code until an expression evaluates to true (or false).

For...Next

The syntax for the For...Next statement is as follows:

For var = init To final [Step step]

' statements to execute while looping

Next

While...Wend

The syntax for the While...Wend statement is as follows:

While condition

' statements to execute while looping

Wend

Do While

The syntax for the Do While statement is as follows:

Do While condition

' statements to execute while looping

[Exit Do]

' statements to execute while looping

Loop

Do Until

The syntax for the Do Until statement is as follows:

Do Until condition

' statements to execute while looping

[Exit Do]

' statements to execute while looping

Loop

Alternate Form of Do loop

The Do Until and Do While loops can also be used with the following syntax:

Do

' statements to execute while looping

Loop [Until|While]

Procedures

VBScript provides two different types of procedures, Sub and Function. When there is no return value, Sub should be used. When there is a return value, Function should be used.

Subroutine

The syntax for a Sub procedure is as follows:

Sub SubName([param1][,param2]...[,paramN])

   ' sub procedure statements

End Sub

Function

The syntax for a Function procedure is as follows:

Function fnName([param1][,param2]...[,paramN])

   ' function statements;

   fnName = expr

End Function

Built-in Functions

VBScript contains a number of built-in functions. Each of the VBScript functions is summarized in the following sections.

Math

VBScript provides many different built-in functions for performing mathematical operations.

In the following function declarations, numExpr can be either a number or an expression that evaluates to a number.

Abs(numExpr)

Returns the absolute value of numExpr.

Atn(numExpr)

Returns the arc tangent of numExpr.

Cos(numExpr)

Returns the cosine of numExpr.

Exp(numExpr)

Returns e numExpr where e is Euler's constant.

Fix(numExpr)

Returns the integer portion of numExpr. If the number is negative, the next greater integer is returned.

Int(numExpr)

Returns the integer portion of numExpr. If the number is negative, the next lower integer is returned.

Log(numExpr)

Returns the natural log of numExpr.

Rnd([numExpr])

Returns a pseudo-random number. The number is not really random because the same seed will always produce the same result. If numExpr is used, the result is as follows:

If numExpr = 0, Rnd returns the last random number generated.

If numExpr > 0, Rnd returns the next random number in the sequence.

If numExpr < 0, Rnd returns a random number based on the seed, numExpr. The same seed always returns the same number.

The Randomize statement will generate a seed for the Rnd function based on the system clock. This will provide a much better illusion of randomness. Here's an example:

Randomize

x = Rnd()

Sgn(numExpr)

Returns 1 if numExpr is greater than 0, -1 if numExpr is less than 0, and 0 if numExpr is equal to 0.

Sin(numExpr)

Returns the sine of numExpr.

Sqr(numExpr)

Returns the square root of numExpr.

Tan(numExpr)

Returns the tangent of numExpr.

Dates and Time

VBScript contains a number of built-in functions to work with dates and time.

Date

Returns the current date from the system clock.

DateSerial(year, month, day)

Returns a value of subtype Date to represent the year, month, and day that were passed.

Day(date)

Returns an integer between 1 and 31 to represent the day for the date that was passed.

Hour(time)

Returns an integer between 0 and 23 to represent the hour for the time that was passed.

Minute(time)

Returns an integer between 0 and 59 to represent the minute for the time that was passed.

Month(date)

Returns an integer between 1 and 12 to represent the month for the date that was passed.

Now

Returns the current date and time based on the system clock.

Second(time)

Returns an integer between 0 and 59 to represent the second for the time that was passed.

Time

Returns the current time from the system clock.

TimeSerial(hour,minute,second)

Returns a value of subtype Date to represent the hour, minute, and second that were passed.

Weekday(date [, firstday])

Returns an integer between 1 and 7 that represents the current day of the week for date. By default, Sunday is represented by 1, Monday 2, and so on. If a firstday parameter is passed, another day can be set to be represented by 1. For example, if 2 is passed as the firstday parameter, Monday would be represented by 1.

Year(date)

Returns an integer that represents the year in date; for example, 1996.

String Manipulation

VBScript contains many built-in functions to assist in dealing with strings.

In the function declarations below, strExpr can be either a string or an expression that evaluates to a string.

Asc(strExpr)

Returns an integer representing the ANSI code for the first character of strExpr.

Chr(ANSICode)

Returns the character represented by ANSICode.

Hex(number)

Returns a string that represents number in hexadecimal.

InStr([startPos,] string, srchstr [, compType])

Returns the position of the first occurrence of srchstr in string. If startPos is specified, the search begins at that position. The compType parameter can be either 0 or 1. The default value of 0 is case sensitive. A compType of 1 indicates that the search should not be case sensitive.

LCase(strExpr)

Converts strExpr to lowercase and returns it as a string.

Left(strExpr, numChars)

Returns a substring of strExpr that begins at the first position (on the left) and is numChars in length.

Len(strExpr | varName)

If a string expression is passed, Len returns the length of that string. If a variable name is passed, Len returns the number of bytes required to store that variable.

LTrim(strExpr)

Removes all leading spaces from strExpr and returns it as a string.

Mid(strExpr, startPos, numChars)

Returns a substring of strExpr that begins at startPos and is numChars in length.

Oct(number)

Returns a string that represents number in octal.

Right(strExpr, numChars)

Returns a substring of strExpr that begins at the last position (on the right) and is numChars in length.

RTrim(strExpr)

Removes all trailing spaces from strExpr and returns it as a string.

StrComp(strExpr1, strExpr2 [,compType])

Compares strExpr1 and strExpr2. If they are equal, 0 is returned. -1 is returned if strExpr1 is less than strExpr2. 1 is returned if strExpr1 is greater than strExpr2. If either string is null, Null is returned.

The compType parameter can be either 0 or 1. The default value of 0 is case sensitive. A compType of 1 indicates that the search should not be case sensitive.

String(length, character)

Returns a string of repeating character that is length in length.

Trim(strExpr)

Removes all leading and trailing spaces from strExpr and returns it as a string.

UCase(strExpr)

Converts strExpr to uppercase and returns it as a string.

User Interface

VBScript provides two built-in functions that provide easy access to the user interface: InputBox and MsgBox.

InputBox(prompt [, title][, default][, xPos][, yPos][, helpFile, context])

This function displays a dialog box with a text field. The contents of the text field are returned. The parameters are defined as follows:

MsgBox(prompt[, buttons][, title][, helpfile, context])

The MsgBox function displays a dialog box with one or more buttons, as configured by the buttons parameter. The parameters are defined as follows:

The return value provides the button that was selected:

Data Type

VBScript provides several built-in functions for dealing with data types.

CBool(expr)

Returns expr converted to subtype Boolean. If expr is 0, False is returned. True is returned if expr is unequal to 0. A type mismatch runtime error occurs if expr does not represent a numeric value.

CByte(expr)

Returns expr converted to subtype Byte. If expr cannot be converted to subtype Byte, a type mismatch runtime error occurs.

CDate(expr)

Returns expr converted to subtype Date. If expr cannot be converted to subtype Date, a type mismatch runtime error occurs.

CDbl(expr)

Returns expr converted to subtype Double. If expr cannot be converted to subtype Double, a type mismatch or overflow runtime error occurs.

CInt(expr)

Returns expr converted to subtype Integer. If expr cannot be converted to subtype Integer, a type mismatch or overflow runtime error occurs.

CLng(expr)

Returns expr converted to subtype Long. If expr cannot be converted to subtype Long, a type mismatch or overflow runtime error occurs.

CSng(expr)

Returns expr converted to subtype Single. If expr cannot be converted to subtype Single, a type mismatch or overflow runtime error occurs.

CStr(expr)

Returns expr converted to subtype String.

If expr is boolean, either True or False is returned.

If expr is a Date, a string will be returned in the short date format for the particular system.

If expr is of the subtype Error, a string containing the word Error and the error number is returned.

If expr is Null, a runtime error occurs.

DateValue(string)

Returns a Variant of subtype Date to represent the date in string.

IsArray(expr)

Returns a boolean indicating whether expr is an array.

IsDate(expr)

Returns a boolean indicating whether expr can be converted to a Date.

IsEmpty(expr)

Returns a boolean indicating whether expr is empty. The intent of this function is to pass a variable name as expr to determine if it has been initialized.

IsNull(expr)

Returns a boolean indicating whether expr contains Null.

IsNumeric(expr)

Returns a boolean indicating whether expr can be evaluated to a numeric value.

IsObject(expr)

Returns a boolean indicating whether expr references a valid object.

LBound(arrayName[, dimension])

Returns the lower bound of arrayName for the dimension indicated. Because VBScript does not support lower bounds other than zero, this function is not very useful.

TimeValue(string)

Returns a Variant of subtype Date to represent the time in string.

UBound(arrayName[, dimension])

Returns the upper bound of arrayName for the dimension indicated.

Val(strExpr)

Returns the first numeric value found in strExpr. The numeric value must be at the beginning of strExpr. Spaces, tabs, and linefeeds will be removed and periods converted to decimal points. The prefixes &O and &H in strExpr can be used to specify octal or hexadecimal values.

VarType(varName)

Returns a number that indicates the Variant subtype of varName according to the following: