Appendix F The Scripting Runtime Library Object Reference

The default scripting languages installed with Microsoft Windows XP, Office XP, ASP 3.0, and many other applications provide a scripting runtime library in the file scrrun.dll , which implements a series of objects that can be used in ASP on the server and in client-side code running on the client.

• The Dictionary object provides a useful storage object that we can use to store values,break accessed and referenced by their name rather than by index as would be the case in abreak normal array-it's ideal for storing the name /value pairs that we retrieve from the ASPbreak Request object, for example.
• The FileSystemObject object provides us with access to the underlying file system on thebreak server (or on the client in Internet Explorer 5/6 when used in conjunction with a specialbreak type of page named HTML Application or HTA)-we can use the FileSystemObject break object to iterate through the machine's local and networked drives , folders and files.
• The TextStream object provides access to files stored on disk, and is used in conjunctionbreak with the FileSystemObject object-it can read from or write to text (sequential) files.

The Scripting Dictionary Object

The Dictionary object provides a useful storage object that we can use to store values, accessedbreak and referenced by their name rather than by index, as would be the case in a normal array. Thebreak properties and methods exposed by the Dictionary object are:

Properties

Property	Description
Count	Returns the number of key/item pairs in the Dictionary (read-only)
Item (key)	Sets or returns the value of the item for the specified key
Key (key)	Sets or returns the value of a key

Methods

Method	Description
Add (key , item)	Adds the key/item pair to the Dictionary. You can also add items with a simple assignment, and in fact, you must use this syntax in order to store object references in a dictionary: Set objDict(" keyname ") = objMyObject
Exists (key)	Returns true if the specified key exists or false if not
Items ()	Returns an array containing all the items in abreak Dictionary object
Keys ()	Returns an array containing all the keys in abreak Dictionary object
Remove (key)	Removes a single key/item pair specified by key
RemoveAll ()	Removes all the key/item pairs

Note  

An error will occur if we try to add a key/item pair when that key already exists, remove a key/item pair that doesn't exist, or change the CompareMode of a Dictionary object that already contains data.

The Scripting FileSystemObject Object

The FileSystemObject object provides us with access to the underlying file system on the server (or on the client in Internet Explorer 5/6 when used in conjunction with a special type of page named an HTML Application or HTA). The FileSystemObject object exposes a series of properties and methods of its own, some of which return other objects that are specific to objects within the file system. These subsidiary objects are:

• The Drive object, provides access to all the drives available on the machine
• The Folder object, provides access to the folders on a drive
• The File object, provides access to the files within each folder

While these three objects form a neat hierarchy, the FileSystemObject object also provides methods that can bridge the hierarchy by creating instances of the subsidiary objects directly.

The FileSystemObject Object

The FileSystemObject object provides overall access to the underlying file system and is used as a starting point when navigating the file system.

Properties

Property	Description
Drives	Returns a collection of Drive objects that are available from the local machine. This includes network drives that are mapped from this machine

Methods

Method	Description
BuildPath ( path , name )	Adds the file or folder specified in name to the existing path, adding a path separator character ( ˜') if required. This does not check for valid or existing path
CopyFile (source , destination , overwrite)	Copies the file or files specified in source (wildcards can be included) to the folder specified in destination. If source contains wildcards or destination ends with a path separator character ( '' ) then destination is assumed to be a folder; otherwise , it is assumed to be a full path and name for the new file. Note that leaving off the last '' when the source doesn't contain wildcards throws a 'Permission denied ' error since the name (assumed to be a filename without an extension) exists as a folder name. An error will occur if the destination file already exists and the optional overwrite parameter is set to False . The default for overwrite is True
CopyFolder (source , destination , overwrite)	Copies the folder or folders specified in source (wildcards can be included) to the folder specified in destination , including all the files contained in the source folder(s). If source contains wildcards or destination ends with a path separator character ( '' ) then destination is assumed to be a folder into which the copied folder(s) will be placed; otherwise, it is assumed to be a full path and name for a new folder to be created. An error will occur if the destination folder already exists and the optional overwrite parameter is set to False . The default for overwrite is True
CreateFolder (foldername)	Creates and returns a reference to a new folder, which has the path and name specified in foldername. Only the last folder in the path is created-all parent folders must exist. An error occurs if the specified folder already exists.
CreateTextFile (filename , overwrite , unicode)	Creates a new text file on disk with the specified filename and returns a TextStream object that refers to it. If the optional overwrite parameter is set to True any existing file with the same path and name will be overwritten. The default for overwrite is False . If the optional unicode parameter is set to True , the content of the file will be stored as Unicode text. The default for unicode is False for an ASCII file
DeleteFile (filespec , force)	Deletes the file or files specified in filespec (wildcards can be included). If the optional force parameter is set to True the file(s) will be deleted even if the read-only attribute is set. The default for force is False
DeleteFolder (folderspec , force)	Deletes the folder or folders specified in folderspec (wildcards can be included in the final component of the path) together with all their contents. If the optional force parameter is set to True the file(s) will be deleted even if the read-only attribute is set. The default for force is False
DriveExists (drivespec)	Returns true if the drive specified in drivespec exists, or False if not. The drivespec parameter can be a drive letter as a string or a full absolute path for a folder or file
FileExists (filespec)	Returns True if the file specified in filespec exists, or False if not. The filespec parameter can contain an absolute or relative path for the file, or just the file name to look in the current folder
FolderExists (folderspec)	Returns True if the folder specified in folderspec exists, or False if not. The folderspec parameter can contain an absolute or relative path for the folder, or just the folder name to look in the current folder
GetAbsolutePathName (pathspec)	Takes a path that unambiguously identifies a folder and, taking into account the current folder's path, returns a full unambiguous path specification for the pathspec folder. For example, if the current folder is ' c:docssales ' and pathspec is ' jan ' the returned value is ' c:docssalesjan '. Wildcards and the ' . ', ' .. ' and ' \ ' path operators are accepted
GetBaseName (filespec)	Returns just the name of a file or folder specified in filespec , that is, with the path and file extension removed
GetDrive (drivespec)	Returns a Drive object corresponding to the drive specified in drivespec . The format for drivespec can include the colon , path separator or be a network share, that is, ' c ', ' c: ',' c: ' or ' \ machinesharename '
GetDriveName (drivespec)	Returns the name of the drive specified in drivespec as a string. The drivespec parameter must be an absolute path to a file or folder, or just the drive letter such as ' c: ' or just ' c '
GetExtensionName (filespec)	Returns just the extension of a file or folder specified in filespec , that is, with the path and file name removed
GetFile (filespec)	Returns a File object corresponding to the file specified in filespec or the last folder name if there is no file. This can be a relative or absolute path to the required file
GetFileName (pathspec)	Returns the name part (that is, without the path or file extension) of the path and filename specified in pathspec , or the last folder name of which there is no file name. This does not check for existence of the file or folder
GetFileVersion (filespec)	Returns the version information from a file in Windows 2000, XP and Windows Script Host 2.0 and 5.6
GetFolder (folderspec)	Returns a Folder object corresponding to the folder specified in folderspec . This can be a relative or absolute path to the required folder
GetParentFolderName (pathspec)	Returns the name of the parent folder of the file or folder specified in pathspec . This does not check for existence of the folder
GetSpecialFolder (folderspec)	Returns a Folder object corresponding to one of the special Windows folders. The permissible values for folderspec are: WindowsFolder (0) SystemFolder (1) TemporaryFolder (2)
GetTempName ()	Returns a randomly generated file name that can be used for performing operations that require a temporary file or folder
MoveFile (source , destination)	Moves the file or files specified in source to the folder specified in destination . Wildcards can be included in source but not in destination . If source contains wildcards or destination ends with a path separator character ( '' ) then destination is assumed to be a folder; otherwise, it is assumed to be a full path and name for the new file. Note that leaving off the last '' when the source doesn't contain wildcards throws a 'Permission denied' error since the name (assumed to be a filename without an extension) exists as a folder name. An error will occur if the destination file already exists
MoveFolder (source , destination)	Moves the folder or folders specified in source to the folder specified in destination . Wildcards can be included in source but not in destination . If source contains wildcards or destination ends with a path separator character ( '' ) then destination is assumed to be the folder in which to place the moved folders; otherwise, it is assumed to be a full path and name for a new folder. An error will occur if the destination folder already exists
OpenTextFile (filename , iomode , create , format)	Creates a file named filename , or opens an existing file named filename , and returns a TextStream object that refers to it. The filename parameter can contain an absolute or relative path. The iomode parameter specifies the type of access required. The permissible values are ForReading (1) , (the default), ForWriting (2) , and ForAppending (8) . If the create parameter is set to True when writing or appending to a file that does not exist, a new file will be created. The default for create is False . The format parameter specifies the format of the data to be read from or written to the file. Permissible values are TristateFalse (0) , (the default) to open it as ASCII, TristateTrue (-) to open it as Unicode, and TristateUseDefault (-2) to open it using the system default format

The Drive Object

The Drive object provides access to all the drives available on the machine. The properties (note that it has no methods) exposed by the Drive object are:

Property	Description
AvailableSpace	Returns the amount of space in bytes available to this user on the drive, taking into account quotas and/or other restrictions
DriveLetter	Returns the drive letter of the drive
DriveType	Returns the type of the drive The values are: Unknown (0) Removable (1) Fixed (2) Network (3) CDRom (4) RamDisk (5)
FileSystem	Returns the type of file system for the drive. The values include ' FAT ', ' NTFS ', and ' CDFS '
FreeSpace	Returns the actual amount of free space in bytes available onbreak the drive
IsReady	Returns a Boolean value indicating if drive is ready ( True ) orbreak not ( False )
Path	Returns the path for the drive as a drive letter and colon,break that is, ' C: '
RootFolder	Returns a Folder object representing the root folder of the drive
SerialNumber	Returns a decimal serial number used to uniquely identify abreak disk volume
ShareName	Returns the network share name for the drive if it is abreak networked drive
TotalSize	Returns the total size in bytes of the drive
VolumeName	Sets or returns the volume name of the drive if it is a local drive

The Folder Object

The Folder object provides access to the folders on a drive.

Properties

Property	Description
Attributes	Returns the attributes of the folder
	Can be a combination of any of the values
	Normal (0)
	ReadOnly (1)
	Hidden (2)
	System (4)
	Volume (name) (8)
	Directory (folder) (16)
	Archive (32)
	Alias (1024)
	Compressed (2048)
	Can also be used to set the ReadOnly , Hidden , System , and Archive attributes
DateCreated	Returns the date and time that the folder was createdbreak where available
DateLastAccessed	Returns the date and time that the folder was last accessed
DateLastModified	Returns the date and time that the folder was last modified
Drive	Returns the drive letter of the drive on which thebreak folder resides
Files	Returns a Files collection containing File objects representing all the files within this folder
IsRootFolder	Returns a Boolean value indicating if the folder is the root folder of the current drive
Name	Sets or returns the name of the folder
ParentFolder	Returns the Folder object for the parent folder ofbreak this folder
Path	Returns the absolute path of the folder using long file names where appropricate
ShortName	Returns the DOS-style 8.3 version of the folder name
ShortPath	Returns the DOS-style 8.3 version of the absolute path of this folder
Size	Returns the total combined size of all files and subfolders contained in the folder
SubFolders	Returns a Folders collection consisting of all folders contained in the folder, including hidden and system folders
Type	Returns a string that is a description of the folder type (such as 'Recycle Bin'), if available
DateCreated	Returns the date and time that the folder was created where available

Methods

Method	Description
Copy (destination , overwrite)	Copies this folder and all its contents to the folder specified in destination , including all the files contained in this folder. If destination ends with a path separator character ( '' ) then destination is assumed to be a folder into which the copied folder will be placed; otherwise, it is assumed to be a full path and name for a new folder to be created. An error will occur if the destination folder already exists and the optional overwrite parameter is set to False . The default for overwrite is True
Delete (force)	Deletes this folder and all its contents. If the optional force parameter is set to True the folder will be deleted even if the read-only attribute is set on it or on any contained files. The default for force is False
Move (destination)	Moves this folder and all its contents to the folder specified in destination . If destination ends with a path separator character ( '' ) then destination is assumed to be the folder in which to place the moved folder; otherwise, it is assumed to be a full path and name for a new folder. An error will occur if the destination folder already exists
CreateTextFile (filename , overwrite , unicode)	Creates a new text file within this folder with the specified filename and returns a TextStream object that refers to it. If the optional overwrite parameter is set to True any existing file with the same name will be overwritten. The default for overwrite is False . If the optional unicode parameter is set to True , the content of the file will be stored as Unicoded text. The default for unicode is False

The File Object

The File object provides access to the files within each folder.

Properties

Property	Description
Attributes	Sets or returns the attributes of the file
	Can be a combination of any of the values:
	Normal (0)
	ReadOnly (1)
	Hidden (2)
	System (4)
	Volume (name) (8)
	Directory (folder) (16)
	Archive (32)
	Alias (1024)
	Compressed (2048)
	Can also be used to set the ReadOnly , Hidden , System , and Archive attributes
DateCreated	Returns the date and time that the file was createdbreak where available
DateLastAccessed	Returns the date and time that the file was last accessed
DateLastModified	Returns the date and time that the file was last modified
Drive	Returns the drive letter of the drive on which thebreak file resides
Name	Sets or returns the name of the file
ParentFolder	Returns the Folder object for the parent folder of this file
Path	Returns the absolute path of the file using long file names where appropriate
ShortName	Returns the DOS-style 8.3 version of the file name
ShortPath	Returns the DOS-style 8.3 version of the absolute path of this file
Size	Returns the size of the file in bytes
Type	Returns a string that is a description of the file type (such as ' Text Document ' for a .txt file) if available

Methods

Method	Description
Copy (destination , overwrite)	Copies this file to the folder specified in destination . If destination ends with a path separator character ('' ) then destination is assumed to be a folder into which the copied file will be placed; otherwise, it is assumed to be a full path and name for a new file to be created. Note that leaving off the last '' when the source doesn't contain wildcards throws a 'Permission denied' error since the name (assumed to be a filename without an extension) exists as a folder name. An error will occur if the destination file already exists and the optional overwrite parameter is set to False . The default for overwrite is True
Delete (force)	Deletes this file. If the optional force parameter is set to True the file will be deleted even if the read-only attribute is set. The default for force is False
Move (destination)	Moves this file to the folder specified in destination . If destination ends with a path separator character ( '' ) then destination is assumed to be the folder in which to place the moved file; otherwise, it is assumed to be a full path and name for a new file. An error will occur if the destination file already exists
OpenAsTextStream (iomode , format)	Opens a specified file and returns a TextStream object that can be used to read from,write to, or append to the file. The iomode parameter specifies the type of access required.
	The permissible values are:
	ForReading (1) (the default)
	ForWriting (2)
	ForAppending (8)
	If the create parameter is set to True when writing or appending to a file that does not exist, a new file will be created. The default for create is False . The format parameter specifies the format of the data to be read from or written to the file. Permissible values are TristateFalse (0) (the default) to open it as ASCII, TristateTrue (-1) to open it as Unicode, and TristateUseDefault (-2) to open it using the system default format

The TextStream Object

The TextStream object provides access to files stored on disk, and is used in conjunction with the FileSystemObject object.

Properties

Property	Description
AtEndOfLine	Returns true if the file pointer is at the end of a line in the file
AtEndOfStream	Returns true if the file pointer is at the end of the file
Column	Returns the column number of the current character in the file starting from 1
Line	Returns the current line number in the file starting from 1

The AtEndOfLine and AtEndOfStream properties are only available for a file that is opened with the iomode parameter set with the value ForReading. Referring to them otherwise causes an error to occur.

Methods

Method	Description
Close ()	Closes an open file
Read (numchars)	Reads numchars characters from the file
ReadAll ()	Reads the entire file as a single string
ReadLine ()	Reads a line from the file as a string
Skip (numchars)	Skips and discards numchars characters when reading from the file
SkipLine ()	Skips and discards the next line when reading from the file
Write (string)	Writes string to the file
WriteLine (string)	Writes string (optional) and a newline character to the file
WriteBlankLines (n)	Writes n newline characters to the file