Syntax

result = Abs(number)

number

Use: Required

Data Type: Any valid numeric expression

A number or a string representation of a number.

Return Value

The absolute value of number. The data type is the same as that passed to the function if number is numeric, and Double if it is not.

Description

Returns the absolute value of a number (i.e., its unsigned magnitude). For example, Abs(-1) and Abs(1) both return 1.

Rules at a Glance

• number can be a number, a string representation of a number, an object whose default property is numeric, or a Null or Empty.
• If number is Null, the function returns Null.
• If number is an uninitialized variable or Empty, the function returns zero.

See Also

IsNumeric Function

Syntax

Array([element1], [elementN],....)

element

Use: Optional

Data Type: Any

The data to be assigned to the first array element.

elementN

Use: Optional

Data Type: Any

Any number of data items you wish to add to the array.

Return Value

A variant array consisting of the arguments passed into the function.

Description

Returns a variant array containing the elements whose values are passed to the function as arguments.

The code fragment:

Dim vaMyArray vaMyArray = Array("Mr", "Mrs", "Miss", "Ms")

is similar to writing:

Dim vaMyArray(3) vaMyArray(0) = "Mr" vaMyArray(1) = "Mrs" vaMyArray(2) = "Miss" vaMyArray(3) = "Ms"

Because Array creates a variant array, you can pass any data type, including objects, to the Array function. You can also pass the values returned by calls to other Array functions to create multidimensional arrays; these kinds of arrays are called "ragged" arrays.

Rules at a Glance

• Although the array you create with the Array function is a variant array data type, the individual elements of the array can be a mixture of different data types.
• The initial size of the array you create is the number of arguments you place in the argument list and pass to the Array function.
• The lower bound of the array created by the Array function is 0.
• The array returned by the Array function is a dynamic rather than a static array. Once created, you can redimension the array using Redim, Redim Preserve, or another call to the Array function.
• If you don't pass any arguments to the Array function, an empty array is created. Although this may appear to be the same as declaring an array in the conventional manner with the statement:

  Dim myArray( )

  the difference is that you can then use the empty array with the Array function again later in your code.

Example

<% Dim myArray myArray = Array(100, 2202, 3.3, 605, 512) Response.Write myArray(2) %>

Programming Tips and Gotchas

• The Array function was not present in the first version of VBScript and was added to the language in Version 2.
• You cannot assign the return value of Array to a variable previously declared as an array variable. Therefore, don't declare the variant variable as an array using the normal syntax:

  Dim MyArray( )

  Instead, simply declare a variant variable, such as:

  Dim MyArray

• The Array function is ideal for saving space and time and for writing more efficient code when creating a fixed array of known elements, for example:

  Dim Titles Title = Array("Mr", "Mrs", "Miss", "Ms")

  You can use the Array function to create multidimensional arrays. However, accessing the elements of the array needs a little more thought. The following code fragment creates a simple two-dimensional array with three elements in the first dimension and four elements in the second:

  Dim vaListOne vaListOne = Array(Array(1, 2, 3, 4), _ Array(5, 6, 7, 8), _ Array(9, 10, 11, 12))

  Surprisingly, the code you'd expect to use to access the array returns a "Subscript out of range" error:

  'This line generates a Subscript out of range error Response.Write vaListOne(1, 2)

  Instead, since this is an array stored within an array (that is, a ragged array), you can access it as follows:

  Response.Write vaListOne(1)(2)

• Because you declare the variant variable to hold the array as a simple variant, rather than an array and can then make repeated calls to Array, the function can create dynamic arrays. For example, the following code fragment dimensions a variant to hold the array, calls Array to create a variant array, then calls Array again to replace the original variant array with a larger variant array:

  Dim varArray varArray = Array(10,20,30,40,50) ... varArray = Array(10,20,30,40,50,60)

  The major disadvantage of using this method is that while it makes it easy to replace an array with a different array, it doesn't allow you to easily expand or contract an existing array.

VBA/VBScript Differences

Unlike Visual Basic, VBScript does not contain an Option Base statement; therefore, arrays created in VBScript using the Array function have a lower boundary of 0. That is, the first element of the array will always be accessed using an index value of 0.

See Also

Dim Statement, LBound Function, ReDim Statement, UCase Function

Syntax

Asc(string) AscB(string) AscW(string)

string

Use: Required

Data Type: String

Any expression that evaluates to a string.

Return Value

An integer that represents the character code of the first character of the string.

Description

Returns the ANSI (in the case of Asc) or Unicode (in the case of AscW ) character code that represents the first character of the string passed to it. All other characters in the string are ignored. The AscB function returns the first byte of a string.

Rules at a Glance

• The string expression passed to the function must contain at least one character, or a runtime error (either "Invalid use of Null" or "Invalid procedure call or argument") is generated.
• Only the first character of the string is evaluated by Asc, AscB, and AscW.
• Use the AscW function to return the Unicode character of the first character of a string.
• Use the AscB function to return the first byte of a string containing byte data.

Example

<% Dim sChars Dim iCharCode sChars = Request.Form("chars") If Len(sChars) > 0 Then CharCode = Asc(sChars) If iCharCode >= 97 And iCharCode <= 122 Then Response.Write "The first character must be uppercase" Else Response.Write iCharCode End If End If %>

Programming Tips and Gotchas

• Always check that the string you are passing to the function contains at least one character using the Len function, as the following example shows:

  If Len(sMyString) > 0 Then iCharCode = Asc(sMyString) Else Response.Write "Cannot process a zero-length string" End If

• Surprisingly, although the VBScript documentation shows that the data type of the parameter passed to the Asc function is String, it can actually be any data type. Evidently the Asc routine converts incoming values to strings before extracting their first character. Try this quick example for yourself:

  <% sChars = 123 Response.Write Asc(sChars) %>

• Use Asc within your data validation routines to determine such conditions as whether the first character is upper- or lowercase and whether it's alphabetic or numeric, as the following example demonstrates:

  Function CheckText (sText) Dim iChar If Len(sText) > 0 Then iChar = Asc(sText) If iChar >= 65 And iChar <= 90 Then CheckText = "The first character is UPPERCASE" ElseIf iChar >= 97 And iChar <= 122 Then CheckText = "The first character is lowercase" Else CheckText = "The first character isn't alphabetical" End If Else CheckText = "Please enter something in the text box" End If End Function

See Also

Chr, ChrB, ChrW Functions

Syntax

Atn(number)

number

Use: Required

Data Type: Numeric

Any numeric expression, representing the ratio of two sides of a right angle triangle.

Return Value

The return value is a Double representing the arctangent of number in the range -pi/2 to pi/2 radians.

Description

Takes the ratio of two sides of a right triangle (number) and returns the corresponding angle in radians. The ratio is the length of the side opposite the angle divided by the length of the side adjacent to the angle.

Rules at a Glance

• If no number is specified, a runtime error is generated.
• The return value of Atn is in radians, not degrees.

Example

<% Const Pi = 3.14159 Dim dblSideAdj, dblSideOpp Dim dblRatio, dblAtangent, dblDegrees dblSideAdj = 50.25 dblSideOpp = 75.5 dblRatio = dblSideOpp / dblSideAdj dblAtangent = Atn(dblRatio) ' convert from radians to degrees dblDegrees = dblAtangent * (180 / Pi) Response.Write dblDegrees & " Degrees" %>

Programming Tips and Gotchas

• To convert degrees to radians, multiply degrees by pi/180.
• To convert radians to degrees, multiply radians by 180/pi.
• Don't confuse Atn with the cotangent. Atn is the inverse trigonometric function of Tan, as opposed to the simple inverse of Tan.

See Also

Tan Function

Syntax

[Call] procedurename [argumentlist]

Call

Use: Optional

Use: Required

Data Type: n/a

The name of the subroutine being called.

argumentlist

Use: Optional

Data Type: Any

A comma-delimited list of arguments to pass to the subroutine being called.

Description

Passes program control to an explicitly named procedure or function.

Rules at a Glance

• The Call statement requires that the procedure being called be named explicitly. You cannot assign the subroutine name to a variable and provide that as an argument to the Call statement. For example, the following is an illegal use of Call:

  Dim sProc sProc = "PrintRoutine" Call sProc(sReport) ' Illegal: sProc is a variable

  The following code fragment shows a valid use of the Call statement:

  Call PrintRoutine(sReport) ' Legal usage

• You aren't required to use the Call keyword when calling a function procedure. However, if you use the Call keyword to call a procedure that requires arguments, argumentlist must be enclosed in parentheses. If you omit the Call keyword from the procedure call, you must also omit the parentheses around argumentlist.

Example

The WSH code fragment shows a call to a procedure that passes two arguments: a string array and a string. Note that while the call to the ShowList procedure uses the Call keyword, the equivalent call to the MsgBox function within the ShowList procedure does not:

Dim aList, sCaption aList = Array("One", "Two", "Three", "Four") sCaption = "Array Contents" Call ShowList(aList, sCaption) Sub ShowList(arr( ), s2) Dim mem, sMsg For Each mem In arr sMsg = sMsg & mem & vbCrLf Next MsgBox sMsg, ,s2 End Sub

Programming Tips and Gotchas

• You can use the Call keyword to call a function when you're not interested in the function's return value.
• The use of the Call keyword is considered outdated. We suggest not using the keyword, as it is unnecessary and provides no value.
• If you remove the Call statement but fail to remove the parentheses from a call to a subroutine with a single argument, then that argument is passed by value rather than by reference. This can have unintended consequences.

VBA/VBScript Differences

VBA (as of Version 6.0) supports the CallByName function, which allows you to call a public procedure in a VBA object module by assigning the procedure name to a variable. VBScript does not support the CallByName function and requires that you provide the name of the function or sub procedure in the Call statement.

Syntax

CBool(expression)

expression

Use: Required

Data Type: String or Numeric

Any numeric expression or a string representation of a numeric value.

Return Value

expression converted to a type of Boolean (True or False).

Description

Casts expression as aa Boolean type. Expressions that evaluate to 0 are converted to False (0), and expressions that evaluate to nonzero values are converted to True (-1).

Rules at a Glance

If the expression to be converted is a string, the string must act as a number. Therefore, CBool("ONE") results in a type mismatch error, yet CBool("1") converts to True.

Programming Tips and Gotchas

• You can check the validity of the expression prior to using the CBool function by using the IsNumeric function.
• When you convert an expression to a Boolean, an expression that evaluates to 0 is converted to False (0), and any nonzero number is converted to True (-1). Therefore, a Boolean False can be converted back to its original value (i.e., 0), but the original value of the True expression can't be restored unless it was originally -1.

See Also

IsNumeric Function

Syntax

CByte(expression)

expression

Use: Required

Data Type: Numeric or String

A string or numeric expression that evaluates between 0 and 255.

Return Value

expression converted to a type of Byte.

Description

Converts expression to a Byte data type. The Byte type is the smallest data storage device in VBScript. Being only one byte in length, it can store unsigned numbers between 0 and 255.

Rules at a Glance

• If expression is a string, the string must be capable of being treated as a number.
• If expression evaluates to less than 0 or more than 255, an overflow error is generated.
• If expression isn't a whole number, CByte rounds the number prior to conversion.

Example

If IsNumeric(sMyNumber) Then If val(sMyNumber) >= 0 and val(sMyNumber) <= 255 Then BytMyNumber = Cbyte(sMyNumber) End If End If

Programming Tips and Gotchas

• Check that the value you pass to CByte is neither negative nor greater than 255.
• Use IsNumeric to insure the value passed to CByte can be converted to a numeric expression.
• When using CByte to convert floating-point numbers, fractional values up to but not including 0.5 are rounded down, while values greater than 0.5 are rounded up. Values of 0.5 are rounded to the nearest even number (i.e., they use the Banker's Rounding Algorithm).

See Also

IsNumeric Function

Syntax

CCur(expression)

expression

Use: Required

Data Type: Numeric or String

A string or numeric expression that evaluates to a number between -922,337,203,685,477.5808 and 922,337,203,685,477.5807.

Return Value

expression converted to a type of Currency.

Description

Converts an expression into a type of Currency.

Rules at a Glance

• If the expression passed to the function is outside the range of the Currency data type, an overflow error occurs.
• Expressions containing more than four decimal places are rounded to four decimal places.
• The only localized information included in the value returned by CCur is the decimal symbol.

Example

If IsNumeric(sMyNumber) Then curMyNumber = CCur(sMyNumber) End If

Programming Tips and Gotchas

• CCur doesn't prepend or append a currency symbol; for this, you need to use the FormatCurrency function. CCur does, however, correctly convert strings that include a localized currency symbol. For instance, if a user enters the string "$1234.68" into a text box whose value is passed as a parameter to the CCur function, CCur correctly returns a currency value of 1234.68.
• CCur doesn't include the thousands separator; for this, you need to use the FormatCurrency function. CCur does, however, correctly convert currency strings that include localized thousands separators. For instance, if a user enters the string "1,234.68" into a text box whose value is passed as a parameter to the CCur function, CCur correctly converts it to a currency value of 1234.68.

See Also

FormatCurrency, FormatNumber, FormatPercent Functions

Syntax

CDate(expression)

expression

Use: Required

Data Type: String or Numeric

Any valid date expression.

Return Value

expression converted into a Date type.

Description

Converts expression to a Date type. The format of expressionthe order of day, month, and yearis determined by the locale setting of your computer. To be certain of a date being recognized correctly by CDate, the month, day, and year elements of expression must be in the same sequence as your computer's regional settings; otherwise, the CDate function has no idea that in the expression "04/01/01," 4 is supposed to be the 4th of the month, not the month of April, for example.

CDate also converts numbers to a date. The precise behavior of the function, however, depends on the value of expression :

• If expression is less than or equal to 23 and includes a fractional component less than 60, the integer is interpreted as the number of hours since midnight, and the fraction is interpreted as the number of seconds.
• In all other cases, the integer portion of expression is converted to a date that interprets the integer as the number of days before (in the case of negative numbers) or after December 31, 1899, and its fractional part is converted to the time of day, with every .01 representing 864 seconds (14 minutes 24 seconds) after midnight.

Rules at a Glance

• CDate accepts both numerical date expressions and string literals. You can pass month names into CDate in either complete or abbreviated form; for example, "31 Dec 1997" is correctly recognized.
• You can use any of the date delimiters specified in your computer's regional settings; for most systems, this includes , / - and the space character.
• The oldest date that can be handled by the Date data type is 01/01/100, which in VBScript terms equates to the number -657434. Therefore, if you try to convert a number of magnitude greater than -657434 with CDate, an error ("Type mismatch") is generated.
• The furthest date into the future that can be handled by the Date data type is 31/12/9999, which in VBScript terms equates to the number 2958465. Therefore, if you try to convert a number higher than 2958465 with CDate, an error ("Type mismatch") is generated.
• A "Type mismatch" error is generated if the values supplied in expresssion are invalid. CDate tries to treat a month value greater than 12 as a day value.

Programming Tips and Gotchas

• Use the IsDate function to determine if expression can be converted to a date or time.
• A common error is to pass an uninitialized variable to CDate, in which case midnight will be returned
• A modicum of intelligence has been built into the CDate function. It can determine the day and month from a string regardless of their position, but only where the day number is larger than 12, which automatically distinguishes it from the number of the month. For example, if the string "30/12/97" were passed into the CDate function on a system expecting a date format of mm/dd/yy, CDate sees that 30 is obviously too large for a month number and treats it as the day. It's patently impossible for CDate to second guess what you mean by "12/5/97"is it the 12th of May, or 5th of December? In this situation, CDate relies on the regional settings of the computer to distinguish between day and month. This can also lead to problems, as you may have increased a month value to more than 12 inadvertently in an earlier routine, thereby forcing CDate to treat it as the day value. If your real day value is 12 or less, no error is generated, and a valid, albeit incorrect, date is returned.
• If you pass a two-digit year into CDate, how does it know which century you are referring to? Is "10/20/97" 20 October 1997 or 20 October 2097? The answer is that two-year digits less than 30 are treated as being in the 21st Century (i.e., 29 = 2029), and two-year digits of 30 and over are treated as being in the 20th Century (i.e., 30 = 1930).
• Don't follow a day number with "st," "nd," "rd," or "th," since this generates a type mismatch error.
• If you don't specify a year, the CDate function uses the year from the current date on your computer.

VBA/VBScript Differences

If you pass an initialized variable to the CDate function in VBA, the return value is 31 December 1899. In VBScript, the function's return value is 12:00:00 AM.

See Also

FormatDateTime Function

Syntax

CDbl(expression)

expression

Use: Required

Data Type: Numeric or String

-1.79769313486232E308 to -4.94065645841247E-324 for negative values; 4.94065645841247E-324 to 1.79769313486232E308 for positive values.

Return Value

expression cast as a Double type.

Description

Converts expression to a Double type.

Rules at a Glance

• If the value of expression is outside the range of the double data type, an overflow error is generated.
• Expression must evaluate to a numeric value; otherwise, a type mismatch error is generated.

Example

Dim dblMyNumber as Double If IsNumeric(sMyNumber) then dblMyNumber = CDbl(sMyNumber) End If

Programming Tips and Gotchas

Use IsNumeric to test whether expression evaluates to a number.

See Also

IsNumeric Function

Syntax

Chr(charactercode) ChrB(charactercode) ChrW(charactercode)

charactercode

Use: Required

Data Type: Long

An expression that evaluates to either an ANSI or Unicode character code.

Return Value

Chr, ChrB, and ChrW return a variant of the string type that contains the character represented by charactercode.

Description

Returns the character represented by charactercode.

Rules at a Glance

• Chr returns the character associated with an ANSI character code.
• ChrB returns a one-byte string.
• ChrW returns a Unicode character.

Programming Tips and Gotchas

• Use Chr(34) to embed quotation marks inside a string, as shown in the following example:

sSQL = "SELECT * from myTable where myColumn = " & Chr(34) & _ sValue & Chr(34)

• You can use the ChrB function to assign binary values to String variables.
• The following table lists some of the more commonly used character codes that are supplied in the call to the Chr function:

See Also

Asc, AscB, AscW Functions, CStr Function

Syntax

CInt(expression)

expression

Use: Required

Data Type: Numeric or String

The range of expression is -32,768 to 32,767; fractions are rounded.

Return Value

expression cast as an integer type.

Description

Converts expression to a type of integer; any fractional portion of expression is rounded.

Rules at a Glance

• expression must evaluate to a numeric value; otherwise, a type mismatch error is generated.
• If the value of expression is outside the range of the Integer data type, an overflow error is generated.
• When the fractional part of expression is exactly 0.5, CInt always rounds to the nearest even number. For example, 0.5 rounds to 0, and 1.5 rounds to 2.

Example

Syntax

Class name 'statements End Class

name

Use: Required

Data Type: n/a

The name of the class

Description

Defines a class and delimits the statements that define that class's member variables, properties, and methods.

Rules at a Glance

• name follows standard Visual Basic variable naming conventions.
• statements can consist of the following:
  • Private variable definitions. These variables are accessible within the class but not outside it.
  • Public variable definitions. (If variables are declared using the Dim keyword without an explicit indication of their accessibility, they are Public by default.) These variables become public properties of the class.
  • Public functions and subroutines defined with the Function...End Function or Sub...End Sub statements. The scope of routines not explicitly defined by the Public or Private keywords is public by default. These routines become the public methods of the class.
  • Private function and subroutines defined with the Function...End Function or Sub...End Sub statements. They are visible within the Class...End Class code block, but not to code outside the class.
  • Public properties defined using the Property Let, Property Get, and Property Set statements. Properties defined without an explicit Public or Private statement are also Public by default. They, along with any public variables, form the public properties of the class.
  • Private properties defined using the Property Let, Property Get, and Property Set statements. They are visible within the class, but inaccessible outside of it.

• The default member of the class can be defined by specifying the Default keyword in the member's Function, Sub, or Property Get statement.
• The Initialize event is fired and the Class_Initialize event procedure is executed, if it is present, when the class is instantiated.
• The Terminate event is fired and the Class_Terminate event procedure is executed, if it is present, when an instance of the class is destroyed. This occurs when the last variable or property holding the object reference is set to Nothing or when it goes out of scope. Note that, even if all the variables are destroyed, there are situations (such as circular references) in which the object persists until the script engine is destroyed. Hence, the Terminate event procedure may not be called until very late.
• The class can be instantiated by using the Set statement with the New keyword. For example, if a class named CObject is defined with the Class...End Class construct, the following code fragment instantiates an object belonging to the class:

  Dim oObj Set oObj = New CObject

Example

The example defines a class, CCounter, with one read-only property, Value, and one method, ShowCount, as well as an Initialize event procedure and one private variable:

Dim oCtr Set oCtr = New CCounter oCtr.Increment oCtr.Increment MsgBox "Count: " & oCtr.ShowCount ' definition of CCounter class Class CCounter Private lCtr Private Sub Class_Initialize( ) lCtr = 1 End Sub Public Sub Increment( ) lCtr = lCtr + 1 End Sub Public Function ShowCount( ) ShowCount = Me.Value End Function End Class

Programming Tips and Gotchas

• A property defined as a simple public variable cannot be designated as the class's default member.
• Public properties should be defined using the Property Let, Property Get, and Property Set statements, since they allow the value of a property to be modified in a controlled and predictable way. Defining a public variable that becomes accessible outside of the class (that is, defining a variable using either the Dim or Public keywords) is considered poor programming practice.
• The Me Keyword can be used within the Class...End Class construct to reference the object instance.
• The Initialize event procedure can be used to initialize variables and property values.
• The Terminate event procedure can be used to perform cleanup, such as releasing references to child objects, or closing database connections or recordsets. But be very careful about what code you run in the Terminate event terminator. Any code that results in the object being referenced again results in the terminated object's continued existence.
• A VBScript object instance should never be stored to the Session object in an ASP application. Since VBScript object instances are apartment-threaded, this has the effect of locking down the application to a single thread of execution.

VBA/VBScript Differences

The Class...End Class construct, which is the scripted equivalent of VBA class modules, is not supported in VBA.

See Also

Dim Statement, Function Statement, Initialize Event, Private Statement, Property Get Statement, Property Let Statement, Property Set Statement, Public Statement, Set Statement, Sub Statement, Terminate Event

Syntax

CLng(expression)

expression

Use: Required

Data Type: Numeric or String

The range of expression is -2,147,483,648 to 2,147,483,647; fractions are rounded.

Return Value

expression cast as a type of Long.

Description

Converts expression to a type of Long; any fractional element of expression is rounded.

Rules at a Glance

• expression must evaluate to a numeric value; otherwise, a type mismatch error is generated.
• If the value of expression is outside the range of the long data type, an overflow error is generated.
• When the fractional part is exactly 0.5, CLng always rounds it to the nearest even number. For example, 0.5 rounds to 0, and 1.5 rounds to 2.

Example

Syntax

[Public|Private] Const constantname = constantvalue

constantname

Use: Required

The name of the constant.

constantvalue

Use: Required

Data Type: Numeric or String

A constant value, and optionally, the + and - unary operators. Unlike variables, constants must be initialized.

Description

Declares a constant value; i.e., its value can't be changed throughout the life of the program or routine. One of the ideas of declaring constants is to make code easier to both write and read; it allows you to replace a value with a recognizable word.

Rules at a Glance

• The rules for constantname are the same as those of any variable: the name can be up to 255 characters in length and can contain any alphanumeric character or an underscore, although it must start with an alphabetic character. As is the case with variable names, these rules can be overridden by placing brackets around the constant name.
• constantvalue can be a string or numeric literal. It can be only a single value (a simple constant); that is, it cannot be an expression that includes a call to an intrinsic or user-defined function, property, or method, nor can it contain any arithmetic or string operators or variables. In addition, a constant can't be defined in terms of another constant, as in the statement:

  Public Const CDATE = CSTART_DATE ' Invalid

Example

Private Const my_Constant = 3.1417

Programming Tips and Gotchas

• The recommended coding convention for constants is the same as variables: use camel casing. This places the first letter of the first word in lowercase, and the first letter of subsequent words in uppercase. All other characters are in lowercase. To improve readability, you can also use underscores to separate words. For example, myConstant or my_Constant are constant names that adhere to this coding convention.
• One of the benefits of long variable and constant names (of up to 255 characters) in VBScript is that you can make your constant names as meaningful as possible while using abbreviations sparingly. After all, you may know what abbreviations mean, but will others?
• Rather than having to explicitly define constants found in type libraries, you can access the type library definitions from Windows Script Hosts by using the XML element in an .wsf file (for details, see Chapter 7), and from Active Server Pages by using the tag in the application's global.asa file.

VBA/VBScript Differences

• VBA allows you to explicitly define the data type of the constant. VBScript, since it does not support strong typing, does not.
• VBA supports complexconstants; that is, VBA allows you to define constants using other constants, as well as using expressions containing absolute values, operators, and constants. In contrast, VBScript supports only simple constants; that is, it allows you to define a constant using only an absolute value.

See Also

Private Statement, Public Statement

Syntax

Cos(number)

number

Use: Required

Data Type: Numeric expression

An angle in radians.

Return Value

A type of Double denoting the cosine of an angle.

Description

Takes an angle specified in radians and returns a ratio representing the length of the side adjacent to the angle divided by the length of the hypotenuse.

Rules at a Glance

The cosine returned by the function is between -1 and 1.

Example

Dim dblCosine as Double dblCosine = Cos(dblRadians)

Programming Tips and Gotchas

• To convert degrees to radians, multiply degrees by pi/180.
• To convert radians to degrees, multiply radians by 180/pi.

See Also

Atn Function, Sin Function, Tan Function

Syntax

CreateObject(servername, progID [, location])

servername

Use: Required

Data Type: String

The name of application providing the object.

ProgID

Use: Required

Data Type: String

The programmatic identifier (ProgID) of the object to create, as defined in the system registry.

Location

Use: Optional

Data Type: String

The name of the server where the object is to be created.

Return Value

A reference to an ActiveX object.

Description

Creates an instance of an OLE Automation (ActiveX) object. Prior to calling the methods, functions, or properties of an object, you are required to create an instance of that object. Once an object is created, you reference it in code using the object variable you defined.

Rules at a Glance

• In order to assign the object reference to a variable, you must use the Set keyword. For example:

  Dim oDoc Set oDoc = CreateObject("Word.Document")

• Programmatic identifiers use a string to identify a particular COM component or COM-enabled application. They are included among the subkeys of HKEY_CLASSES_ROOT in the system registry.
• Some common programmatic identifiers are shown in the following table:

• If an instance of the ActiveX object is already running, CreateObject may start a new instance when it creates an object of the required type.

Example

The following WSH example places text in the first cell of an Excel spreadsheet document, changes the font to bold, saves the document to the MyDocuments folder, and closes the Excel application. In this example, Excel must already be running for the code to work (the code uses the CreateObject function to create a new workbook, but not to open Excel itself), but you can just as easily use the CreateObject function to open an application:

' Get MyDocuments folder Dim oShell Dim docfolder Set oShell = WScript.CreateObject ("WScript.Shell") docfFolder = oShell.SpecialFolders ("MyDocuments") 'Create and save Excel worksheet Dim XLObj, XLBook, XLSheet Set XLObj = CreateObject ("Excel.Application") XLObj.Application.Visible = True XLObj. Workbooks.Add( ) Set XLSheet = XLObj.ActiveSheet XLSheet.Cells(1,1) = "Insert Text Here" XLSheet.Cells(1,1).Font.Bold = True XLSheet.SaveAs docFolder & "Test.xls" XLObj.Application.Quit

Programming Tips and Gotchas

• In a scripted environment, it's sometimes preferable to use the host application's object model to instantiate new objects rather than to use the VBScript CreateObject function. For instance, using the CreateObject method of the IIS Server object instead of the VBScript CreateObject function allows ASP to track the object instance and allows the object to participate in MTS or COM+ transactions. In Windows Script Host, using the CreateObject method of the WScript object instead of the VBScript CreateObject function allows WSH to track the object instance and to handle the object's events. When using VBScript to develop an Outlook form, the CreateObject method of the Application object is the preferred way to instantiate an external class.
• The CreateObject function does not succeed in client-side Internet Explorer scripts if the code attempts to create a dangerous object or the user's security policy does not allow it. In order to instantiate an object, use the HTML tag.
• VBScript offers the ability to reference an object on another network server. Using the Location parameter, you can pass in the name of a remote server and the object can be referenced from that server. This means that you could even specify different servers depending upon prevailing circumstances, as this short example demonstrates:

  Dim sMainServe Dim sBackUpServer sMainServer = "NTPROD1" sBackUpServer = "NTPROD2" If IsOnline(sMainServer) Then CreateObject("Sales.Customer",sMainServer) Else CreateObject("Sales.Customer",sBackUpServer) End If

• To use a current instance of an already running ActiveX object, use the GetObject function.
• If an object is registered as a single-instance object (i.e., an out-of-process ActiveX EXE), only one instance of the object can be created; regardless of the number of times CreateObject is executed, you will obtain a reference to the same instance of the object.
• An urban programming legend says it's necessary to release unused object references by setting them to Nothing when the reference is no longer needed. But since unused object references are released when they go out of scope, this step is not necessary. In general, object variables need to be explicitly released only to free circular references.
• Using the CreateObject function's location parameter to invoke an object remotely requires that the object be DCOM-aware. As an alternative, scripts can be run remotely using Remote Windows Script Host, a technology briefly discussed in Chapter 7.
• A apartment-threaded COM object instantiated using the CreateObject function should never be stored to the Session object in an ASP application, since doing so locks down the ASP application to a single thread of execution.

VBA/VBScript Differences

• In VBA, the CreateObject function is just one of the language constructs that you can use to instantiate a new object; you can also use the New keyword in either the object variable declaration or the object assignment. Because VBScript supports only late binding, however, CreateObject (along with a similar method in the target object model that you're using) is the only method available to instantiate objects that are external to the script.
• While CreateObject under VBA is an intrinsic part of the language, you cannot assume that CreateObject is necessarily available in a particular scripted environment. In Internet Explorer, for instance, calls to the CreateObject method generate a runtime error.

See Also

GetObject Function, Set Statement

Syntax

CSng(expression)

expression

Use: Required

Data Type: Numeric or String

The range of expression is -3.402823E38 to -1.401298E-45 for negative values; 1.401298E-45 to 3.402823E38 for positive values.

Return Value

expression cast as a type of Single.

Description

Returns a single-precision number.

Rules at a Glance

• expression must evaluate to a numeric value; otherwise, a type mismatch error is generated.
• If the value of expression is outside the range of the Single data type, an overflow error is generated.

Example

Dim sngMyNumber If IsNumeric(sMyNumber) then sngMyNumber = CSng(sMyNumber) End If

Programming Tips and Gotchas

• If you need to use a floating-point number in VBScript, there is no reason to use a Single; use a Double instead. Generally, a Single is used because it offers better performance than a Double, but this is not true in VBScript. Not only is a Single not smaller than a Double in the VBScript implementation, but the processor also converts Singles to Doubles, performs any numeric operations, and then converts Doubles back to Singles.
• Test that expression evaluates to a number by using the IsNumeric function.

See Also

FormatCurrency, FormatNumber, FormatPercent Functions, IsNumeric Function

Syntax

CStr(expression)

expression

Use: Required

Data Type: Any

Any expression that is to be converted to a string.

Return Value

expression converted to a String.

Description

Returns a string representation of expression.

Rules at a Glance

Almost any data can be passed to CStr to be converted to a string.

Example

Dim sMyString SMyString = CStr(100)

Programming Tips and Gotchas

• The string representation of Boolean values is either True or False, as opposed to their underlying values of 0 and -1.
• An uninitialized variable passed to CStr returns an empty string.
• An object reference cannot be passed to the CStr function. Attempting to do so generates a runtime error.

Syntax

Date

Return Value

Date returns a Date.

Description

Returns the current system date.

Rules at a Glance

They don't come any easier than this!

Programming Tips and Gotchas

To return both the current date and time in one variable, use the Now function.

See Also

IsDate Function, Now Function

Syntax

DateAdd(interval, number, date)

interval

Use: Required

Data Type: String

An expression denoting the interval of time you need to add or subtract (see the following table "Interval Settings").

number

Use: Required

Data Type: Any numeric type

An expression denoting the number of time intervals you want to add or subtract.

date

Use: Required

Data Type: Date

The date on which to base the DateAdd calculation.

Interval Settings

Return Value

A Date.

Description

Returns a Date representing the result of adding or subtracting a given number of time periods to or from a given date or time. For instance, you can calculate the date 178 months before today's date, or the date and time 12,789 minutes from now.

Rules at a Glance

• Specify the interval value as a string enclosed in quotation marks (e.g., "ww").
• If number is positive, the result will be after date; if number is negative, the result will be before date.
• The DateAdd function has a built-in calendar algorithm to prevent it from returning an invalid date. For example, if you add 10 minutes to 31 December 1999 23:55, DateAdd automatically recalculates all elements of the date to return a valid datein this case, 1 January 2000 00:05. In addition, the calendar algorithm takes the presence of 29 February into account for leap years.

Example

Dim lNoOfIntervals lNoOfIntervals = 100 Msgbox DateAdd("d", lNoOfIntervals, Now)

Programming Tips and Gotchas

• When working with dates, always check that a date is valid using the IsDate function prior to passing it as a parameter to the function.
• To add a number of days to date, use either the day of the year "y", the day "d", or the weekday "w".
• The Variant date type can handle only dates as far back as 100 A.D. DateAdd generates an error (runtime error number 5, "Invalid procedure call or argument") if the result precedes the year 100.
• The Variant date type can handle dates as far into the future as 9999 A.D.from a practical application standpoint, a virtual infinity. If the result of DateAdd is a year beyond 9999 A.D., the function generates runtime error number 5, "Invalid procedure call or argument."
• If number contains a fractional value, it's rounded to the nearest whole number before being used in the calculation.

See Also

DateDiff Function, DatePart Function, DateSerial Function, IsDate Function

Syntax

DateDiff(interval, date1, date2[, firstdayofweek[, firstweekofyear]])

interval

Use: Required

Data Type: String

The units of time used to express the result of the difference between date1 and date2 (see the following "Interval Settings" table).

date1

Use: Required

Data Type: Date

The first date you want to use in the differential calculation.

date2

Use: Required

Data Type: Date

The second date you want to use in the differential calculation.

firstdayofweek

Use: Optional

Data Type: Integer

A numeric constant that defines the first day of the week. If not specified, Sunday is assumed (see the following table "First Day of Week Constants").

firstweekofyear

Use: Optional

Data Type: Integer

A numeric constant that defines the first week of the year. If not specified, the first week is assumed to be the week in which January 1 occurs (see the following table "First Week of Year Constants").

Interval Settings

First Day of Week Constants

First Week of Year Constants

Return Value

A Long specifying the number of time intervals between two dates.

Description

The DateDiff function calculates the number of time intervals between two dates. For example, you can use the function to determine how many days there are between 1 January 1980 and 31 May 1998.

Rules at a Glance

• The calculation performed by DateDiff is always date2-- date1. Therefore, if date1 chronologically follows date2, the value returned by the function is negative.
• If interval is Weekday "w", DateDiff returns the number of weeks between date1 and date2. DateDiff totals the occurrences of the day on which date1 falls, up to and including date2, but not including date1. Note that an interval of "w" doesn't return the number of weekdays between two dates, as you might expect.
• If interval is Week "ww", DateDiff returns the number of calendar weeks between date1 and date2. To achieve this, DateDiff counts the number of Sundays (or whichever other day is defined to be the first day of the week by the firstdayofweek argument) between date1 and date2. date2 is counted if it falls on a Sunday, but date1 isn't counted, even if it falls on a Sunday.
• The firstdayofweek argument affects only calculations that use the "ww" (week) interval values.

Example

Dim dtNow, dtThen Dim sInterval Dim lNoOfIntervals dtNow = Date dtThen = #01/01/1990# sInterval = "m" lNoOfIntervals = DateDiff(sInterval, dtThen, dtNow) MsgBox lNoOfIntervals

Programming Tips and Gotchas

• When working with dates, always check that a date is valid using the IsDate function prior to passing it as a function parameter.
• When comparing the number of years between December 31 of one year and January 1 of the following year, DateDiff returns 1, although in reality, the difference is only one day.
• DateDiff considers the four quarters of the year to be January 1-March 31, April 1-June 30, July 1-September 30, and October 1-December 31. Consequently, when determining the number of quarters between March 31 and April 1 of the same year, for example, DateDiff returns 1, even though the latter date is only one day after the former.
• If interval is "m", DateDiff simply counts the difference in the months on which the respective dates fall. For example, when determining the number of months between January 31 and February 1 of the same year, DateDiff returns 1, even though the latter date is only one day after the former.
• To calculate the number of days between date1 and date2, you can use either Day of year "y" or Day "d".
• In calculating the number of hours, minutes, or seconds between two dates, if an explicit time isn't specified, DateDiff provides a default value of midnight (00:00:00).
• If you specify date1 or date2 as strings within quotation marks (" ") and omit the year, the year is assumed to be the current year, as taken from the computer's date. This allows the same code to be used in different years.

See Also

DateAdd Function, DatePart Function, IsDate Function

Syntax

DatePart(interval, date[,firstdayofweek[, firstweekofyear]])

interval

Use: Required

Data Type: String

The unit of time to extract from within date (see the following table "Interval Settings").

date

Use: Required

Data Type: Date

The Date value that you want to evaluate.

firstdayofweek

Use: Optional

Data Type: Integer

A numeric constant that defines the first day of the week. If not specified, Sunday is assumed (see the following table "First Day of Week Constants").

firstweekofyear

Use: Optional

Data Type: Integer

A numeric constant that defines the first week of the year. If not specified, the first week is assumed to be the week in which January 1 occurs (see the following table "First Week of Year Constants").

Interval Settings

First Day of Week Constants

First Week of Year Constants

Return Value

An Integer.

Description

Extracts an individual component of the date or time (like the month or the second) from a date/time value. It returns an Integer containing the specified portion of the given date. DatePart is a single function encapsulating the individual Year, Month, Day, Hour, Minute, and Second functions.

Rules at a Glance

• The firstdayofweek argument affects only calculations that use either the "w" or "ww" interval values.
• The firstdayofweek argument affects only calculations that use the "ww" interval value.

Example

Dim sTimeInterval Dim dtNow sTimeInterval = "n" 'minutes dtNow = Now MsgBox DatePart(sTimeInterval, dtNow)

Programming Tips and Gotchas

• When working with dates, always check that a date is valid using the IsDate function prior to passing it as a function parameter.
• If you specify date within quotation marks (" ") omitting the year, the year is assumed to be the current year taken from the computer's date.
• If you attempt to extract either the hours, the minutes, or the seconds, but date1 doesn't contain the necessary time element, the function assumes a time of midnight (0:00:00).

See Also

DateSerial Function, Day Function, Month Function, Year Function, Minute Function, Hour Function, Second Function

Syntax

DateSerial(year, month, day)

year

Use: Required

Data Type: Integer

Number between 0 and 9999, inclusive.

month

Use: Required

Data Type: Integer

Any numeric expression to express the month between 1 and 12.

day

Use: Required

Data Type: Integer

Any numeric expression to express the day between 1 and 31.

Return Value

A Date.

Description

Returns a Date from the three date components (year, month, and day). For the function to succeed, all three components must be present and all must be numeric values.

Rules at a Glance

• If the value of a particular element exceeds its normal limits, DateSerial adjusts the date accordingly. For example, if you tried DateSerial (96,2,31)February 31, 1996DateSerial returns March 2, 1996.
• You can specify expressions or formulas that evaluate to individual date components as parameters to DateSerial. For example, DateSerial (98,10+9,23) returns 23 March 1999. This makes it easier to use DateSerial to form dates whose individual elements are unknown at design time or that are created on the fly as a result of user input.

Example

Dim iYear, iMonth, iday iYear = 1987 iMonth = 3 + 11 iday = 16 MsgBox DateSerial(iYear, iMonth, iday)

Programming Tips and Gotchas

• If any of the parameters exceed the range of the Integer data type (-32,768 to 32,767), an error (runtime error 6, "Overflow") is generated.
• The Microsoft documentation for this function incorrectly states, "For the year argument, values between 0 and 99, inclusive, are interpreted as the years 1900-1999." In fact, DateSerial handles two-digit years in the same way as other Visual Basic date functions. A year argument between 0 and 29 is taken to be in the 21st Century (2000 to 2029); year arguments between 30 and 99 are taken to be in the 20th Century (1930 to 1999). Of course, the safest way to specify a year is to use the full four digits.

See Also

DateAdd Function

Syntax

DateValue(stringexpression)

stringexpression

Use: Required

Data Type: String expression

Any of the date formats recognized by IsDate.

Return Value

Variant of type Date.

Description

Returns a Date variant containing the date represented by stringexpression. DateValue can successfully recognize a stringexpression in any of the date formats recognized by IsDate. DateValue doesn't return time values in a date/time string; they are simply dropped. However, if stringexpression includes a valid date value but an invalid time value, a runtime error results.

Rules at a Glance

• The order of the day, the month, and the year within stringexpression must be the same as the sequence defined by the computer's regional settings.
• Only those date separators recognized by IsDate can be used.
• If you don't specify a year in your date expression, DateValue uses the current year from the computer's system date.

Example

Dim dateExpression dateExpression = #10 March 2003# If IsDate (dateExpression) Then MsgBox DateValue(dateExpression) Else MsgBox "Invalid date" End If

Programming Tips and Gotchas

• When working with dates, always check that a date is valid using the IsDate function prior to passing it as a function parameter.
• If stringexpression includes time information as well as date information, the time information is ignored; however, if only time information is passed to DateValue, an error is generated.
• DateValue handles two-digit years in the following manner: year arguments between 0 and 29 are taken to be in the 21st Century (2000 to 2029), and year arguments between 30 and 99 are taken to be in the 20th Century (1930 to 1999). The safest way to specify a year is to use the full four digits.
• The current formats being used for dates are easier to discover on Windows NT than on Windows 9x. On Windows NT, the date formats are held as string values in the following registry keys:

  Date Separator

  HKEY_CURRENT_USERControl PanelInternational, sDate value entry

  Long Date

  HKEY_CURRENT_USERControl PanelInternational, sLongDate value entry

  Short Date

  HKEY_CURRENT_USERControl PanelInternational, sShortDate value entry

• The more common approach to date conversion is to use the CDate function. Microsoft also recommends using CDate and the other C... conversion functions due to their enhanced capabilities and their locale awareness.

See Also

CDate Function, DateSerial Function, IsDate Function

Syntax

Day(dateexpression)

dateexpression

Use: Required

Data Type: Any valid date expression

Any expression capable of conversion to a Date.

Return Value

Variant of type Integer.

Description

Returns a variant integer data type that can take on a value ranging from 1 to 31, representing the day of the month of dateexpression. dateexpression, the argument passed to the Day function, must be a valid date/time or time value.

Rules at a Glance

• dateexpression can be any variant, numeric expression, or string expression that represents a valid date.
• The range of dateexpression is 1/1/100 to 12/31/9999.
• If dateexpression is Null, Null is returned.

Programming Tips and Gotchas

• When working with dates, always check that a date is valid using the IsDate function prior to passing it as a function parameter.
• If dateexpression omits the year, Day still returns a valid day.
• If the day portion of dateexpression is outside its valid range, the function generates runtime error 13, "Type mismatch." This is also true if the day and month portion of dateexpression is 2/29 for a nonleap year.
• To return the day of the week, use the WeekDay function.

See Also

DatePart Function, Weekday Function, WeekdayName Function, Month Function, Year Function

Createable

Yes

Library

Microsoft Scripting Runtime

Description

The Dictionary object is similar to a Collection object, except that it's loosely based on the Perl associative array. Like an array or a Collection object, the Dictionary object holds elements, called items or members, containing data. A Dictionary object can contain any data whatsoever, including objects and other Dictionary objects. Access the value of these dictionary items by using unique keys (or named values) that are stored along with the data, rather than by using an item's ordinal position as you do with an array. This makes the Dictionary object ideal when you need to access data that is associated with a unique named value.

You can access each item stored to a Dictionary object by using the For Each ...Next construct. However, rather than returning a variant containing the data value stored to the Dictionary object as you would expect, it returns a variant containing the key associated with the member. You then have to pass this key to the Item method to retrieve the member, as the following example shows:

Dim vKey Dim sItem, sMsg Dim oDict Set oDict = CreateObject("Scripting.Dictionary") oDict.Add "One", "Engine" oDict.Add "Two", "Wheel" oDict.Add "Three", "Tire" oDict.Add "Four", "Spanner" For Each vKey In oDict sItem = oDict.Item(vKey) sMsg = sMsg & sItem & vbCrLf Next MsgBox sMsg

Dictionary Object Properties

The Dictionary object includes the following four properties:

Dictionary Object Methods

The Dictionary object supports the following five methods:

Syntax

dictionaryobject.Add key, item

dictionaryobject

Use: Required

Data Type: Dictionary object

A reference to a Dictionary object.

key

Use: Required

Data Type: Any

A key value that's unique in the Dictionary object.

item

Use: Required

Data Type: Any

The item to be added to the dictionary.

Description

Adds a key and its associated item to the specified Dictionary object.

Rules at a Glance

• If the key isn't unique, runtime error 457, "This key is already associated with an element of this collection," is generated.
• item can be of any data type, including objects and other Dictionary objects.

Example

The example uses a Dictionary object to store state abbreviations and their corresponding state names:

Dim StateCode, StateName Dim StateDict Dim Key Set StateDict = CreateObject("Scripting.Dictionary") StateCode = "CA" StateName = "California" StateDict.Add StateCode, StateName StateCode = "NY" StateName = "New York" StateDict.Add StateCode, StateName StateCode = "MI" StateName = "Michigan" StateDict.Add StateCode, StateName Key = "NY" MsgBox StateDict.Item(Key)

Programming Tips and Gotchas

• The order of members within a Dictionary object is officially undefined. That is, you can't control the position of individual members, nor can you retrieve individual members based on their position within the Dictionary object. Your code, in short, should make no assumptions about the position of individual elements within the Dictionary objects.
• Once you add a key and its associated data item, you can change the key by using the write-only Key property.
• Use the Dictionary object to store tables of data, and particularly to store single items of data that can be meaningfully accessed by a key value.
• The use of the Dictionary object to store multifield data records is not recommended; instead, classes offer a better programmatic alternative. Typically, you would store a record by adding an array representing the record's field values to the dictionary. But assigning arrays to items in the Dictionary object is a poor programming practice, since individual elements of the array cannot be modified directly once they are assigned to the dictionary.

See Also

Dictionary.Key Property

Data Type

Long

Description

Sets or returns the mode used to compare the keys in a Dictionary object.

Rules at a Glance

• CompareMode can be set only on a dictionary that doesn't contain any data.
• The CompareMode property can have either of the following two values:

  0, Binary

  This is the default value. It compares the keys with a string byte-per-byte to determine whether a match exists.

  1, Text

  Uses a case-insensitive comparison when attempting to match keys with a string.

  In addition, the value of CompareMode can be greater than 2, in which case it defines the locale identifier (LCID) to be used in making the comparison.

Programming Tips and Gotchas

• You need to explicitly set the CompareMode property only if you do not wish to use the default binary comparison mode.
• The Scripting Runtime type library defines constants (BinaryCompare and TextCompare) that can be used in place of their numeric equivalents. You can do this in one of three ways. You can define the constants yourself by adding the following code to your script:

  Const BinaryCompare = 0 Const TextCompare = 1

  You can also use the equivalent vbBinaryCompare and vbTextCompare constants that are defined in the VBScript library.

  Finally, if you're an ASP programmer, you can use the METADATA directive to access the Scripting Runtime type library; if you're developing a Windows Script Host script, you can include the following line in a Windows Script Host (.wsf ) file in order to access the constants from the Scripting Runtime type library:

   

• Practically, the CompareMode property indicates whether the comparison between existing key names and the key argument of the Dictionary object's Add method, Exists method, Item property, or Key property will be case-sensitive (BinaryCompare) or case-insensitive (TextCompare). By default, comparisons are case-sensitive.

Data Type

Long

Description

A read-only property that returns the number of key/item pairs in a Dictionary object.

Rules at a Glance

This property returns the actual number of items in the dictionary. So if you use the Count property to iterate the items in the dictionary, you would use code like the following:

Dim ctr For ctr = 0 to dictionary.Count - 1 ' do something Next

Syntax

dictionaryobject.Exists(key)

dictionaryobject

Use: Required

Data Type: Dictionary object

A reference to a Dictionary object.

key

Use: Required

Data Type: String

The key value being sought.

Return Value

Boolean

Description

Determines whether a given key is present in a Dictionary object.

Rules at a Glance

Returns True if the specified key exists in the Dictionary object; False if not.

Programming Tips and Gotchas

• If you attempt to use the Item property to return the item of a nonexistent key, or if you assign a new key to a nonexistent key, the nonexistent key is added to the dictionary, along with a blank item. To prevent this, you should use the Exists property to ensure that the Key is present in the dictionary before proceeding.
• The way in which key is compared with the existing key values is determined by the setting of the Dictionary object's CompareMode property.

Example

If oDict.Exists(strOldKey) Then oDict.Key(strOldKey) = strNewKey End If

Syntax

The syntax for setting an item is:

dictionaryobject.Item(key) = item

The syntax for returning an item is:

value = dictionaryobject.Item(key)

dictionaryobject

Use: Required

Data Type: Dictionary object

A reference to a Dictionary object.

key

Use: Required

Data Type: String

A unique string key for this Dictionary object.

item

Use: Optional

Data Type: Any

The data associated with key.

Data Type

Any

Description

Sets or returns the data item to be linked to a specified key in a Dictionary object.

Rules at a Glance

• The Item property is the default member of the Dictionary object.
• The data type is that of the item being returned.
• Unlike the Item property of most objects, the Dictionary object's Item property is read/write. If you try to set item to a nonexistent key, the key is added to the dictionary, and the item is linked to it as a sort of "implicit add."

Programming Tips and Gotchas

• The Dictionary object doesn't allow you to retrieve an item by its ordinal position.
• If you provide a nonexistent key when trying to retrieve an item, the dictionary exhibits rather strange behavior: it adds key to the Dictionary object along with a blank item. You should therefore use the Exists method prior to setting or returning an item, as the example shows.
• If the item to be assigned or retrieved from the Dictionary object is itself an object, be sure to use the Set keyword when assigning it to a variable or to the Dictionary object.
• The comparison of key with member keys is defined by the value of the Dictionary object's CompareMode property.
• Although the read/write character of the Dictionary object's Item property has its drawbacks, it also has its advantages. In particular, it makes it easy to overwrite or replace an existing data item, since its Item property is read/write: simply assign the new value like you would with any other property.
• The Dictionary object should never be used to store HTML form or query data in Session scope in an ASP application. Since the Dictionary object is an apartment-threaded COM object, this has the effect of locking down the application to a single thread of execution.

Example

The example uses the Dictionary object as a lookup table to retrieve the state name that corresponds to the state code entered by the user. The HTML page that submits user information to the server is as follows:

Syntax

dictionaryobject.Items

dictionaryobject

Use: Required

Data Type: Dictionary object

A reference to a Dictionary object.

Return Value

A Variant array.

Description

Returns an array containing all the items in the specified Dictionary object.

Rules at a Glance

The returned array is always a zero-based variant array whose data type matches that of the items in the Dictionary object.

Programming Tips and Gotchas

• The only way to directly access members of the Dictionary is via their key values. However, using the Items method, you can "dump" the data from the Dictionary into a zero-based variant array. The data items can then be accessed like an array in the normal way, as the following code shows:

  Dim vArray vArray = DictObj.Items For i = 0 to DictObj.Count -1 Response.Write vArray(i) & "

  " Next I

• The Items method retrieves only the items stored in a Dictionary object; you can retrieve all the Dictionary object's keys by calling its Keys method.

See Also

Dictionary.Keys Method

Syntax

dictionaryobject.Key(key) = newkey

dictionaryobject

Use: Required

Data Type: Dictionary object

A reference to a Dictionary object.

key

Use: Required

Data Type: String

The key of an existing dictionary item.

newkey

Use: Required

Data Type: String

A new unique key for this dictionary item.

Data Type

A String.

Description

Replaces an existing key with a new one.

Rules at a Glance

• The Key property is write-only.
• key, the existing key value, must exist in the dictionary or an error results.
• newkey must be unique and must not already exist in the dictionary or an error results.
• The comparison of key and newkey with existing key values is defined by the Dictionary object's CompareMode property.

Example

Private Function ChangeKeyValue(sOldKey, sNewKey) 'Assumes oDictionary is a public object If oDictionary.Exists(sOldKey) Then oDictionary.Key(sOldKey) = sNewKey ChangeKeyValue = True Else ChangeKeyValue = False End If End Function

Programming Tips and Gotchas

• Use the Key property to change the name of an existing key. Use the Add method to add a new key and its associated value to the Dictionary object. Use the Keys method to retrieve the names of all keys; this is especially useful when you don't know the names or the contents of the dictionary in advance.
• Attempting to retrieve the key name (a nonsensical operation, since this amounts to providing the key's name in order to retrieve the key's name) generates an error, as does attempting to modify a key name that hasn't already been added to the dictionary.
• Using a For Each...Next loop to iterate the members of a Dictionary object involves an implicit call to the Key property. In other words, each iteration of the loop returns a key, rather than a data item. To retrieve the member's data, you then must use its key value to access its data through the Item property. This is illustrated in the example for the Dictionary.Item property.

Syntax

dictionaryobject.Keys

dictionaryobject

Use: Required

Data Type: Dictionary object

A reference to a Dictionary object.

Return Value

An array of strings.

Description

Returns an array containing all the Key values in the specified Dictionary object.

Rules at a Glance

The returned array is always a 0-based variant array whose data type is String.

Programming Tips and Gotchas

The Keys method retrieves only the keys stored in a Dictionary object. You can retrieve all the Dictionary object's items by calling its Items method. You can recall an individual data item by using the Dictionary object's Item property.

Example

Dim vArray vArray = DictObj.Keys For i = 0 to DictObj.Count -1 Response.Write vArray(i) & " " Next

Syntax

dictionaryobject.Remove key

dictionaryobject

Use: Required

Data Type: Dictionary object

A reference to a Dictionary object.

key

Use: Required

Data Type: String

The key associated with the item to be removed.

Description

Removes both the specified key and its associated data (i.e., its item) from the dictionary.

Rules at a Glance

If key doesn't exist, runtime error 32811, "Element not found," occurs.

Syntax

dictionaryobject.RemoveAll

dictionaryobject

Use: Required

Data Type: Dictionary object

A reference to a Dictionary object.

Description

Clears out the dictionary; in other words, removes all keys and their associated data from the dictionary.

Programming Tips and Gotchas

If you want to remove a selected number of members rather than the entire contents of the dictionary, use the Remove method.

Syntax

Dim varname[([subscripts])], varname[([subscripts])]

varname

Use: Required

Your chosen name for the variable.

subscripts

Use: Optional

Dimensions of an array variable.

Description

Declares and allocates storage space in memory for variables. The Dim statement is used either at the start of a procedure or the start of a global script block. In the first case, the variable declared using Dim is local to the procedure. In the second, it's available throughout the module.

Rules at a Glance

• You can declare multiple variables in a single Dim statement, as long as you use a comma to delimit them.
• When variables are first initialized with the Dim statement, they have a value of Empty. In addition, if a variable has been initialized but not assigned a value, the following expressions will both evaluate to True:

  If vVar = 0 Then If vVar = "" Then

• To declare array variables, use the following syntax:

  Fixed length, single dimension

  Dim arrayname(upper)

  Example: Dim myArray(10)

  Fixed length, multidimensional

  Dim arrayname(upper, upper, ...)

  Example: Dim MyArray(20,30)

  Variable length, single or multidimensional

  Dim arrayname( )

  Example: Dim myArray( )

• You can declare a multidimensional array with up to 60 dimensions.
• Variable-length arrays can be resized using the ReDim statement. Fixed-length arrays can't be resized.

Example

The example shows how to use the Dim statement to define a variable that receives an array returned by a function:

Dim Input, NumArray Input = InputBox("Enter three numbers separated by commas: ") NumArray = Split(Input, ",") If IsEmpty(NumArray) Then MsgBox "No numbers were entered." Else Dim Sum, Element For Each Element in NumArray If IsNumeric(Element) Then Sum = Sum + CDbl(Element) Next MsgBox "The total of the numbers is: " & Sum End If

Programming Tips and Gotchas

• It's accepted practice to place all the Dim statements to be used in a particular procedure at the beginning of that procedure, and to place all Dim statements for global variables at the beginning of the script block.
• Variables declared with Dim in the global script block are available to all procedures within the script. At the procedure level, variables are available only within the procedure.

VBA/VBScript Differences

• VBA allows you to instantiate objects of a particular type through early binding by using the New keyword. VBScript does not support the New keyword when used with Dim statement, nor does it support strong typing of objects.
• VBA supports the use of the WithEvents keyword, which allows VBA code to trap the events fired by an object of a particular type (that is, by a strongly typed object). VBScript does not support the keyword and hence does not allow you to trap events that are not otherwise supported by the host object model. For instance, you can trap the Application_OnStart, Application_OnEnd, OnTransactionCommit, OnTransactionAbort, Session_OnStart, and Session_OnEnd events in an ASP application. (For details on events supported by each object model, see Chapter 5 through Chapter 8, which discuss the object models of each host environment that supports VBScript.) A partial exception to this lack of support for external events is Windows Script Host, which allows you to trap an object's events by supplying an extra parameter to the WScript.CreateObject method or by calling the WScript.ConnectObject method.
• In VBA, only variables explicitly declared as variants and variables whose data type has not been declared are reported by the IsEmpty function to be empty, and return True when compared to zero or to a null string. This is true of all variables in VBScript, because it does not support strong typing.

See Also

Const Statement, Private Statement, Public Statement, ReDim Statement

Syntax

Do [{While | Until} condition] [statements] [Exit Do] [statements] Loop

or:

Do [statements] [Exit Do] [statements] Loop [{While | Until} condition]

condition

Use: Optional

Data Type: Boolean expression

An expression that evaluates to True or False.

statements

Use: Optional

Program statements that are repeatedly executed while, or until, condition is True.

Description

Repeatedly executes a block of code while or until a condition becomes True.

Rules at a Glance

• On its own, Do...Loop repeatedly executes the code that is contained within its boundaries indefinitely. You therefore need to specify under what conditions the loop is to stop repeating. Sometimes, this requires modifying the variable that controls loop execution within the loop. For example:

  Do intCtr = intCtr + 1 ' Modify loop control variable Response.Write "Iteration " & intCtr & _ " of the Do loop..." & " " ' Compare to upper limit If intCtr = 10 Then Exit Do Loop

  Failure to do this results in the creation of an endless loop.

• Adding the Until keyword after Do instructs your program to Do something Until the condition is True. Its syntax is:

  Do Until condition code to execute Loop

  If condition is True before your code gets to the Do statement, the code within the Do...Loop is ignored.

• Adding the While keyword after Do repeats the code while a particular condition is True. When the condition becomes False, the loop is automatically exited. The syntax of the Do While statement is:

  Do While condition code to execute Loop

  Again, the code within the Do...Loop construct is ignored if condition is False when the program arrives at the loop.

• In some cases, you may need to execute the loop at least once. You might, for example, evaluate the values held within an array and terminate the loop if a particular value is found. In that case, you'd need to execute the loop at least once. To do this, place the Until or While keyword along with the condition after the Loop statement. Do...Loop Until always executes the code in the loop at least once and continues to loop until the condition is True. Likewise, Do...Loop While always executes the code at least once, and continues to loop while the condition is True. The syntax of these two statements is as follows:

  Do code to execute Loop Until condition Do code to execute Loop While condition

• A Null condition is treated as False.
• Your code can exit the loop at any point by executing the Exit Do statement.

Programming Tips and Gotchas

• Inexperienced programmers often think that a loop exits as soon as the condition that terminates the loop is met. In fact, however, it exits whenever the conditional statement that evaluates the loop control expression is executed and that expression is True. For example, in the code:

  Do While X <> 10 ' This always executes if the loop is entered ' Set loop termination variable X = 10 ' Any code here still executes. There is nothing ' monitoring X Loop

  all statements following the assignment execute until the condition at the top of the loop is evaluated.

• You'll also encounter situations in which you intend to continually execute the loop while or until a condition is True, except in a particular case. This type of exception is handled using the Exit Do statement. You can place as many Exit Do statements within a Do...Loop structure as you require. As with any exit from a Do...Loop, whether it's exceptional or normal, the program continues execution on the line directly following the Loop statement. The following code fragment illustrates the use of Exit Do:

  Do Until condition1 'code to execute If condition2 Then Exit Do End if 'more code to executeonly if condition2 is false Loop

See Also

For Each . . . Next Statement, For . . . Next Statement, While . . . Wend Statement

Returned by

File.Drive property

FileSystemObject.Drives.Item property

Createable

No

Library

Microsoft Scripting Runtime

Description

Represents a single drive connected to the current machine, including a network drive. By using the Drive object, you can interrogate the system properties of any drive. In addition, you can use the Folder object returned by the Drive object's RootFolder property as your foothold into the physical drive's filesystem.

A new instance of the Drive object cannot be created. Instead, a Drive object that represents an existing physical drive typically is retrieved from the FileSystemObject object's Drives collection, as in the following code fragment, which retrieves an object reference that represents the C: drive:

Dim oFS, oDrive Set oFS = CreateObject("Scripting.FileSystemObject") set oDrive = oFS.Drives("C")

For an overview of the File System object model, including the library reference needed to access it, see the "File System Object Model" entry.

Properties

All Drive object properties are read-only. In addition, removable media drives must be ready (i.e., have media inserted) for the Drive object to read certain properties.

AvailableSpace

Data Type: Long

Returns the number of bytes unused on the disk. Typically, the AvailableSpace property returns the same number as the Drive object's FreeSpace property, although differences may occur on systems that support quotas. In early versions of the Scripting Runtime, AvailableSpace was capable of storing only values that ranged from 0 to 2^31, or 2,147,483,648; in other words, in the case of drives with over 2 GB free, it failed to accurately report the amount of available free space.

In order to check the amount of available space on the drive, the drive must be ready. Otherwise, an error is likely to result. This makes it worthwhile to check the value of the IsReady property before attempting to retrieve a drive's free space, particularly if your script is iterating the Drives collection.

DriveLetter

Data Type: String

The drive letter used for this drive on the current machine (e.g., C ). In addition, its value is an empty string ("") if the drive is a network share that has not been mapped to a local drive letter.

DriveType

Data Type: Long

A value (see the following table) indicating the type of drive. Any remote drive is shown only as remote. For example, a shared CD-ROM or Zip drive that is both remote and removable is shown simply as remote (i.e., it returns a value of 3) on any machine other than the machine on which it's installed.

The Scripting Runtime type library defines the constants shown in the above table's Constant column that can be used in place of their numeric equivalents. You can take advantage of these constants in your scripts in one of two ways. You can define the constants yourself by adding the following code to your script:

Const Unknown = 0 Const Removable = 1 Const Fixed = 2 Const Remote = 3 Const CDRom = 4 Const RAMDisk = 5

You can also use the ASP METADATA tag to access the constants from the type library, or you can include the following line in a Windows Script Host (.wsf ) file in order to access the constants from the Scripting Runtime type library:

The DriveType property does not require that the drive be ready to return a value.

FileSystem

Data Type: String

The installed filesystem; returns FAT, FAT32, NTFS, or CDFS. In order to determine that the filesystem in place, a device must be present on removable drives or runtime error 71, "Disk not ready," results.

FreeSpace

Data Type: Long

The number of bytes unused on the disk. Typically, its value is the same as the Drive object's AvailableSpace property, although differences may occur on computer systems that support quotas.

In early versions of the scripting Runtime, the property was capable of storing only values that ranged from 0 to 231, or 2,147,483,648. In other words, in the case of drives with over 2 GB free, it failed to accurately report the amount of available free space.

IsReady

Data Type: Boolean

For hard drives, this should always return True. For removable media drives, True is returned if media is in the drive; otherwise, False is returned.

A number of Drive object properties raise an error if the drive they represent is not ready. You can use the IsReady property to check the status of the drive and prevent your script from raising an error.

Path

Data Type: String

The drive name followed by a colon (e.g., C:). (Note that it does not include the root folder.) This is the default property of the Drive object.

RootFolder

Data Type: Folder object

Gives you access to the rest of the drive's filesystem by exposing a Folder object representing the root folder.

SerialNumber

Data Type: Long

The serial number of the drive, an integer that uniquely identifies the drive or disk. If a disk or CD-ROM has been assigned a serial number, you can use this property to insure that the correct disk is present in a drive that has removable media.

ShareName

Data Type: String

For a network share, returns the machine name and share name in UNC format (e.g., NTSERV1TestWork). If the Drive object does not represent a network drive, the ShareName property returns a zero-length string ("").

TotalSize

Data Type: Double

The total size of the drive in bytes. In early versions of the Scripting Runtime, the TotalSize property was capable of storing only values that ranged from 0 to 231, or 2,147,483,648. In other words, in the case of drives larger than 2 GB, it failed to accurately report the total drive size.

In order to check the amount of total space on the drive, the drive must be ready. Otherwise, a "Disk not ready" error is likely to result. This makes it worthwhile to check the value of the IsReady property before attempting to retrieve a drive's free space, particularly if your script is iterating the Drives collection.

VolumeName

Data Type: String

The drive's volume name, if one is assigned (e.g., DRIVE_C). If a drive or disk has not been assigned a volume name, the VolumeName property returns an empty string (""). This is the only read/write property supported by the Drive object.

In order to retrieve the volume name, the drive must be ready. Otherwise, a "Disk not ready" error is likely to result. This makes it worthwhile to check the value of the IsReady property before attempting to retrieve a drive's volume name, particularly if your script is iterating the Drives collection.

Returned by

FileSystemObject.Drives property

Createable

No

Library

Microsoft Scripting Runtime

Description

All drives connected to the current machine are included in the Drives collection, even those that aren't currently ready (like removable media drives with no media inserted in them). The Drives collection object is read-only.

The Drives collection cannot be created; instead, it is returned by the Drives property of the FileSystemObject object, as the following code fragment illustrates:

Dim oFS, oDrives Set oFS = CreateObject("Scripting.FileSystemObject") Set oDrives = oFS.Drives

For an overview of the filesystem object model, including the library reference needed to access it, see the "File System Object Model" entry.

Properties

Count

Data Type: Long

Returns the number of Drive objects in the collection.

Item

Syntax: oDrives.Item(key)

Data Type: Drive object

Returns a Drive object whose key is key, the drive letter. This is an unusual collection, since the drive's index value (its ordinal position in the collection) can't be used; attempting to do so generates runtime error 5, "Invalid procedure call or argument." Since attempting to retrieve a Drive object for a drive that doesn't exist generates runtime error 68, it's a good idea to call the FileSystemObject object's DriveExists method beforehand.

Example

Dim ofsFileSys As FileSystemObject Dim ofsDrives As Drives Dim ofsDrive As Drive Set ofsFileSys = New FileSystemObject Set ofsDrives = ofsFileSys.Drives Set ofsDrive = ofsDrives.Item("C") MsgBox ofsDrive.DriveType

See Also

Drive Object, FileSystemObject.Drives Property

Syntax

End Class End Function End If End Property End Select End Sub End With

Description

Ends a procedure or a block of code.

Rules at a Glance

The End statement is used as follows:

Programming Tips and Gotchas

The End statement used by itself to terminate the program is not supported within a VBScript script or procedure. Instead you should terminate execution of a procedure prematurely using the Exit... statement. You can also terminate the script or application by calling a method belonging to an object of the object model you are using. These are shown in the following table:

VBA/VBScript Differences

VBA supports the End statement, which immediately terminates execution of code and, in the case of Visual Basic, terminates the application. The End statement, however, is not supported in VBScript.

See Also

Exit Statement

Syntax

Erase arraylist

arraylist

Use: Required

Data Type: Variant array

A list of array variables to clear.

Description

Resets the elements of an array to their initial (unassigned) values. In short, Erase "clears out" or empties an array.

Rules at a Glance

• Specify more than one array to be erased by using commas to delimit arraylist.
• Fixed array variables remain dimensioned; on the other hand, all memory allocated to dynamic arrays is released.
• After the Erase statement executes, TypeName returns "Variant( )" for a fixed-length array; in addition, the IsEmpty function returns True when individual members of the array are passed to it, and comparisons of an individual member of the array with an empty string ("") and with zero both return True. On the other hand, the TypeName function returns Empty for a dynamic array, and comparisons of the array with an empty string ("") and zero also return True.

Programming Tips and Gotchas

Once you use Erase to clear dynamic arrays, they must be redimensioned with ReDim before being used again. This is because Erase releases the memory storage used by the dynamic array back to the operating system, which sets the array to have no elements.

VBA/VBScript Differences

Because VBA can be strongly typed, the behavior of the Erase statement in clearing a fixed array varies, depending on the array's data type. The effect of the Erase statement on a fixed variant array in VBScript is described earlier in the "Rules at Glance" section.

See Also

Dim Statement, ReDim Statement

Description

The Err object contains properties and methods that allow you to obtain information about a single runtime error in a VBScript script. It also allows you to generate errors and to reset the error object. Because the Err object is an intrinsic object (which means that it's part of every VBScript script you create) with global scope, you don't need to create an instance of it within your code.

When an error is generated in your applicationwhether it's handled or notthe properties of the Err object are assigned values you can then access to gain information about the error that occurred. You can even generate your own errors explicitly using the Err.Raise method. You can also define your own errors to unify the error-handling process.

When your program reaches an On Error Resume Next or On Error Goto 0 statement, the Err object is cleared and its properties reinitialized. This can also be achieved explicitly using the Err.Clear method.

Properties

Methods

Programming Tips and Gotchas

The VBScript Err object isn't a collection; it contains only information about the last error, if one occurred. You could, however, implement your own error collection class to store a number of errors by copying error information from the Err object into an object array that holds error information.

VBA/VBScript Differences

• The VBA Err object includes one additional property, LastDLLError, that reports the last error code generated by a call to a DLL routine.
• In VBA, the Err object is automatically reset whenever an Exit Function, Exit Sub, Exit Property, Resume, or On Error statement is encountered, the Err object is cleared, and its properties reinitialized. In VBScript, this occurs only when an On Error Resume Next or an On Error Goto 0 statement is executed.

See Also

Err.Clear Method, Err.Raise Method, On Error Statement

Syntax

Err.Clear

Description

Explicitly resets all the properties of the Err object after an error has been handled.

Rules at a Glance

You need to clear the Err object only if you need to reference its properties for another error within the same subroutine or before another On Error Resume Next statement within the same subroutine.

Example

On Error Resume Next i = oObjectOne.MyFunction(iVar) If Err.Number <> 0 Then MsgBox "The Error : " & Err.Description & vbCrLf _ & " was generated in " & Err.Source Err.Clear End If j = oObjectTwo.YourFunction(iVar) If Err.Number <> 0 Then MsgBox "The Error : " & Err.Description & vbCrLf _ & " was generated in " & Err.Source Err.Clear End If

Programming Tips and Gotchas

• Resetting the Err object explicitly using the Clear method is necessary when you use On Error Resume Next and test the value of Err.Number repeatedly. Unless you reset the Err object, you run the very real risk of catching the previously handled error, the details of which are still lurking in the Err object's properties.
• The Err object is automatically reset when an On Error Resume Next or On Error Goto 0 statement is executed.
• It is also possible to set the Err.Number property to 0 instead of calling up the Err.Clear method. However, this doesn't reset the remaining properties of the Err object.
• When testing the value of Err.Number, don't forget that OLE servers often return "negative" numbers. Actually internally they're not really negative, but are unsigned longs. However, since VBScript has no unsigned long data type, its value is represented as a negative number.

VBA/VBScript Differences

In VBA, the Err object is automatically reset by an Exit Function, Exit Sub, Exit Property, Resume, or On Error statement. In VBScript, it's reset only by an On Error statement.

See Also

Err Object, Err.Raise Method, On Error Statement

Data Type

String

Description

A read/write property containing a short string describing a runtime error.

Rules at a Glance

• When a runtime error occurs, the Description property is automatically assigned the standard description of the error.
• If there is no error (that is, if the value of Err.Number is 0), the value of the Description property is an empty string.
• For user-defined errors (that is, for errors that you define in your own scripts), you must assign a string expression to the Description property or the error won't have an accompanying textual message.
• You can override the standard description by assigning your own description to the Err object for both VBScript errors and user-defined errors.

Example

This example uses the description parameter of the Err.Raise method to return an error message when validating information from an HTML form. The web page containing the form is:

Data Type

Long

Description

A read/write property that either sets or returns a long integer value containing the context ID of the appropriate topic within a Help file.

Rules at a Glance

• The HelpContext property can be set either directly or by supplying the fifth parameter (the helpcontext parameter) to the Err.Raise method.
• HelpContext IDs are decided upon when writing and creating a Windows help file. Once the Help or HTML help file has been compiled, the IDs can't be changed. Each ID points to a separate Help topic.

Example

On Error Resume Next Dim i i = 8 MsgBox (i / 0) If Err.Number <> 0 Then Err.Description = "You are attempting to divide by zero." Err.Helpfile = "C:WindowshelpCustomApp.CHM" Err.HelpContext = 1000000 + Err.Number MsgBox Err.Description, vbMsgBoxHelpButton, "Error", Err.HelpFile, _ Err.HelpContext End If

Programming Tips and Gotchas

• You can display a topic from a help file by supplying values to the Err.HelpFile and Err.HelpContext properties, using the MsgBox function with the vbMsgBoxHelpButton constant and passing Err.HelpContext as the HelpContext argument (as shown in the previous example).
• If you supply a HelpContext ID that can't be found in a Windows Help file, the contents page for the Help file should be displayed. However, what actually happens is that a Windows Help error is generated, and a message box is displayed that informs the user to contact their vendor. If you supply a HelpContextID that cannot be found in an HTML Help file, VBScript displays an error message indicating that the Help file is either invalid or corrupted.
• In ASP applications, the HelpContext and HelpFile properties should not be used, since context-sensitive help on the server is undesirable. In Internet Explorer applications, particularly those that are accessible over the Internet, use of the HelpContext and HelpFile properties is not advisable, since you can't be certain that the appropriate help file is available on the client.

VBA/VBScript Differences

• At runtime, the HelpFile and HelpContext properties are automatically set when a VBA runtime error is encountered either because of an actual error or because of a call to the Err.Raise method. When a VBScript-defined error is encountered, on the other hand, these property values are not updated, since it may not make sense to supply help in a scripted environment.
• An invalid HelpContext ID to an HTML Help file causes VBA to display the file's Contents page. It causes VBScript to display an error message noting that the file either is not a help file or has been corrupted.

See Also

MsgBox Function, Err.HelpFile Property, Chapter 4

Data Type

String

Description

A read/write string property that contains the fully qualified path of a Windows Help or HTML Help file.

Rules at a Glance

The HelpFile property can be set either directly or by supplying the fourth parameter (the helpfile parameter) to the Err.Raise method.

Example

See Err.HelpContext.

Programming Tips and Gotchas

• Some objects you may use within your application have their own help files, which you can access using HelpFile to display highly focused help to your users.
• Remember that once the program encounters an On Error statement, all the properties of the Err object are reset; this includes HelpFile. You must therefore set the Err.HelpFile property each time your application needs to access the help file.
• In ASP applications, the HelpContext and HelpFile properties should not be used, since context-sensitive help on the server is undesirable. In IE applications, particularly those that are accessible over the Internet, use of the HelpContext and HelpFile properties is not advisable, since you can't be certain that the appropriate help file is available on the client.

VBA/VBScript Differences

Much of the utility of the HelpFile and HelpContext properties in VBA stems from the fact that, for errors recognized by the runtime engine, these values are automatically supplied to the Err object and can in turn be passed to the MsgBox function. In VBScript, however, these values are not updated automatically; if you want to use a help file or implement context-sensitive help, you have to supply these values yourself.

See Also

Err.HelpContext Property, Err.Number Property, Chapter 4

Data Type

Long

Description

A read/write property containing a type Long value that represents the error code for the last error generated.

Rules at a Glance

• When a runtime error is generated within the program, the error code is automatically assigned to Err.Number.
• The Number property is updated with an application-defined error whose code is passed as an argument to the Err.Raise method.
• When using the Err.Raise method in normal code, your user-defined error codes can't be greater than 65536 or less than 0. (See the final note in the "Programming Tips and Gotchas" section of the entry for the Err.Raise method.)
• VBScript uses error numbers in the range of 1-1058 as well as 32766-32767 and 32811 for its own trappable errors. In implementing a series of application-defined errors, your error handlers should either translate application errors into VBScript trappable errors or, preferably, assign a unique range to application-defined errors.
• If your code instantiates an ActiveX server, its error codes should be increased by the value of the VBScript intrinsic constant vbObjectError. When control returns to the local application after an error has been raised by the OLE server, the application can determine that the error originated in the OLE server and extract the error number with a line of code like the following:

  Dim lError If ((Err.Number And &HFF00) And vbObjectError) Then lError = Err.Number XOr vbObjectError

Syntax

Err.Raise number, [source], [description], _ [[helpfile], helpcontext]

number

Use: Required

Data Type: Long integer

A numeric identifier of the particular error.

source

Use: Optional

Data Type: String

The name of the object or application responsible for generating the error.

description

Use: Optional

Data Type: String

A useful description of the error.

helpfile

Use: Optional

Data Type: String

The fully qualified path of a Microsoft Windows Help or HTML Help file containing help or reference material about the error.

helpcontext

Use: Optional

Data Type: Long

The context ID within helpfile.

Description

Generates a runtime error.

Rules at a Glance

• To use the Raise method, you must specify an error number.
• If you supply any of the number, source, description, helpfile, and helpcontext arguments when you call the Err.Raise method, they are supplied as values to the Err object's Number, Source, Description, HelpFile, and HelpContext properties, respectively. Refer to the entries for the individual properties for full descriptions of and rules for each property.

Programming Tips and Gotchas

• The Raise method doesn't reinitialize the Err object prior to assigning the values you pass in as arguments. This can mean that if you Raise an error against an Err object that hasn't been cleared since the last error, any properties you don't specify values for still contain the values from the last error.
• As well as using Raise in a runtime scenario, you can put it to good use in the development stages of your program to test the viability of your error-handling routines under various circumstances.
• The fact that Err.Number accepts only numbers in the range 0-65536 may appear to be strange at first because the data type of the Error Number parameter in the Raise event is a Long; however, deep in the recesses of the Err object, the error code must be declared as an unsigned integer, which is a data type not supported by VBScript.
• When you raise an error in a scripted environment, it may not make sense to supply arguments to the helpfile and helpcontext parameters. They have no relevance to ASP applications; in IE applications, the help file itself may not be available on the host computer.

See Also

Err Object, Err.Clear Method, Err.HelpContext Property, Err.Number Property, Chapter 4

Data Type

String

Description

A read/write string property containing the name of the application or the object that has generated the error.

Rules at a Glance

• When a runtime error occurs in your code, the Source property is automatically assigned the string "Microsoft VBScript runtime error."
• If the error occurs in an ActiveX component instantiated by your application, the Source property usually contains the class name or the programmatic identifier of the component that raised the error.

Programming Tips and Gotchas

Knowing what type of error has occurred within a program is often of little use if you don't know where the error was generated. However, if you enhance the standard Source property by adding the name of the procedure, class, property, or method when you raise an error, your debugging time can be cut dramatically.

See Also

Err Object, Chapter 4

Syntax

Escape (string) string

string

Use: Optional

Data Type: String

The String to be encoded.

Return Value

An encoded Variant of Type string.

Description

Returns an encoded version of string.

Rules at a Glance

• All Unicode characters 255 and below are converted to %xx format except for A-Z, a-z, 0-9, and _*+-./@. For example, a space is replaced by %20.

Programming Tips and Gotchas

• The Escape function is not documented in the VBScript documentation.
• The function corresponds to the JScript escape method.
• You can use the Escape function to encode an HTML document so that a web browser displays the HTML source rather than interprets it. Alternatively, you can use the HTMLEncode method of the ASP Server object to achieve a similar (and more readable) result.
• You can use the Escape function to encode an HTTP query string before returning it to a web server.
• If string contains no spaces, punctuation characters, accented characters, or non-ASCII characters, the Escape function simply returns string unchanged.

Example

The following is a very simple routine that allows you to experiment with encoding character strings:

Option Explicit Dim sIn, sOut Do While True sIn = InputBox("Enter a string:", "UnescapedString", "") If sIn = " Then Exit Do sOut = Escape(sIn) msgbox "In: " & sIn & vbcrlf & _ Loop

For example, the string:

This is a level-1 head:

Hello!

returns the string:

This%20is%20a%20level-1%20head%3A%20%3CH1%3EHello%21%3C/H1%3E

VB/VBA Differences

This function is not supported in VBA.

See Also

Unescape Function

Syntax

[result = ]Eval(expression)

result

Use: Optional

Data Type: Any

A variable to hold the result of the Eval function.

expression

Use: Required

Data Type: String

The expression to be evaluated.

Return Value

Any

Description

Evaluates an expression and returns the results.

Rules at a Glance

• Eval follows the rules of precedence in evaluating expression.
• If an equals sign (=) occurs in expression, it is interpreted as a comparison operator rather than as an assignment operator. In this case, Eval returns True if the parts of expression are equal and False if they are not.

Example

In this example, the first result will always evaluate to False, since the variables are not equal, and the second will always evaluate to True, since Test1 is in fact less than Test2:

Dim Test1, Test2, Result Test1 = 4 Test2 = 5 Result = Eval("Test1 = Test2") MsgBox Result Result = Eval("Test1 < Test2") MsgBox Result Result = Eval("Test1 / Test2") MsgBox Result Result = Eval("Test1 - Test2") MsgBox Result

Programming Tips and Gotchas

You may wonder why you'd want to bother with Eval when you can do the same thing without it. For example:

lVar1 = 2 lVar2 = 3 lResult = lVar1 + lVar2

is the same as:

lVar1 = 2 lVar2 = 3 lResult = Eval(lVar1 + lVar2)

But the significance of Eval is that it evaluates expressions stored to strings. For example, the code:

Dim sExp, result, a, b, c a = 10 b = 20 c = 30 sExp = "a + b + c" result = eval(sExp)

returns 60. This means that you can build expressions and assign them to strings dynamically, then have them evaluated by passing them to the Eval function.

VBA/VBScript Differences

The Eval function is not supported in VBA.

See Also

Execute Statement

Syntax

Execute statement

statement

Use: Required

Data Type: String expression

A string expression containing one or more statements for execution.

Description

Executes one or more statements.

Rules at a Glance

• statement must evaluate to a string that contains one or more executable statements. An executable statement is any call to a user-defined procedure or function, or any intrinsic VBScript command.
• You can put multiple statements in the expression; separate them with colons.
• You can also separate the arguments with embedded line breaks.
• If statement includes an equal sign, it is interpreted as an assignment rather than an evaluation. For example, x = 3 assigns the value 3 to the variable x, rather than comparing the value of the variable x with 3.
• In VBScript, a program fragment such as x=3 can be interpreted as both an assignment statement (assigning the value 3 to the variable x) or as a comparison expression (for example If x = 3 Then...) The Execute and ExecuteGlobal statements always treat strings of the form a = b as assignment statements. Use Eval to interpret strings of this form as expressions.

Example

The following is a corrected version of an example appearing in online help that appears to do nothing. In this case, the Execute statement is used to execute a procedure named Proc2, and the entire source code for the procedure is also stored to the string S that is passed to the Execute statement:

dim S S = "Proc2 : " S = S & "Sub Proc2 : " S = S & "Dim x : " S = S & "x = 10 : " S = S & "MsgBox X : " S = S & "End Sub " Execute S

But since the Execute statement only defines Proc2 as a procedure that's visible within the script block but does not execute it, we must also execute Proc2 as follows:

dim S S = "Sub Proc2 : " S = S & "Dim x : " S = S & "x = 10 : " S = S & "MsgBox X : " S = S & "End Sub " Execute S Proc2

Programming Tips and Gotchas

• The Execute statement does for executable statements what the Eval function does for expressions: it allows you to dynamically (i.e., at runtime) assign code to a string and execute it by passing it to the Execute statement.
• Be careful with this technique, since it can lead to very hard-to-read code.

VBA/VBScript Differences

The Execute statement is not supported by VBA. However, it is not unlike the CallByName function, which appeared for the first time in VBA 6.0. CallByName allows you to execute a routine whose name you store to a variable; hence, the name of the routine need not be determined at design time.

See Also

Eval Function, ExecuteGlobal Statement

Syntax

ExecuteGlobal statement

statement

Use: Required

Data Type: String

A string expression containing zero or more statements for execution.

Description

Executes zero or more statements in the global namespace of a script.

Rules at a Glance

• statement must evaluate to a string containing one or more executable statements. An executable statement is any call to a user-defined procedure or function, or to an intrinsic VBScript command.
• If statement contains multiple statements or lines of code, you can separate them with colons.
• You can also separate statements or lines of code with embedded line breaks (i.e., vbCrLf).
• If statement includes an equal sign, it is interpreted as an assignment rather than an evaluation. For example, x = 3 assigns the value 3 to the variable x, rather than comparing the value of the variable x with 3.
• Code created by ExecuteGlobal is executed in the script's global namespace. The global namespace is the following:
  • In ASP and IE, code within a tag, but outside of individual functions or procedures.
  • In Outlook, form-level code outside of individual event handlers, functions, or procedures.
  • In WSH, code outside of individual functions and procedures.

Example

The example WSH script illustrates the difference between Execute and ExecuteGlobal. Each is called within the MainProc procedure to define a subroutine. Execute creates a procedure named Proc2; however, it is only visible if called from MainProc. ExecuteGlobal creates a procedure named Proc1 which is globally available throughout the script.

Option Explicit Dim x x = 10 MainProc EndProc 'Proc2 ' procedure not visible Sub MainProc Dim x x = 20 ExecuteGlobal "Sub Proc1 : MsgBox x : End Sub" Execute "Sub Proc2 : MsgBox x : End Sub" Proc2 ' only callable from MainProc Proc1 End Sub Sub EndProc Proc1 End Sub

Note that both Proc1 and Proc2 access the public variable x, even though a local variable x was visible in MainProc when the Execute statement created the Proc2 procedure. If we wanted to pass the local variable x to our routine, we'd have to redefine Proc2 to accept it as a parameter, as follows:

Execute "Sub Proc2(ByVal a) : MsgBox a : End Sub"

Programming Tips and Gotchas

• While the Execute statement executes code that inherits the scope of the procedure in which it was declared, ExecuteGlobal always executes code in the script's global scope. This has two major implications:
  • After the ExecuteGlobal statement runs, functions, procedures, or classes defined using ExecuteGlobal can be accessed from anywhere within the script.
  • Any variables accessed from code defined by the ExecuteGlobal statement must have global scope. In other words, when using ExecuteGlobal in a local scope, ExecuteGlobal will not see local variables.

VBA/VBScript Differences

The ExecuteGlobal statement is not supported by VBA.

See Also

Eval Function, Execute Statement

Syntax

Exit Do Exit For Exit Function Exit Property Exit Sub

Description

Prematurely exits a block of code.

Rules at a Glance

Exit Do

Exits a Do...Loop statement. If the current Do...Loop is within a nested Do...Loop, execution continues with the next Loop statement wrapped around the current one. If, however, the Do...Loop is standalone, program execution continues with the first line of code after the Loop statement.

Exit For

Exits a For...Next loop. If the current For...Next is within a nested For...Next loop, execution continues with the next Next statement wrapped around the current one. If, however, the For...Next loop is standalone, program execution continues with the first line of code after the Next statement.

Exit Function

Exits the current function.

Exit Property

Exits the current property procedure.

Exit Sub

Exits the current sub procedure.

Programming Tips and Gotchas

• Traditional programming theory recommends one entry point and one exit point for each procedure. However, you can improve the readability of long routines by using the Exit statement. Using Exit Sub can save having to wrap almost an entire subroutine (which could be tens of lines long) within an If...Then statement.

  With Exit Sub:

  Sub MyTestSub(iNumber) If iNumber = 10 Then Exit Sub End If ...'code End Sub

  Without Exit Sub:

  Sub MyTestSub(iNumber) If iNumber <> 10 Then ...'code End If End Sub

• In the case of the Exit Function, Exit Property, and Exit Sub statements, the point in the program to which program flow returns depends on the caller of the property, function, or sub, respectively, and not on the property, function, or sub itself.

See Also

Do . . . Loop Statement, For . . . Next Statement, For Each . . . Next Statement, Function Statement, Property Get Statement, Property Let Statement, Property Set Statement, Sub Statement

Syntax

Exp(number)

number

Use: Required

Data Type: Number

Any valid numeric expression.

Return Value

A Double representing the antilogarithm of number.

Description

Returns the antilogarithm of a number; the antilogarithm is the base of natural logarithms, e (whose value is the constant 2.7182818), raised to a power.

Rules at a Glance

The maximum value for number is 709.782712893.

Programming Tips and Gotchas

Exp is the inverse of the Log function.

See Also

Log Function

Createable

No

Returned by

Files.Item property

FileSystemObject.GetFile method

Library

Microsoft Scripting Runtime

Description

The File object represents a disk file that can be a file of any type and allows you to interrogate the properties of the file and to move upward in the filesystem hierarchy to interrogate the system on which the file resides. The process of instantiating a File objectfor example, assigning a reference from the File object's Item property to a local object variabledoesn't open the file. An open file is represented in the File System object model by a TextStream object, which can be generated by the File object's OpenAsTextStream method.

There are several methods of retrieving a reference to an existing File object:

• If you want to work with a particular file, you can retrieve a reference to it directly by calling the GetFile method of the FileSystemObject object. For example:

  Dim oFS, oFile Set oFS = CreateObject("Scripting.FileSystemObject") Set oFile = oFS.GetFile("C:DocumentsMyReport.doc")

  allows you to retrieve a reference to a File object representing the MyReport.doc file without having to use the File System object model to navigate the filesystem.

• If you want to work with a file as a member of a folder or of a set of files, you can retrieve a reference to a File object that represents it from the Item property of the Files collection. (The Files collection is returned by the Files property of a Folder object.) The following code fragment, for instance, retrieves a reference to a file named MyReport.doc that is a member of the Documents folder:

  Dim oFS, oFile Set oFS = CreateObject("Scripting.FileSystemObject") Set oFile = oFS.Drives("C").RootFolder.SubFolders("Documents"). _ Files("MyReport.doc")

  Note that a File object represents an existing file; you cannot create a File object representing a new file. (You can, however, create a new TextStream object that represents a new text file by calling the Folder object's CreateTextFile method.)

Properties

Attributes

Data Type: Long

Sets or returns the file's attributes. The value of the property represents a bit mask consisting of six flags in the case of a File object, each of which represents a particular file attribute. These values are:

All flags are read/write except for the alias and compressed flags. A value of 0 (normal) indicates that no flags are set.

The attribute flags are represented by the constants of the FileAttribute enumeration in the Scripting Runtime library. You can access them from an ASP page by including the METADATA tag, or from a WSH script by including the following line in a Windows Script Host (.wsf ) file:

You can also add Const statements that define the attribute constants.

DateCreated

Data Type: Date

The date and time the file was created; the property is read-only.

DateLastAccessed

Data Type: Date

The date and time the file was last accessed. Whether the property includes the date and time or only the date depends on the operating system; Windows 95, Windows 98, and Windows ME, for instance, only return the date, while Windows NT, Windows 2000, and Windows XP return the date and time. The property is read-only.

DateLastModified

Data Type: Date

The date and time the file was last modified; the property is read-only.

Drive

Data Type: Drive object

Returns a Drive object representing the drive on which the file resides; the property is read-only.

Name

Data Type: String

The name of the file. Modifying the value of a File object's Name property renames the file.

ParentFolder

Data Type: Folder object

Returns a Folder object representing the folder in which the file resides; the property is read-only.

Path

Data Type: String

Returns the full path to the file from the current machine, including drive letter or network path/share name; the property is read-only. Path is the default property of the File object.

ShortName

Data Type: String

Returns a DOS 8.3 filename.

ShortPath

Data Type: String

Returns a DOS 8.3 folder name. The property is read-only.

Size

Data Type: Long

Returns the size of the file in bytes. The property is read-only.

The Size property holds a long integer, meaning that it accurately reports file sizes from 0 to 2,147,483,648 bytes. In previous versions of VBScript, the property failed to accurately report the size of large files of over 2 GB.

Type

Data Type: String

Returns a string containing the registered type description. This is the type string displayed for the file in Windows Explorer. If a file doesn't have an extension, the type is simply "File." When a file's type isn't registered, the type appears as the extension and "File." The property is read-only.

Methods

Copy

Move

Delete

OpenAsTextStream

Syntax

oFileObj.Copy Destination [, OverwriteFiles]

oFileObj

Use: Required

Data Type: File object

A File object.

Destination

Use: Required

Data Type: String

The path and, optionally, the filename of the copied file.

OverwriteFiles

Use: Optional

Data Type: Boolean

True if the copy operation can overwrite an existing file, False otherwise.

Description

Copies the file represented by oFileObj to another location.

Rules at a Glance

Wildcard characters can't be used in Destination.

Programming Tips and Gotchas

• If the Destination path is set to read-only, the Copy method fails regardless of the OverwriteFiles setting and generates a "Permission denied" error.
• If OverwriteFiles is False and the file already exists in Destination, runtime error 58, "File Already Exists," is generated.
• If the user has adequate rights, Destination can be a network path or share name. For example:

  MyFile.Copy "\NTSERV1d$RootTwo" MyFile.Copy "\NTSERV1RootTest"

See Also

FileSystemObject.CopyFile Method

Syntax

oFileObj.Delete [Force]

oFileObj

Use: Required

Data Type: File object

A File object.

Force

Use: Optional

Data Type: Boolean

If set to True, ignores the file's read-only flag (if it's on), and deletes the file.

Description

Removes the current file.

Rules at a Glance

• The Delete method deletes a file permanently; it does not move it to the Recycle Bin.
• If the file is open, the method fails with a "Permission Denied" error.
• The default setting for Force is False.
• If Force is set to False, and the file is read-only, the method will fail.

Programming Tips and Gotchas

• Unlike the FileSystemObject object's DeleteFile method, which accepts wildcard characters in the path parameter and can therefore delete multiple files, the Delete method deletes only the single file represented by oFileObj.
• As a result of the Delete method, the Files collection object containing oFileObj is automatically updated, the deleted file is removed from the collection, and the collection count is reduced by one. You shouldn't try to access the deleted file object again; you should set oFileObj to Nothing.

See Also

FileSystemObject.DeleteFile Method

Syntax

oFileObj.Move destination

oFileObj

Use: Required

Data Type: File object

A File object.

destination

Use: Required

Data Type: String

The path to the location where the file is to be moved.

Description

Moves a file from one folder to another.

Rules at a Glance

• The file represented by oFileObj must not be open or an error occurs.
• Wildcard characters can't be used in Destination.
• Destination can be either an absolute or a relative path.

Programming Tips and Gotchas

• If a fatal system error occurs during the execution of this method (like a power failure), the worst that can happen is that the file is copied to the destination but not removed from the source. There are no rollback capabilities built into the File.Move method; however, because the copy part of this two-stage process is executed first, the file can't be lost.
• If a folder or a file by the same name already exists in destination, the method generates runtime error 58, "File exists." To prevent this, you can use the FileSystemObject's FileExists and GetAbsolutePath methods prior to calling the Move method.
• Unlike the FileSystemObject's MoveFile method, which accepts wildcard characters in the path parameter and can therefore move multiple files, the Move method moves only the single file represented by oFileObj.
• As a result of the Move method, the Files collection object originally containing oFileObj is automatically updated, the file is removed from it, and the collection count is reduced by one. You shouldn't try to access the moved file object again in the same Folders collection object.
• oObj, the File object reference, remains valid after the file has been moved. Its relevant properties (the Drive, ParentFolder, Path, and ShortPath properties, for example) are all updated to reflect the file's new path after the move.
• If the user has rights, destination can be a network path or share name:

  oFile.Move "\NTSERV1d$RootTwomyfile.doc"

See Also

FileSystemObject.MoveFile Method

Syntax

oFileObj.OpenAsTextStream ([IOMode[, Format]])

oFileObj

Use: Required

Data Type: File object

A File object.

IOMode

Use: Optional

Data Type: Long

A constant specifying the purpose for opening the file.

Format

Use: Optional

Data Type: Long

A constant specifying ASCII or Unicode format.

Return Value

A TextStream object.

Description

Opens the referenced text file for reading or writing.

Rules at a Glance

• IOMode can be one of the following values:

  Constant	Value	Description
  ForAppending	8	Opens the file in append mode; that is, the current contents of the file are protected, and new data written to the file is placed at the end of the file.
  ForReading	1	Opens the file for reading; you can't write to a file that has been opened for reading.
  ForWriting	2	Opens the file for writing; all previous file content is overwritten by new data.

  The default value is 1, ForReading.

• The Scripting Runtime type library defines constants of the IOMode enumeration that can be used in place of their numeric equivalents for the IOMode argument. You can use them in your scripts in either of two ways. You can define the constants yourself by adding the following code to your script:

  Const ForReading = 1 Const ForWriting = 2 Const ForAppending = 8

  You can also include the ASP METADATA tag in global.asa or include the following line in a Windows Script Host (.wsf ) file in order to access the constants from the Scripting Runtime type library:

   

• Unicode can be one of the following values:

  Constant	Value	Description
  TristateUseDefault	-2	Open as System default
  TristateTrue	-1	Open as Unicode
  TristateFalse	0	Open as ASCII

  The default value is 0 or ASCII (TristateFalse).

• The Scripting Runtime type library defines constants of the Tristate enumeration that can be used in place of their numeric equivalents for the Unicode argument. You can use them in your scripts in either of two ways. You can define the constants yourself by adding the following code to your script:

  Const TristateFalse = 0 Const TristateTrue = -1 Const TristateUseDefault = -2

  You can also include the ASP METADATA tag in global.asa or include the following line in a Windows Script Host (.wsf ) file in order to access the constants from the Scripting Runtime type library:

   

• If another process has opened the file, the method fails with a "Permission Denied" error.
• The TextStream object is so named for a very good reason: it is designed to work with text files rather than binary files. Although it is possible to use the OpenAs TextStream method to open a binary file, an enormous number of subtle bugs may crop up when you manipulate binary data as text. Because of this, if you want to work with binary files, you should use some technology (like the ADO binary file object) or programming language (like C/C++) that's more amenable to processing binary files.

See Also

FileSystemObject.OpenTextFile Method , TextStream Object

Library to Reference

Microsoft Scripting Runtime (SCRRUN.DLL )

Description

The FileSystemObject is a boon for all developers using any variety of Visual Basic (VBScript, VBA, and VB). It simplifies the task of dealing with any type of file input and output and for dealing with the system file structure itself. Rather than resorting to complex calls to the Win32 API (or, in the case of VBScript, not being able to access the filesystem altogether), this object allows the developer to easily handle files and navigate the underlying directory structures. This is especially useful for those developers or administrators who are creating scripts that are used for system administration or maintenance.

The File System object model is available to both VB and VBA developers, but it is only intrinsically part of the VBScript scripting language. The File System object model allows you to interrogate, create, delete, and manipulate folders and text files.

To access the File System object model, you must first create an instance of the FileSystemObject object, the only externally createable object in the model. From there, you can navigate through the object model, as shown in the object hierarchy diagram in Figure 10-1. The FileSystemObject object can be instantiated with a code fragment like the following:

Dim oFS Set oFS = CreateObject("Scripting.FileSystemObject")

Figure 10-1. The File System object model

It can also be instantiated using the object creation method of the host object model.

See Also

File Object, Files Collection Object, FileSystemObject Object, Folder Object, Folders Collection Object, TextStream Object

Createable

No

Returned by

Folder.Files property

Library

Microsoft Scripting Runtime

Description

The Files collection object is one of the objects in the File System object model; for an overview of the model, including the library reference needed to access it, see the "File System Object Model" entry.

The Files collection object is a container for File objects that is returned by the Files property of any Folder object. All files contained in the folder are included in the Files collection object. You can obtain a reference to a Files collection object using a code fragment like the following:

Dim oFS, oFiles Set oFS = CreateObject("Scripting.FileSystemObject") Set oFiles = oFS.Drives("C:").RootFolder. _ SubFolders("Windows").Files

This code returns the Files collection for the Windows folder.

You can obtain a reference to an individual File object using the Files collection object's Item property; this takes the exact filename, including the file extension, as an argument. To iterate through the collection, you can use the For Each...Next statement. For details, see the entry for the File Object.

The Files collection object is read-only. Consequently, it supports only the following two properties.

Properties

Count

Data Type: Long

The number of File objects in the collection.

Item

Data Type: File object

Takes the filename (including the file extension) as a parameter and returns the File object representing the file with that name. Individual File objects can't be accessed by their ordinal position in the collection. Item is the Files collection object's default property. The code fragment shown next uses the Item property to retrieve the autoexec.bat File object.

Dim ofsFiles Dim ofsFile Set ofsFileSys = CreateObject("Scripting.FileSystemObject") Set ofsFiles = ofsFileSys.Drives("C:").RootFolder.Files Set ofsFile = ofsFiles.Item("autoexec.bat") MsgBox ofsFile.DateCreated & vbCrLf & _ ofsFile.DateLastModified & vbCrLf & _ ofsFile.DateLastAccessed

See Also

File System Object Model, File Object

Createable

Yes

Library

Microsoft Scripting Runtime

Description

The FileSystemObject object is at the top level of the File System object model and is the only externally createable object in the hierarchy; that is, it's the only object you can create using the CreateObject function or the host object model's object creation facilities. For example, the following code instantiates a FileSystemObject object named oFS:

Dim oFS Set oFS = CreateObject("Scripting.FileSystemObject")

The FileSystemObject object represents the host computer's filesystem as a whole. Its members allow you to begin navigation into the filesystem, as well as to access a variety of common filesystem services. For information about the FileSystemObject object's properties and methods, see the entry for each property and method.

For an overview of the file system object model, see the "File System Object Model" entry.

Properties

Drives (returns a Drives collection object).

Methods

Syntax

oFileSysObj.BuildPath(Path, Name)

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

Path

Use: Required

Data Type: String

A drive and/or folder path.

Name

Use: Required

Data Type: String

The folder or file path to append to path.

Return Value

A String.

Description

Creates a single string representing a path and filename or simply a path by concatenating the path parameter with the folder or filename, adding, where required, the correct path separator for the host system.

Rules at a Glance

• Path can be an absolute or relative path and doesn't have to include the drive name.
• Neither Path nor Name has to currently exist.

Programming Tips and Gotchas

• BuildPath is really a string concatenation method rather than a filesystem method; it does not check the validity of the new folder or filename. If you intend that the method's return value be a path, you should check it by passing it to the FolderExists method; if you intend that the method's return value be a path and filename, you should verify it by passing it to the FileExists method.
• The only advantage to using the BuildPath function as opposed to concatenating two strings manually is that the function selects the correct path separator.

Syntax

oFileSysObj.CopyFile Source, Destination [, OverwriteFiles]

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

Source

Use: Required

Data Type: String

The path and name of the file to be copied. The path can be relative or absolute, and the filename (but not the path) can contain wildcard characters.

Destination

Use: Required

Data Type: String

The path and optionally the filename of the copy to make. Destination cannot include wildcard characters.

OverwriteFiles

Use: Optional

Data Type: Boolean

Flag indicating whether an existing file is to be overwritten (True) or not (False). It's default value is True; files of the same names in the target folder will be overwritten.

Description

Copies a file or files from one folder to another.

Rules at a Glance

• The default value for OverwriteFiles is True.
• The source path can be relative or absolute.
• The source filename can contain wildcard characters; the source path can't.
• Wildcard characters can't be included in Destination.

Programming Tips and Gotchas

• If the destination path or file is read-only, the CopyFile method fails, regardless of the value of OverwriteFiles and generates runtime error 70, "Permission Denied."
• If OverwriteFiles is set to False and the file exists in Destination, a trappable errorruntime error 58, "File Already Exists"is generated.
• If an error occurs while copying more than one file, the CopyFile method exits immediately, thereby leaving the rest of the files uncopied. There is no rollback facility to undo copies made prior to the error.
• Both Source and Destination can include relative pathsthat is, paths that are relative to the current folder. The current folder is the folder in which the script is stored, the folder specified in the "Start in" text box of a shortcut, or the folder from which the script is launched from the console mode. The symbol to indicate the parent of the current folder is (..); the symbol to indicate the current folder is (.).
• Source must include an explicit filename. For instance, under DOS, you could copy all of the files in a directory with a command in the format of:

  Copy c:data c:ckup

  or:

  Copy c:data c:ckup

  which would copy all the files from the C:data directory to C:ckup. The Source argument cannot take any of these forms; instead, you must include some filename component. For example, to copy all of the files from C:data, the CopyFile statement would take the form:

  oFS.CopyFile "C:data*.*", "C:ckup"

• To specify multiple files, the Source argument can include the * and ? wildcard characters. Both are legacies from DOS. * matches any characters in a filename that follow those characters that are explicitly specified. For instance, a Source argument of File* matches File01.txt, File001.txt, and File.txt, since all three filenames begin with the string "File"; the remainder of the filename is ignored. ? is a wildcard that ignores a single character in a filename comparison. For instance, a Source argument of Fil?01.txt copies File01.txt and Fil_01.txt, since the fourth character of the filename is ignored in the comparison.
• If you want the source and the destination directories to be the same, you can copy only a single file at a time, since Destination does not accept wildcard characters.
• If the path specified in Destination does not exist, the method does not create it. Instead, it generates runtime error 76, "Path not found."
• If the user has adequate rights, the source or destination can be a network path or share name. For example:

  CopyFile "c:Rootone*.*", "\NTSERV1d$RootTwo" CopyFile "\NTSERV1RootTest est.txt", "c:RootOne"

• The CopyFile method copies a file or files stored in a particular folder. If the folder itself has subfolders containing files, the method doesn't copy these; use the CopyFolder method.
• The CopyFile method differs from the Copy method of the File object in two ways:
  • You can copy any file anywhere in a filesystem without having to first instantiate it as a File object.
  • You can copy multiple files in a single operation, rather than copying only the file represented by the File object.

See Also

FileSystemObject.CopyFolder Method, Folder.Copy Method

Syntax

oFileSysObj.CopyFolder Source, Destination [, OverwriteFiles]

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

Source

Use: Required

Data Type: String

The path and name of the folder to be copied from.

Destination

Use: Required

Data Type: String

The path for the folder where the copy is to be made.

OverwriteFiles

Use: Optional

Data Type: Boolean

Flag indicating whether existing files are to be overwritten (True) or not (False). Its default value is True; files of the same name will be overwritten if they already exist in Destination.

Description

Copies the contents of one or more folders, including their subfolders, to another location.

Rules at a Glance

• Source must end with either a wildcard character or no path separator. If it ends with a wildcard character, all matching subfolders and their contents will be copied. Wildcard characters can be used in Source only for the last component.
• Wildcard characters can't be used in Destination.
• All subfolders and files contained within the source folder are copied to Destination unless disallowed by the wildcard characters. That is, the CopyFolder method is recursive.
• If Destination ends with a path separator or Source ends with a wildcard, CopyFolder assumes that the folder stated in Source exists in Destination or should otherwise be created. For example, given the following folder structure:

  C: Rootone SubFolder1 SubFolder2 RootTwo

  The code FileSys.CopyFolder "c:Rootone*", "C:RootTwo" produces this folder structure:

  C: Rootone SubFolder1 SubFolder2 RootTwo SubFolder1 SubFolder2

  The code FileSys.CopyFolder "c:Rootone", "C:RootTwo" produces this folder structure:

  C: Rootone SubFolder1 SubFolder2 RootTwo Rootone SubFolder1 SubFolder2

Programming Tips and Gotchas

• If the destination path or any of the files contained in Destination are set to read-only, the CopyFolder method fails, regardless of the value of OverwriteFiles.
• If OverwriteFiles is set to False, and the source folder or any of the files contained in Source exists in Destination, runtime error 58, "File Already Exists," is generated.
• If an error occurs while copying more than one file or folder, the CopyFolder function exits immediately, leaving the rest of the folders or files uncopied. There is no rollback facility to undo the copies prior to the error.
• If the user has adequate rights, both the source or destination can be a network path or share name. For example:

  CopyFolder "c:Rootone", "\NTSERV1d$RootTwo" CopyFolder "\NTSERV1RootTest", "c:RootOne"

See Also

Folder.Copy Method

Syntax

oFileSysObj.CreateFolder(Path)

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

Path

Use: Required

Data Type: String

An expression that returns the name of the new folder to create.

Return Value

A Folder object.

Description

Creates a single new folder in the path specified and returns its Folder object.

Rules at a Glance

• Wildcard characters aren't allowed in Path.
• Path can be a relative or absolute path.
• If no path is specified in Path, the current drive and directory are used.
• If the last folder in Path already exists, the method generates runtime error, "File already exists."

Programming Tips and Gotchas

• If Path is read-only, the CreateFolder method fails.
• If Path already exists, the method generates runtime error 58, "File already exists."
• If the user has adequate rights, Path can be a network path or share name. For example:

  CreateFolder "\NTSERV1d$RootTwo ewFolder" CreateFolder "\NTSERV1RootTest ewFolder"

• You must use the Set statement to assign the Folder object to an object variable. For example:

  Dim oFileSys Dim oFolder Set oFileSys = CreateObject("Scripting.FileSystemObject") Set oFolder = oFileSys.CreateFolder("MyFolder")

See Also

Folders.Add Method

Syntax

oFileSysObj.CreateTextFile Filename [, Overwrite[, Unicode]])

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

Filename

Use: Required

Data Type: String

Any valid filename, along with an optional path.

Overwrite

Use: Optional

Data Type: Boolean

Flag indicating if an existing file of the same name should be overwritten.

Unicode

Use: Optional

Variant Sub Type: Boolean

Flag indicating if Filename is to be written in Unicode or ASCII.

Return Value

A TextStream object.

Description

Creates a new file and returns its TextStream object.

Rules at a Glance

• Wildcard characters aren't allowed in Filename.
• Filename can be a relative or absolute path.
• If no path is specified in Filename, the script's current drive and directory are used. If no drive is specified in Filename, the script's current drive is used.
• If the path specified in Filename doesn't exist, the method fails. To prevent this error, you can use the FileSystemObject object's FolderExists method to insure that the path is valid.
• The default value for Overwrite is False.
• If Unicode is set to True, the file is created in Unicode; otherwise, it's created as an ASCII text file. The default value for Unicode is False.

Programming Tips and Gotchas

• The newly created text file is automatically opened only for writing. If you subsequently wish to read from the file, you must first close it and reopen it in read mode.
• If the path referred to in Filename is set to read-only, the CreateTextFile method fails regardless of the value of Overwrite.
• If the user has adequate rights, Filename can contain a network path or share name. For example:

  FileSys.CreateTextFile "\NTSERV1RootTestmyFile.doc"

• You must use the Set statement to assign the TextStream object to your local object variable.
• The CreateTextFile method of the Folder object is identical in operation to that of the FileSystemObject object.

See Also

Folder.CreateTextFile Method, TextStream Object

Syntax

oFileSysObj.DeleteFile FileSpec [, Force]

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

FileSpec

Use: Required

Data Type: String

The name and path of the file or files to delete.

Force

Use: Optional

Data Type: Boolean

If set to True, the read-only flag on a file is ignored and the file deleted. Its default value is False; read-only files will not be deleted.

Description

Permanently removes a given file or files.

Rules at a Glance

• FileSpec can contain wildcard characters as the final path component, which allows multiple files to be deleted.
• FileSpec can be a relative or absolute path.
• If any of the files specified for deletion are open, the method fails with a "Permission Denied" error.
• If the specified file or files can't be found, the method fails.
• If only a filename is used in FileSpec, the application's current drive and directory is assumed.

Programming Tips and Gotchas

• If FileSpec specifies a path not ending in a path separator, the method will fail without generating an error. If FileSpec specifies a path that ends in a path separator, the method fails and generates runtime error 53, "File not found."
• The DeleteFile method differs from the Delete method of the File object in several respects. First, it allows you to delete a file directly, without first obtaining an object reference to it. Second, by supporting wildcards, it allows you to delete multiple files at once.
• If an error occurs while deleting more than one file, the DeleteFile method exits immediately, thereby leaving the rest of the files undeleted. There is also no rollback facility to undo deletions prior to the error.
• If the user has adequate rights, the source or destination can be a network path or share name. For example:

  DeleteFile "\NTSERV1RootTestmyFile.doc"

• DeleteFile permanently deletes files; it doesn't move them to the Recycle Bin.

See Also

Folder.Delete Method

Syntax

oFileSysObj.DeleteFolder FileSpec[, Force]

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

FileSpec

Use: Required

Data Type: String

The name and path of the folders to delete.

Force

Use: Optional

Data Type: Boolean

If set to True, the read-only flag on a file is ignored and the file deleted. By default, its value is False; read-only files will not be deleted.

Description

Removes a given folder and all its files and subfolders.

Rules at a Glance

• FileSpec can contain wildcard characters as the final path component, which allows multiple folders that meet the file specification to be deleted.
• FileSpec can't end with a path separator.
• FileSpec can be a relative or absolute path.
• If any of the files within the specified folders are open, the method fails with a "Permission Denied" error.
• The DeleteFolder method deletes all contents of the given folder, including other folders and their contents.
• If the specified folder can't be found, the method fails.

Programming Tips and Gotchas

• If an error occurs while deleting more than one file or folder, the DeleteFolder method exits immediately, thereby leaving the rest of the folders or files undeleted. There is also no rollback facility to undo the deletions prior to the error.
• DeleteFolder permanently deletes folders and their contents; it doesn't move them to the Recycle Bin.
• The DeleteFolder method differs from the Delete method of the Folder object in two respects. First, it allows you to directly delete a folder, without first having to navigate to it or otherwise obtain an object reference to it. Second, it allows you to delete multiple folders, whereas the Delete method allows you to delete only the folder represented by the Folder object.
• If the user has adequate rights, the source or destination can be a network path or share name. For example:

FileSys.DeleteFolder "\NTSERV1d$RootTwo"

See Also

Folder.Delete Method

Syntax

oFileSysObj.DriveExists (DriveSpec)

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

DriveSpec

Use: Required

Data Type: String

A path or drive letter.

Return Value

Boolean (True or False).

Description

Determines whether a given drive (of any type) exists on the local machine or on the network. The method returns True if the drive exists or is connected to the machine, and returns False if not.

Rules at a Glance

• If DriveSpec is a Windows drive letter, it doesn't have to include the colon. For example, "C" works just as well as "C:".
• Returns True if the drive exists or is connected to the machine, and returns False if not.

Programming Tips and Gotchas

• DriveExists doesn't note the current state of removable media drives; for this, you must use the IsReady property of the Drive object representing the given drive.
• If the user has adequate rights, DriveSpec can be a network path or share name. For example:

  If ofs.DriveExists("\NTSERV1d$") Then

• This method is ideal for detecting any current drive around the network before calling a function in a remote ActiveX server located on that drive.

Syntax

oFileSysObj.Drives

oFileSysObj

Use: Required

Variant Type: FileSystemObject object

A FileSystemObject object.

Return Value

Drives collection object.

Description

Drives is a read-only property that returns the Drives collection; each member of the collection is a Drive object, representing a single drive available on the system. Using the collection object returned by the Drives property, you can iterate all the drives on the system using a For...Next loop, or you can retrieve an individual Drive object, which represents one drive on the system, by using the Drives collection's Item method.

See Also

Drive Object, Drives Collection Object

Syntax

oFileSysObj.FileExists(FileSpec)

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

FileSpec

Use: Required

Data Type: String

A complete path to the file.

Return Value

Boolean (True or False).

Description

Determines if a given file exists.

Rules at a Glance

• Returns True if the file exists or is connected to the machine, and returns False if not.
• FileSpec can't contain wildcard characters.
• FileSpec can include either an absolute or a relative paththat is, a path that is relative to the current folder. The current folder is the folder in which the script is running, or the folder specified in the "Start in" text box of the shortcut used to launch the script. The symbol to indicate the parent of the current folder is (..); the symbol to indicate the current folder is (.). If FileSpec does not include a path, the current folder is used.

Programming Tips and Gotchas

If the user has adequate rights, FileSpec can be a network path or share name. For example:

If ofs.FileExists("\TestPathTest.txt") Then

See Also

FileSystemObject.FolderExists Method

Syntax

oFileSysObj.FolderExists(FolderSpec)

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

FolderSpec

Use: Required

Data Type: String

The complete path to the folder.

Return Value

Boolean (True or False).

Description

Determines whether a given folder exists; the method returns True if the Folder exists, and returns False if not.

Rules at a Glance

• FolderSpec can't contain wildcard characters.
• FolderSpec cannot include a filename as well as a path. In other words, the entire FolderSpec string can only include drive and path information.
• If FolderSpec does not include a drive specification, the current drive is assumed.
• FolderSpec is interpreted as an absolute path if it begins with a drive name and a path separator, and it is interpreted as an absolute path on the current drive if it begins with a path separator. Otherwise, it is interpreted as a relative path.

Programming Tips and Gotchas

• If the user has adequate rights, FolderSpec can be a network path or share name. For example:

  If FileSys.FolderExists("\NTSERV1d$TestPath") Then

• Among its string manipulation methods, the Scripting Runtime library lacks one that will extract a complete path from a path and filename. The example provides the GetCompletePath function to perform this useful task, as well as to illustrate the use of the FolderExists method.

Example

Function GetCompletePath(sPath) Dim oFS Dim sFileName, sPathName Dim lPos Set oFS = CreateObject("Scripting.FileSystemObject") ' Check if no backslash is present If Instr(1, sPath, "") = 0 Then ' Determine if string is a filename If oFS.FileExists(sPath) Then ' Return current folder GetCompletePath = oFS.GetAbsolutePathName(".") Else ' Check if folder exists If oFS.FolderExists("" & sPath) Then GetCompletePath = sPath Else ' Raise "Path not found" error Err.Raise 76 End If End If ' At least one backslash is present Else ' check if last character is a backslash If Right(sPath, 1) = "" Then If oFS.FolderExists(sPath) Then GetCompletePath = sPath Else Err.Raise 76 End If ' Extract prospective filename from path Else ' Check if the string includes a filename lPos = InstrRev(sPath, "") sFileName = Mid(sPath, lPos + 1) If oFS.FileExists(sPath) Then GetCompletePath = Left(sPath, lPos) Else ' Generate file not found error Err.Raise 53 End If End If End If End Function

See Also

FileSystemObject.DriveExists Method, FileSystemObject.FileExists Method

Syntax

oFileSysObj.GetAbsolutePathName(Path)

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

Path

Use: Required

Data Type: String

A path specifier.

Return Value

A string containing the absolute path of a given path specifier.

Description

Converts a relative path to a fully qualified path, including the drive letter.

Rules at a Glance

• (.) returns the drive letter and complete path of the current folder.
• (..) returns the drive letter and path of the parent of the current folder.
• If Path is simply a filename without a path, the method concatenates the complete path to the current directory with the filename. For example, if the current folder is C:DocumentsMyScripts, then the method call:

  sFileName = GetAbsolutePathName("MyFile.txt")

  produces the string "C:DocumentsMyScriptsMyFile.txt".

• All relative pathnames are assumed to originate at the current folder. This means, for example, that (.) returns the drive letter and complete path of the current folder, and that (..) returns the drive letter and path of the parent of the current folder.
• If a drive isn't explicitly provided as part of Path, it's assumed to be the current drive.
• Wildcard characters can be included in Path at any point.

Programming Tips and Gotchas

• An absolute path provides a complete route from the root directory of a particular drive to a particular folder or file. In contrast, a relative path describes a route from the current folder to a particular folder or file.
• For mapped network drives and shares, the method doesn't return the full network address. Rather, it returns the fully qualified local path and locally issued drive letter.
• The GetAbsolutePathName method is really a string conversion and concatenation method, rather than a filesystem method. It merely returns a string, but doesn't verify that a given file or folder exists in the path specified.

Syntax

oFileSysObj.GetBaseName(Path)

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

Path

Use: Required

Data Type: String

A path specifier.

Return Value

A string containing the last element in Path.

Description

Returns the name of the last path component, less any extension.

Rules at a Glance

The file extension of the last element in Path isn't included in the returned string.

Programming Tips and Gotchas

• GetBaseName doesn't verify that a given file or folder exists in Path.
• In stripping the "file extension" and returning the base name of Path, GetBaseName has no intelligence. That is, it doesn't know whether the last component of Path is a path or a filename. If the last component includes one or more dots, it simply removes the last one, along with any following text. Hence, GetBaseName returns a null string for a Path of (.) and it returns (.) for a Path of (..). It is, in other words, really a string manipulation function, rather than a file function.

See Also

FileSystemObject.GetExtensionName Method

Syntax

oFileSysObj.GetDrive(drivespecifier)

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

drivespecifier

Use: Required

Data Type: String

A drive name, share name, or network path.

Return Value

A Drive object.

Description

Obtains a reference to a Drive object for the specified drive.

Rules at a Glance

• If drivespecifier is a local drive or the letter of a mapped drive, it can consist of only the drive letter (e.g., "C"), the drive letter with a colon ("C:"), or the drive letter and path to the root directory (e.g., "C:") without generating a runtime error.
• If drivespecifier is a share name or network path, GetDrive ensures that it exists as part of the process of creating the Drive object; if it doesn't, the method generates runtime error 76, "Path not found."
• If the specified drive isn't connected or doesn't exist, runtime error 67, "Device unavailable," occurs.

Programming Tips and Gotchas

• Individual drive objects can be retrieved from the Drives collection by using the Drives property. This is most useful, though, if you want to enumerate the drives available on a system. In contrast, the GetDrive method provides direct access to a particular Drive object.
• If you are deriving the drivespecifier string from a path, you should first use GetAbsolutePathName to insure that a drive is present as part of the path. Then you should use FolderExists to verify that the path is valid before calling GetDriveName to extract the drive from the fully qualified path. For example:

  Dim oFileSys, oDrive Set oFileSys = CreateObject("Scripting.FileSystemObject") sPath = oFileSys.GetAbsolutePathName(sPath) If oFileSys.FolderExists(sPath) Then Set oDrive = oFileSys.GetDrive(oFileSys.GetDriveName(sPath)) End If

• If drivespecifier is a network drive or share, you should use the DriveExists method to confirm the required drive is available prior to calling the GetDrive method.
• You must use the Set statement to assign the Drive object to a local object variable.

See Also

Drives Collection Object

Syntax

oFileSysObj.GetDriveName (Path)

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

Path

Use: Required

Data Type: String

A path specifier.

Return Value

A String.

Description

Returns the drive name of a given path.

Rules at a Glance

If the drive name can't be determined from the given path, a zero-length string (" ") is returned.

Programming Tips and Gotchas

• For local and mapped drives, GetDriveName appears to look for the colon as a part of the drive's name to determine whether a drive name is present. For network drives, it appears to look for the computer name and drive name.
• GetDriveName is really a string-parsing method rather than a filesystem method. In particular, it does not verify that the drive name that it extracts from Path actually exists on the system.
• Path can be a network drive or share.

Syntax

oFileSysObj.GetExtensionName(Path)

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

Path

Use: Required

Data Type: String

A path specifier.

Return Value

A String.

Description

Returns the extension of the file element of a given path.

Rules at a Glance

If the extension in Path can't be determined, a zero-length string (" ") is returned.

Programming Tips and Gotchas

• GetExtensionName is a string parsing method rather than a filesystem method. It does not verify that Path is valid, does not verify that the filename designated in Path exists, and does not even guarantee that the value it returns is a valid file extension. In other words, GetExtensionName has no intelligence. It simply parses a string and returns the text that follows the last dot of the last element.
• Path can be a network drive or share.

See Also

FileSystemObject.GetBaseName Method

Syntax

oFileSysObj.GetFile(FilePath)

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

FilePath

Use: Required

Data Type: String

A path and filename.

Return Value

File object.

Description

Returns a reference to a File object.

Rules at a Glance

• FilePath can be an absolute or a relative path.
• If FilePath is a share name or network path, GetFile ensures that the drive or share exists as part of the process of creating the File object.
• If any part of the path in FilePath can't be contacted or doesn't exist, an error occurs.

Programming Tips and Gotchas

• The object returned by GetFile is a File object, not a TextStream object. A File object isn't an open file; the point of the File object is to perform methods such as copying or moving files and interrogating a file's properties. Although you can't write to or read from a File object, you can use the File object's OpenAsTextStream method to obtain a TextStream object. You can also save yourself a step by calling the FileSystemObject object's OpenTextFile method.
• You should first use GetAbsolutePathName to create the required FilePath string.
• If FilePath includes a network drive or share, you could use the DriveExists method to confirm that the required drive is available prior to calling the GetFile method.
• Since GetFile generates an error if the file designated in FilePath doesn't exist, you should call the FileExists method before calling GetFile.
• You must use the Set statement to assign the File object reference to a local object variable.

See Also

FileSystemObject.GetFolder Method, FileSystemObject.GetDrive Method, FileSystemObject.OpenTextFile Method

Syntax

oFileSysObj.GetFileName(Path)

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

Path

Use: Required

Data Type: String

A path specifier.

Return Value

A String.

Description

Returns the filename element of a given path.

Rules at a Glance

• If the filename can't be determined from the given Path, a zero-length string (" ") is returned.
• Path can be a relative or absolute reference.

Programming Tips and Gotchas

• GetFileName doesn't verify that a given file exists in Path.
• Path can be a network drive or share.
• Like all the Getx Name methods of the FileSystemObject object, the GetFileName method is more a string manipulation routine that an object-related routine. GetFileName has no built-in intelligence (and, in fact, seems to have even less intelligence than usual for this set of methods); it simply assumes that the last element of the string that is not part of a drive and path specifier is in fact a filename. For example, if Path is C:Windows, the method returns the string "Windows"; if Path is C:Windows (which unambiguously denotes a folder rather than a filename), the method still returns the string "Windows."

Syntax

oFileSysObj.GetFileVersion(FileName)

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A reference to the FileSystemObject object.

FileName

Use: Required

Data Type: String

A path and filename.

Return Value

A String.

Description

Retrieves version information about the file specified in FileName.

Rules at a Glance

• FileName should include the path as well as the name of the file. The path component can be either an absolute or a relative path to the file.
• If path information is omitted, VBScript attempts to find FileName in the current folder.
• This function reports version information in the format:

  Major_Version.Minor_Version.0.Build

• If a file does not contain version information, the function returns an empty string (" ").

Programming Notes

• The files that can contain version information are executable files (.exe) and dynamic link libraries (.dll).
• If you're using VBScript to replace a private executable or DLL with another, be particularly careful with version checking, since it has been a particularly serious source of error. Ensuring that the new version of the file should be installed requires that any one of the following conditions be true:
  • It has the same major and minor version but a later build number than the existing file.
  • It has the same major version but a greater minor version number than the existing file.
  • It has a higher version number than the existing file.

• It's also a good idea to copy the replaced file to a backup directory, such as the Windows Sysbckup directory.
• If you're thinking of using VBScript to replace a system executable or DLL with another, it's best to use a professional installation program for this purpose.
• Although this function is listed in the type library and is actually implemented in the Scripting Runtime, no documentation for it is available in the HTML Help file.

See Also

ScriptEngineBuildVersion Function, ScriptEngineMajorVersion Function, ScriptEngineMinorVersion Function

Syntax

oFileSysObj.GetFolder(FolderPath)

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

FolderPath

Use: Required

Data Type: String

A path to the required folder.

Return Value

A Folder object.

Description

Returns a reference to a Folder object.

Rules at a Glance

• FolderPath can be an absolute or relative path.
• If FolderPath is a share name or network path, GetFolder ensures that the drive or share exists as part of the process of returning the Folder object.
• If any part of FolderPath doesn't exist, an error occurs.

Programming Tips and Gotchas

• You should first use GetAbsolutePathName to create the required FolderPath string.
• If FolderPath includes a network drive or share, you could use the DriveExists method to confirm the required drive is available prior to calling the GetFolder method.
• Since GetFolder requires that FolderPath is the path to a valid folder, you should call the FolderExists method to verify that FolderPath exists.
• The GetFolder method allows you to directly obtain an object reference to a particular folder. You can also use the Item property of the Folders collection object for cases in which you must navigate the filesystem to reach a particular folder, or for those cases in which you're interested in enumerating the subfolders belonging to a particular folder.
• You must use the Set statement to assign the Folder object reference to a local object variable.

See Also

Folders Collection Object

Syntax

oFileSysObj.GetParentFolderName(Path)

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

Path

Use: Required

Data Type: String

A path specifier.

Return Value

A String.

Description

Returns the folder name immediately preceding the last element of a given path. In other words, if Path ends in a filename, the method returns the path to the folder containing that file. If Path ends in a folder name, the method returns the path to that folder's parent.

Rules at a Glance

• If the parent folder name can't be determined from Path, a zero-length string (" ") is returned.
• Path can be a relative or absolute reference.

Programming Tips and Gotchas

• GetParentFolderName doesn't verify that any element of Path exists.
• Path can be a network drive or share.
• GetParentFolderName assumes that the last element of the string that isn't part of a drive specifier is the parent folder. It makes no other check than this. As with all the Getx Name methods of the FileSystemObject object, the GetParentFolderName method is more a string parsing and manipulation routine than an object-related routine.

Syntax

oFileSysObj.GetSpecialFolder(SpecialFolder)

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

SpecialFolder

Use: Required

Data Type: Special folder constant

A value specifying one of three special system folders.

Return Value

A Folder object.

Description

Returns a reference to a Folder object of one of the three special system folders: System, Temporary, and Windows.

Rules at a Glance

SpecialFolder can be one of the following special folder constants:

Programming Tips and Gotchas

• As the previous table shows, the Scripting Runtime type library defines constants of the SpecialFolderConst enumeration that can be used in place of their numeric equivalents. You can use them in your scripts in either of two ways. You can define the constants yourself by adding the following code to your script:

  Const WindowsFolder = 0 Const SystemFolder = 1 Const TemporaryFolder = 2

  You can also include a METADATA tag in an ASP global.asa file or include the following line in a Windows Script Host (.wsf ) file in order to access the constants from the Scripting Runtime type library:

   

• Prior to the development of the Scripting Runtime Library with its support for the FileSystemObject, the only way to determine the location of system folders was via the Win32 API. This is a much simpler way of getting at that information. This is especially significant when using VBScript with the Windows Script Host, and adds an extremely powerful aspect to writing administrative or maintenance scripts with VBScript.
• You can use the Set statement to assign the Folder object reference to a local object variable. However, if you're interested only in retrieving the path to the special folder, you can do it with a statement like the following:

  sPath = oFileSys.GetSpecialFolder(iFolderConst)

  or:

  sPath = oFileSys.GetSpecialFolder(iFolderConst).Path

  The first statement works because the Path property is the Folder object's default property. Since the assignment isn't to an object variable, it's the default property's value, rather than the object reference, that is assigned to sPath.

• WSH includes a SpecialFolders collection. However, it does not duplicate the functionality of the GetSpecialFolder method.

Syntax

oFileSys.GetStandardStream(StandardStreamType, [Unicode])

oFileSys

Use: Required

Data Type: FileSystemObject object

A reference to the FileSystemObject object.

StandardStreamType

Use: Required

Data Type: Long

A constant indicating which standard stream (input, output, or error) should be returned by the function.

Unicode

Use: Optional

Data Type: Boolean

A Boolean indicating whether the stream should be Unicode or ASCII.

Return Value

A TextStream object.

Description

Allows you to read from the standard input stream and write to the standard output or standard error streams.

Rules at a Glance

• StandardStreamType can be one of the following constants defined in the Scripting Runtime type library:

• The Scripting Runtime type library defines constants of the StandardStreamTypes enumeration that can be used in place of their numeric equivalents for the StandardStreamType argument. You can use them in your scripts in either of two ways. You can define the constants yourself by adding the following code to your script:

  Const StdIn = 0 Const StdOut = 1 Const StdErr = 2

  You can also include an ASP METADATA tag in the global.asa file or the following line in a Windows Script Host (.wsf ) file in order to access the constants from the Scripting Runtime type library:

   

• The Unicode parameter can be either Unicode (True) or ASCII (False).

Programming Tips and Gotchas

• The GetStandardStream method is available from a WSH script run in console mode using CScript.exe as the WSH engine. Otherwise, attempting to retrieve a reference to the TextStream object returned by the method generates an "Invalid handle" or (in ASP) a "Server.CreateObject failed" error message.
• Note that standard input is a read-only stream, while standard output and standard error are write-only streams.
• Although the function is implemented in the Scripting Runtime library, it is currently undocumented.
• This method is functionally equivalent to three methods in the WSH object model: the WScript.StdIn property, which returns a TextStream object representing the standard input; the WScript.StdOut property, which returns a TextStream object representing the standard output; the WScript.StdErr property, which returns a TextStream object representing the standard error stream.

See Also

TextStream Object

Syntax

oFileSysObj.GetTempName

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

Return Value

A String.

Description

Returns a system-generated temporary file or folder name.

Rules at a Glance

GetTempName doesn't create a temporary file or folder; it simply provides a name you can use with the CreateTextFile method.

Programming Tips and Gotchas

• As a general rule, you shouldn't create your own temporary filenames. Windows provides an algorithm within the Windows API to generate the special temporary file and folder names so that it can recognize them later.
• If you are calling GetTempName as the first step in creating a temporary file, you can also call the GetSpecialFolder method to retrieve the path of the temporary directory, as follows:

  Const TemporaryFolder = 2 Dim oFS, sTempPath Set oFS = CreateObject("Scripting.FileSystemObject") sTempPath = oFS.GetSpecialFolder(TemporaryFolder)

  You can then form the complete path to the temporary folder as follows:

  sFullPath = sTempPath & "' & sTempFileName

Syntax

oFileSysObj.MoveFile source, destination

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

source

Use: Required

Data Type: String

The path to the file or files to be moved.

destination

Use: Required

Data Type: String

The path to the location where the file or files are to be moved.

Description

Moves a file from one folder to another.

Rules at a Glance

• If source contains wildcard characters or if destination ends in a path separator, destination is interpreted as a path; otherwise, its last component is interpreted as a filename.
• If the destination file exists, an error occurs.
• source can contain wildcard characters, but only in its last component. This allows multiple files to be moved.
• destination can't contain wildcard characters.
• Both source and destination can be either absolute or relative paths.
• Both source and destination can be network paths or share names.

Programming Tips and Gotchas

• MoveFile resolves both arguments before beginning the operation.
• Any single file move operation is atomic; that is, any file removed from source is copied to destination. However, if an error occurs while multiple files are being moved, the execution of the function terminates, but files already moved aren't moved back to their previous folder. If a fatal system error occurs during the execution of this method (like a power failure), the worst that can happen is that the affected file is copied to the destination but not removed from the source. There are no rollback capabilities built into the File.Move method, since, because the copy part of this two-stage process is executed first, the file can't be lost. But while there is no chance of losing data, particularly in multifile operations, it's more difficult to determine whether the move operations have succeeded. This is because an error at any time while files are being moved causes the MoveFile method to be aborted.
• You can use the GetAbsolutePath, FolderExists, and FileExists methods prior to calling the MoveFile method to ensure its success.
• The MoveFile method differs from the File object's Move method by allowing you to directly designate a file to be moved rather than requiring that you first obtain an object reference to it. It also allows you to move multiple files rather than the single file represented by the File object.

See Also

FileSystemObject.CopyFile Method, FileSystemObject.FileExists Method, FileSystemObject.GetAbsolutePathName Method

Syntax

oFileSysObj.MoveFolder source, destination

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

source

Use: Required

Data Type: String

The path to the folder or folders to be moved.

destination

Use: Required

Data Type: String

The path to the location where the folder or folders are to be moved.

Description

Moves a folder along with its files and subfolders from one location to another.

Rules at a Glance

• source must end with either a wildcard character or no path separator.
• Wildcard characters can be used in source, but only for the last component.
• Wildcard characters can't be used in destination.
• All subfolders and files contained within the source folder are copied to destination unless disallowed by the wildcard characters. That is, the MoveFolder method is recursive.
• If destination ends with a path separator or Source ends with a wildcard, MoveFolder assumes the folder in Source exists in Destination. For example:

  C: Rootone SubFolder1 SubFolder2 RootTwo

  The command MoveFolder "c:Rootone*", "C:RootTwo" produces this folder structure:

  C: Rootone RootTwo SubFolder1 SubFolder2

  The command MoveFolder "c:Rootone", "C:RootTwo" produces this folder structure:

  C: RootTwo Rootone SubFolder1 SubFolder2

• source and destination can be either absolute or relative paths.
• source and destination can be network paths or share names.

Programming Tips and Gotchas

• MoveFolder resolves both arguments before starting the operation.
• If a fatal system error occurs during the execution of this method (like a power failure), the worst that can happen is that the file is copied to the destination but not removed from the source. There are no rollback capabilities built into the FileSystemObject.MoveFolder method, since, because the copy part of this two-stage process is executed first, the file can't be lost.
• Although there is no chance of actually losing data, it can be difficult to determine whether the operation has succeeded or failed in the event of an error when multiple folders are being moved. This is because an error in the middle of a multifile move operation causes the MoveFolder method to be abandoned and subsequent folder operations to be aborted.
• You can call the GetAbsolutePath and FolderExists methods before calling the MoveFile method to ensure its success.
• If the user has adequate rights, the source or destination can be a network path or share name. For example:

  MoveFolder "c:Rootone", "\NTSERV1d$RootTwo"

See Also

FileSystemObject.CopyFile Method, FileSystemObject.FolderExists Method, FileSystemObject.GetAbsolutePathName Method

Syntax

oFileSysObj.OpenTextFile(FileName[, IOMode[, Create[, Format]]])

oFileSysObj

Use: Required

Data Type: FileSystemObject object

A FileSystemObject object.

FileName

Use: Required

Data Type: String

The path and filename of the file to open.

IOMode

Use: Optional

Data Type: Long

A constant specifying the purpose for opening the file.

Create

Use: Optional

Data Type: Boolean

A Boolean flag denoting whether the file should be created if it can't be found in the given path.

Format

Use: Optional

Data Type: Long

A constant specifying ASCII or Unicode format.

Return Value

A TextStream object.

Description

Opens (and optionally first creates) a text file for reading or writing.

Rules at a Glance

• File open (IOMode) values are:

• Tristate (Format) values are:

• The path element of FileName can be relative or absolute.
• The default IOMode setting is ForReading (1).
• The default Format setting is ASCII (False).
• If another process has opened the file, the method fails with a "Permission Denied" error.

Programming Tips and Gotchas

• You can use the GetAbsolutePath and FileExists methods prior to calling the OpenTextFile method to ensure its success.
• As the table listing values for the IOMode parameter shows, the Scripting Runtime type library defines constants of the IOMode enumeration that can be used in place of their numeric equivalents. You can use them in your scripts in either of two ways. You can define the constants yourself by adding the following code to your script:

  Const ForReading = 1 Const ForWriting = 2 Const ForAppending = 8

  You can also include a METADATA tag in the ASP global.asa file or the following line in a Windows Script Host (.wsf ) file in order to access the constants from the Scripting Runtime type library:

   

• The value of IOMode can be only that of a single constant. For example, a method call such as the following:

  lMode = ForReading Or ForWriting oFileSys.OpenTextStream(strFileName, lMode) ' WRONG generates runtime error 5, "Invalid procedure call or argument."

• As the table listing values for the Format parameter shows, the Scripting Runtime type library defines constants of the Tristate enumeration that can be used in place of their numeric equivalents. You can use them in your scripts in either of two ways. You can define the constants yourself by adding the following code to your script:

  Const TristateFalse = 0 Const TristateTrue = -1 Const TristateUseDefault = -2

  You can also include a METADATA tag in the ASP global.asa file or the following line in a Windows Script Host (.wsf ) file in order to access the constants from the Scripting Runtime type library:

   

• If the user has adequate rights, the path element of FileName can be a network path or share name. For example:

  OpenTextFile "\NTSERV1d$RootTwomyFile.txt"

See Also

File.OpenAsTextStream Method, TextStream Object

Syntax

Filter(SourceArray, FilterString[, Switch[, Compare]])

SourceArray

Use: Required

Data Type: String or numeric

An array containing values to be filtered.

FilterString

Use: Required

Data Type: String or numeric

The string of characters to find in the source array.

Switch

Use: Optional

Data Type: Boolean

A Boolean (True or False) value. If True, the default value, Filter includes all matching values in result; if False, Filter excludes all matching values (or, to put it another way, includes all nonmatching values).

Compare

Use: Optional

Data Type: Long

An optional constant (possible values are 0, vbBinaryCompare; 1, vbTextCompare) that indicates the type of string comparison to use. The default value is 0, vbBinaryCompare.

Return Value

A String array of the elements filtered from SourceArray.

Description

Produces an array of matching values from an array of source values that either match or don't match a given filter string. In other words, individual elements are copied from a source array to a target array if they either match or don't match a filter string.

Rules at a Glance

• The default Switch value is True.
• The default Compare value is 0, vbBinaryCompare.
• vbBinaryCompare is case-sensitive; that is, Filter matches both character and case. In contrast, vbTextCompare is case-insensitive, matching only character regardless of case.

Programming Tips and Gotchas

• SourceArray elements that are Empty or that contain zero-length strings ("") are ignored by the Filter function.
• The array you declare to assign the return value of Filter should be a simple variant, as the following code fragment illustrates:

  Dim aResult aResult = Filter(sNames, sCriteria, True)

• Although the Filter function is primarily a string function, you can also filter numeric values. To do this, populate a SourceArray with numeric values. Although FilterString appears to be declared internally as a variant string, a Long or Integer can be passed to the function. For example:

  Dim varSource As Variant, varResult As Variant Dim strMatch As String strMatch = CStr(2) varSource = Array(10, 20, 30, 21, 22, 32) varResult = Filter(varSource, strMatch, True, _ vbBinaryCompare)

  In this case, the resulting array contains four elements: 20, 21, 22, and 32.

• The Filter function is an ideal companion to the Dictionary object. The Dictionary object is a collection-like array of values, each of which is stored with a unique string key. The Keys method of the Dictionary object allows you to produce an array of these Key values, which you can then pass into the Filter function as a rapid method of filtering the members of your Dictionary, as the following example demonstrates.

Example

Dim sKeys Dim sFiltered Dim sMatch Dim blnSwitch Dim oDict Set oDict = CreateObject("Scripting.Dictionary") oDict.Add "Microsoft", "One Microsoft Way" oDict.Add "AnyMicro Inc", "31 Harbour Drive" oDict.Add "Landbor Data", "The Plaza" oDict.Add "Micron Co.", "999 Pleasant View" sKeys = oDict.Keys sMatch = "micro" blnSwitch = True 'find all keys that contain the string "micro" - any case sFiltered = Filter(sKeys, sMatch, blnSwitch, _ vbTextCompare) 'now iterate through the resulting array For i = 0 To UBound(sFiltered) sMsg = sMsg & sFiltered(i) & ", " & oDict.Item(sFiltered(i)) & _ vbCrLf Next MsgBox sMsg

See Also

RegExp Object

Syntax

Fix(number)

number

Use: Required

Data Type: Numeric

Any valid numeric expression.

Return Value

The same data type as passed to the function containing only the integer portion of number.

Description

Removes the fractional part of a number. Operates in a similar way to the Int function.

Rules at a Glance

• If number is Null, Fix returns Null.
• The operations of Int and Fix are identical when dealing with positive numbers: numbers are rounded down to the next lowest whole number. For example, both Int(3.14) and Fix(3.14) return 3.
• If number is negative, Fix removes its fractional part, thereby returning the next greater whole number. For example, Fix(-3.667) returns -3. This contrasts with Int, which returns the negative integer less than or equal to number (or -4, in the case of our example).

Example

Dim dblTest Dim varTest dblTest = -100.9353 varTest = Fix(dblTest) ' returns -100 Msgbox varTest & " " & TypeName(varTest) dblTest = 100.9353 varTest = Fix(dblTest) 'returns 100 Msgbox.Print varTest & " " & TypeName(varTest)

Programming Tips and Gotchas

Fix doesn't round number to the nearest whole number; it simply removes the fractional part of number. Therefore, the integer returned by Fix is the nearest whole number less than (or greater than, if the number is negative) the number passed to the function.

See Also

Int Function, CInt Function, CLng Function, Round Function

Createable

No

Returned by

Drive.RootFolder property

FileSystemObject.CreateFolder method

FileSystemObject.GetFolder method

Folder.SubFolders.Item property

Folders.Add method

Library

Microsoft Scripting Runtime

Description

The Folder object allows you to interrogate the system properties of the folder and provides methods that allow you to copy, move, and delete the folder. You can also create a new text file within the folder.

The Folder object is unusual because with it, you can gain access to a Folders collection object. The more usual method is to extract a member of a collection to gain access to the individual object. However, because the Drive object exposes only a Folder object for the root folder, you have to extract a Folders collection object from a Folder object (the collection represents the subfolders of the root). From this collection, you can navigate downward through the filesystem to extract other Folder objects and other Folders collections. A Boolean property, IsRootFolder, informs you of whether the Folder object you are dealing with currently is the root of the drive.

The Folder object is one of the objects in the Filesystem object model; for an overview of the model, see the "File System Object Model" entry.

Properties

Attributes

Data Type: Long

A set of flags representing the folder's attributes. The flags that apply to folders are:

As the table shows, the Scripting Runtime type library defines constants of the FileAttribute enumeration that can be used in place of their numeric equivalents. You can use them in your scripts in either of two ways. You can define the constants yourself by adding the following code to your script:

Const Normal = 0 Const ReadOnly = 1 Const Hidden = 2 Const System = 4 Const Directory = 16 Const Archive = 32

Or you can take advantage of the host's facilities to make the constants accessible. In Active Server Pages, you can include the METADATA tag in the global.asa file and provide the type library identifier for the Scripting Runtime as follows:

In Windows Script Host, you can include the following line in a .wsf file in order to access the constants defined in the Scripting Runtime:

You can determine which flag is set by using a logical AND along with the value returned by the property and the value of the flag you'd like to test. For example:

If oFolder.Attributes And ReadOnly Then ' Folder is read-only

To clear a flag, And the value of the Attributes property with a Long in which the flag you want to clear is turned off. For example, the following code clears a Folder object's read-only flag:

oFile.Attributes = oFile.Attributes And (Not ReadOnly)

Date Created

Data Type: Date

The date and time the folder was created.

DateLastAccessed

Data Type: Date

The date and, if it's available from the operating system, the time that the folder was last accessed.

DateLastModified

Data Type: Date

The date and time the folder was last modified.

Drive

Data Type: Drive object

Returns a Drive object representing the drive on which this folder resides; the property is read-only.

Files

Data Type: Files collection object

Returns a read-only Files collection object representing all files in the current folder.

IsRootFolder

Data Type: Boolean

Returns True if the folder is the root folder of its drive.

Name

Data Type: String

Returns the name of the folder.

ParentFolder

Data Type: Folder object

Returns a folder object representing the folder that's the parent of the current folder. It returns Nothing if the current object is the root folder of its drive (i.e., if its IsRootFolder property is True).

Path

Data Type: String

Returns the complete path of the current folder, including its drive. It is the default property of the Folder object.

ShortName

Data Type: String

Returns a DOS 8.3 folder name without the folder's path. The property is read-only.

ShortPath

Data Type: String

Returns the complete path to a folder in DOS 8.3 format. The property is read-only.

Size

Data Type: Long

Returns the total size of all files, subfolders, and their contents in the folder structure, starting with the current folder. The property is read-only.

In previous versions of the Scripting Runtime, this property failed to accurately report the size of a folder whose files and subfolders occupied more than 2 GB of disk space.

Attempting to retrieve the value of a Folder object's Size property when that folder is a drive's root folder (that is, its IsRootFolder property returns True) generates a runtime error.

SubFolders

Data Type: Folders collection object

Returns a Folders collection object representing all subfolders within the current folder.

Type

Data Type: String

Returns the description of a filesystem object, as recorded in the system registry. For Folder objects, the property always returns "File Folder."

Methods

Copy

Create TextFile

Delete

Move

Syntax

oFolderObj.Copy Destination [, OverwriteFiles]

oFolderObj

Use: Required

Data Type: Folder object

A Folder object.

Destination

Use: Required

Data Type: String

The path and, optionally, the filename of the copy to be made.

OverwriteFiles

Use: Optional

Data Type: Boolean

Indicates whether existing files and folders should be overwritten (True) or not (False).

Description

Copies the current folder and its contents, including other folders, to another location.

Rules at a Glance

• Wildcard characters can't be used in Destination.
• The folder and all subfolders and files contained in the source folder are copied to Destination. That is, the Copy method is recursive.
• Unlike the FileSystemObject.CopyFolder method, there is no operational difference between ending Destination with a path separator or not.

Programming Tips and Gotchas

• If the destination path or any of the files contained in the Destination structure are set to read-only, the Copy method will fail regardless of the value of OverwriteFiles and will generate a "Permission denied" error.
• If OverwriteFiles is set to False, and the source folder or any of the files contained in the Destination structure exists in the Destination structure, then trappable error 58, "File Already Exists," is generated.
• If an error occurs while copying more than one file, the Copy method exits immediately, leaving the rest of the files uncopied. There is also no rollback facility to undo the copies prior to the error.
• If the user has adequate rights, Destination can be a network path or share name. For example:

  oFolder.Copy "\NTSERV1d$RootTwo"

Syntax

oFolderObj.CreateTextFile FileName[, Overwrite[, Unicode]])

oFolderObj

Use: Required

Data Type: Folder object

A Folder object.

FileName

Use: Required

Data Type: String

Any valid filename and optional path.

Overwrite

Use: Optional

Data Type: Boolean

Flag to indicate whether an existing file of the same name should be overwritten.

Unicode

Use: Optional

Data Type: Boolean

Flag to indicate whether file is to be written in Unicode or ASCII.

Return Value

A TextStream object.

Description

Creates a new file at the specified location and returns a TextStream object for that file.

Rules at a Glance

• Filename can be a relative or absolute path. Wildcard characters are not allowed in FileName.
• If no path is specified in Filename, the script's current drive and directory are used. If no drive is specified in Filename, the script's current drive is used.
• The default value for Overwrite is False.
• If Unicode is set to True, a Unicode file is created; otherwise it's created as an ASCII text file.
• The default value for Unicode is False.

Programming Tips and Gotchas

• If the path specified in Filename does not exist, the method fails. To prevent this error, you can use the FileSystemObject object's FolderExists method to be sure that the path is valid.
• The newly created text file is automatically opened only for writing. If you subsequently wish to read from the file, you must first close it and reopen it in read mode.
• If the file referred to in Filename already exists as a read-only file, the CreateTextFile method fails regardless of the value of Overwrite.
• You must use the Set statement to assign the TextStream object to a local object variable.
• If the user has adequate rights, Filename can contain a network path, or share name. For example:

  oFolder.CreateTextFile "\NTSERV1RootTestmyFile.doc"

• The CreateTextFile method in the Folder object is identical in operation to that in the FileSystemObject object.

See Also

FileSystemObject.CreateTextFile Method, TextStream Object

Syntax

oFolderObj.Delete [Force]

oFolderObj

Use: Required

Data Type: Folder object

A Folder object.

Force

Use: Optional

Data Type: Boolean

If set to True, any read-only flag on a file or a folder to be deleted is ignored and the file or folder is deleted. When set to False, a read-only flag prevents that folder or file from being deleted. Its default value is False.

Description

Removes the folder specified by the Folder object and all its files and subfolders.

Rules at a Glance

• If any of the files within the folder are open, the method fails with a "Permission Denied" error.
• The Delete method deletes all the contents of the given folder, including subfolders and their contents.
• The default setting for Force is False. If any of the files in the folder or its subfolders are set to read-only, the method will fail.
• If Force is set to False and any of the files in the folders are set to read-only, the method fails.

Programming Tips and Gotchas

• The Delete method deletes a folder and its files and subfolders permanently; it does not move the folder or its files and subfolders to the Recycle Bin.
• If an error occurs while deleting more than one file in the folder, the Delete method exits immediately, thereby leaving the rest of the folders or files undeleted. There is also no rollback facility to undo the deletions prior to the error.
• Unlike the FileSystemObject's DeleteFolder method, which accepts wildcard characters in the path parameter and can therefore delete multiple folders, the Delete method deletes only the single folder represented by the Folder object.
• Immediately after the Delete method executes, the Folder's collection object containing the Folder object is automatically updated. The deleted folder is removed from the collection, and the collection count is reduced by one. You shouldn't try to access the deleted Folder object again, and you should set the local object variable to Nothing, as the following code snippet demonstrates:

  Set ofsSubFolder = ofsSubFolders.Item("roottwo") MsgBox ofsSubFolders.Count ofsSubFolder.Delete False MsgBox ofsSubFolders.Count Set ofsSubFolder = Nothing

See Also

FileSystemObject.DeleteFile Method, FileSystemObject.DeleteFolder Method

Syntax

oFolderObj.Move destination

oFolderObj

Use: Required

Data Type: Folder object

A Folder object.

destination

Use: Required

Data Type: String

The path to the location where the folder or folders are to be moved.

Description

Moves a folder structure from one location to another.

Rules at a Glance

• Wildcard characters can't be used in destination.
• If any of the files within the folder being moved are open, an error is generated.
• All subfolders and files contained within the source folder are copied to destination, unless disallowed by the wildcard characters. That is, the Move method is recursive.
• destination can be either an absolute or a relative path.

Programming Tips and Gotchas

• If a fatal system error (like a power failure) occurs during the execution of this method, the worst that can happen is that the folder is copied to the destination but not removed from the source. There are no rollback capabilities built into the Folder.Move method; since, the copy part of this two-stage process is executed first, the folder can't be lost.
• If an error occurs in the middle of a move operation, the operation is terminated, and the remaining files and folders in the folder aren't moved.
• If a folder or a file by the same name already exists in destination, the method generates runtime error 58, "File already exists." To prevent this, you can use the FileSystemObject's FolderExists and GetAbsolutePath methods prior to calling the Move method.
• Unlike the FileSystemObject's MoveFolder method, which accepts wildcard characters in the source parameter and can therefore move multiple folders, the Move method moves only the single folder represented by the Folder object and its contents.
• Immediately after the Move method executes, the Folders collection object containing the Folder object is automatically updated, the moved folder is removed from the collection, and the collection count is reduced by one. You shouldn't try to access the moved folder object again from the same Folders collection object.
• oFolderObj, the Folder object reference, remains valid after the folder has been moved. Its relevant properties (the Drive, ParentFolder, Path, and ShortPath properties, for example) are all updated to reflect the folder's new path after the move.
• If the user has adequate rights, the destination can be a network path or share name. For example:

  oFolder.Move "\NTSERV1d$RootTwo"

See Also

FileSystemObject.MoveFile Method, FileSystemObject.MoveFolder Method

Createable

No

Returned by

Folder.SubFolders property

Library

Microsoft Scripting Runtime

Description

The Folders collection object is a container for Folder objects. Normally, you'd expect to access a single object from the collection of that object; for example, you'd expect to access a Folder object from the Folders collection object. However, things are the other way around here: you access the Folders collection object from an instance of a Folder object. This is because the first Folder object you instantiate from the Drive object is a Root Folder object, and from it you instantiate a subfolders collection. You can then instantiate other Folder and subfolder objects to navigate through the drive's filesystem.

The Folders collection is a subfolder of any Folder object. For instance, the top-level Folders collection (representing all of the folders in the root directory of a particular drive) can be can be instantiated as follows:

Dim oFS, oFolders Set oFS = CreateObject("Scripting.FileSystemObject") Set oFolders = oFS.Drives("C").RootFolder.SubFolders

The Folders collection object is one of the objects in the File System object model; see the File System object model entry for an overview of the model, including the library reference needed to access it.

Properties

Item

Data Type: Folder object

Retrieves a particular Folder object from the Folders collection object. You can access an individual folder object by providing the exact name of the folder without its path. However, you can't access the item using its ordinal number. For example, the following statement returns the Folder object that represents the roottwo folder:

Set ofsSubFolder = ofsSubFolders.Item("roottwo")

Count

Data Type: Long

The number of Folder objects contained in the Folders collection.

Methods

Add

See Also

Folders.Add Method, Folder Object

Syntax

oFoldersCollObj.Add newfoldername

oFoldersCollObj

Use: Required

Data Type: Folders collection object

Any object variable returning a Folders collection object.

newfoldername

Use: Required

Data Type: String

The name of the new folder.

Return Value

Folder object.

Description

Creates a new folder. The location of the new folder is determined by the parent to which the Folders collection object belongs. For example, if you are calling the Add method from a Folders collection object that is a child of the root Folder object, the new folder is created in the root (i.e., it's added to the root's subfolders collection). For example:

Dim oFileSys Dim oRoot, oChild Dim oRootFolders Set oFileSys = CreateObject("Scripting.FileSystemObject") Set oRoot = oFileSys.Drives("C").RootFolder Set oRootFolders = oRoot.SubFolders Set oChild = oRootFolders.Add("Downloads")

Rules at a Glance

You can't use a path specifier in newfoldername ; you can use only the name of the new folder.

See Also

FileSystemObject.CreateFolder Method

Syntax

For counter = initial_value To maximum_value [Step stepcounter] code to execute on each iteration [Exit For] Next

counter

Use: Required

Data Type: Numeric

A variable to be used as the loop counter.

initial_value

Use: Required

Data Type: Numeric

Any valid numeric expression that specifies the loop counter's initial value.

maximum_value

Use: Required

Data Type: Numeric

Any valid numeric expression that specifies the loop counter's maximum value.

stepcounter

Use: Optional (required if Step used)

Data Type: Numeric

Any valid numeric expression that indicates how much the loop counter should be incremented with each new iteration of the loop.

Description

Defines a loop that executes a given number of times, as determined by a loop counter. To use the For...Next loop, you must assign a numeric value to a counter variable. This counter is either incremented or decremented automatically with each iteration of the loop. In the For statement, you specify the value that is to be assigned to the counter initially and the maximum value the counter will reach for the block of code to be executed. The Next statement marks the end of the block of code that is to execute repeatedly, and also serves as a kind of flag that indicates the counter variable is to be modified.

Rules at a Glance

• If initial_value is greater than maximum_value, and no Step keyword is used or the step counter is positive, the For...Next loop is ignored and execution commences with the first line of code immediately following the Next statement.
• If initial_value and maximum_value are equal and stepcounter is 1, the loop executes once.
• counter can't be a variable of type Boolean or an array element.
• counter is incremented by one with each iteration unless the Step keyword is used.
• If the Step keyword is used, stepcounter specifies the amount counter is incremented if stepcounter is positive or decremented if it's negative.
• If the Step keyword is used, and stepcounter is negative, initial_value should be greater than maximum_value. If this isn't the case, the loop doesn't execute.
• The For...Next loop can contain any number of Exit For statements. When the Exit For statement is executed, program execution commences with the first line of code immediately following the Next statement.

Example

This example demonstrates how to iterate from the end to the start of an array of values:

sArray=Array(10, 12, 14, 16, 18, 20, 22, 24) For i = UBound(sArray) To LBound(sArray) Step -1 total = total +sArray(i) Next

This example demonstrates how to select only every other value from an array of values:

sArray=Array(10, 12, 14, 16, 18, 20, 22, 24) For i = LBound(sArray) To UBound(sArray) Step 2 total = total +sArray(i) Next

Programming Tips and Gotchas

• You can also nest For...Next loops:

  For iDay = 1 to 365 For iHour = 1 to 23 For iMinute = 1 to 59 ... Next Next Next

• You should avoid changing the value of counter in the code within the loop. Not only can this lead to unexpected results, but it also makes for code that's incredibly difficult to read and to understand.

See Also

For Each . . . Next Statement

Syntax

For Each element In group [statements] [Exit For] [statements] Next

element

Use: Required

Data Type: Variant

A variable to which the current element from the group is assigned.

group