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 |