CHAPTER 18 File Access Component

In addition to the native ASP objects (Request, Response, etc.) and the various installable components (Ad Rotator, Browser Capabilities, etc.), you also have access to a third group of objects. These objects are instantiated directly from the Microsoft Scripting Runtime DLL (scrrun.dll ). This DLL contains functionality that is neither in the native ASP objects nor in the VBScript runtime (vbscript.dll) itself. From the scripting DLL, you can instantiate objects that provide your application with extensive file manipulation capabilities. (From this DLL, you also can create a Dictionary object that provides you with a way to perform collection-type functions without true collections.) All file manipulation is performed by the FileSystemObject object. Your application will have only one of these, and it represents your application’s “window” onto the system’s file structures. With this object, you are able to perform some simple functions such as opening and closing files, but the real strength of this object is that through it you are able to instantiate the other file manipulation objects: Drive, Folder, and File. Through these objects, your application has almost all the power over the file system that you have through a command-line interface. Accessory Files/Required DLL Files Scrrun.DLL The dynamic link library that contains all the scripting objects. This DLL is installed by default when you install IIS 4.0 on your web server. Instantiating Installable Components To create an object variable containing an instance of the FileSystemObject component, use the CreateObject method of the Server object. The syntax for the CreateObject method is as follows: Set objMyObject = Server.CreateObject(strProgId) Object Model 317 File Access Object Model ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. where: • objMyObject represents the name of the FileSystemObject component • strProgId represents the programmatic identifier (ProgID) for the FileSystemObject component, which is Scripting.FileSystemObject Example <% ' The following code uses the CreateObject method of ' the Server object to instantiate a FileSystemObject. Dim fsFileSystemObject Set fsFileSystemObject = _ Server.CreateObject("Scripting.FileSystemObject") %> For more details on the use of the CreateObject method, see its entry in Chapter 8, Server Object. Comments/Troubleshooting The File Access components of scrrun.dll are straightforward to use. When errors occur, the various properties and methods all return error messages that are in accordance with what you would expect if you were to perform a given file operation through the command line. For example, if you attempt to write or read files on the floppy drive on your computer, but you have no disk in the drive, you will receive a “disk not ready” error. One final note: Microsoft has recently released for public download an unsupported Document Summary component that will allow you to view the contents of a directory and display useful information (such as file dates, etc.) from an ASP. This was just released as this book was nearing its last stages of development, so it is not covered here. Download it from http://www.microsoft.com/windows/ downloads/default.asp and experiment on your own. Object Model The diagram in Figure 18-1 illustrates the hierarchical object model representing the file system and all its constituents. (Figure 18-1 offers a simplified view of the model. Each collection is in fact made up of its constituent objects; the Folders collection, for example, contains individual Folder objects that, in turn, have Files collections of their own.) The following sections list each object in the model, along with its properties, collections, and methods. Items marked with an asterisk are documented in detail in the Properties Reference and the Methods Reference in this chapter. Drive Object The Drive object represents a physical drive. This drive can exist on your machine, or it can be a drive shared by another machine. The Drive object’s properties and 318 Chapter 18 – File Access Component Object Model ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. its single collection are listed in Tables 18-1 and 18-2, respectively. The properties in Table 18-1 are all read-only. Figure 18-1: The FileSystemObject object model Table 18-1: Drive Object Properties Property Description AvailableSpace* Indicates the amount of space (in bytes) left on the drive or network share represented by the Drive object. DriveLetter A string value representing the physical drive letter or share name for the Drive object. DriveType One of the following integer values representing the type of drive: 0—Unknown 1—Removable 2—Fixed 3—Network 4—CD-ROM 5—RAM Disk FileSystem* A string value representing the file system used to format the drive represented by the Drive object. Some possible return values are FAT, NTFS, and CDFS. FreeSpace A long integer representing the number of bytes of space available on the drive. This is the same value as that for the AvailableSpace property unless the drive represented by the Drive object supports quotas. IsReady* A Boolean value that indicates whether the drive represented by the Drive object is ready for operation. Path The physical path of the drive represented by the Drive object. RootFolder Returns the Folder object (described later in this chapter) that is the root folder for the drive represented by the Drive object. SerialNumber A decimal number that represents a uniquely identifying number for the drive represented by the Drive object. FileSystemObject Drives Collection Folders Collections Files Collection TextStream Object Object Model 319 File Access Object Model ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Drives Collection The Drives collection contains Drive objects representing the collection of all the drives on the current machine. This collection includes both physical drives and drives shared by other machines. This is a read-only collection; you cannot use this collection to add or remove a drive. The Drives collection’s properties are shown in Table 18-3. File Object The File object represents a given file on the local machine or on a network share. This object makes all the properties of that file accessible to your code. The File object’s properties and methods are listed in Tables 18-4 and 18-5, respectively. ShareName A string value that represents the network share name of the drive represented by the Drive object, if it’s shared. TotalSize A long integer that represents the total size in bytes (used and unused) of the drive represented by the Drive object. VolumeName A string value representing the file system volume name of the drive represented by the Drive object. Table 18-2: Drive Object Collections Collection Description Folders All the top-level folders located immediately under the current drive. Within the Folders collection’s Folder objects exist Files collections containing File objects and lower-level Folders collections. Table 18-3: Drives Collection Properties Property Description Count An integer that represents the total number of Drive objects in the collection. Item Returns a specific Drive object from the Drives collection. It works exactly as does the Item property of the Contents collection of the Application or Session objects. You can retrieve a specific Drive object by index (Drives(1)) or by name (Drives("C")). Table 18-4: File Object Properties Property Description Attributes* The operating system attributes for that file. Depending on the specific file attribute, this property could be either read/write or read-only. DateCreated* The date the file was created. DateLastAccessed* The date of the last time a user accessed the file. Table 18-1: Drive Object Properties (continued) Property Description 320 Chapter 18 – File Access Component Object Model ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Files Collection The Files collection represents the collection of all the files in a Folder object. Its properties are shown in Table 18-6. FileSystemObject Object The FileSystemObject object is the top-level object through which all access to a file system occurs. Table 18-7 lists its single collection, while Table 18-8 lists its DateLastModified* The date the file was last modified. Drive* The drive letter of the drive that holds the current file. Name A string value that contains the name of the file. ParentFolder* The name of the folder in which the file resides. Path The physical path of the file. ShortName The 8.3 format name of the file. ShortPath The 8.3 format physical path of the file. Size The size in bytes of the current file. Type The file type for the file, as determined using your machine’s file associations (if one exists). For example, on a machine with Microsoft Word installed, the file test.doc would have a Type property of Microsoft Word Document. Table 18-5: File Object Methods Method Description Copy* Copies the file from one location to another Delete* Deletes the file Move* Moves the file from one location to another OpenAsTextStream* Opens the file for reading, writing, or appending Table 18-6: Files Collection Properties Property Description Count The total number of files in the collection. Item Retrieves a particular file from the collection. Again, the Item property is similar to the same property of the Application and Session Contents collections. You can retrieve a specific File object using its index in the collection or its name. For example, either of the following two lines will work: Set filObj1 = Files(1) Set filObj2 = Files("help.txt") Table 18-4: File Object Properties (continued) Property Description Object Model 321 File Access Object Model ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. methods. Note that many of these methods are only parsing functions and have no real correlation with the underlying file system. Table 18-7: FileSystemObject Object Collections Property Description Drives Returns the Drives collection containing all the drives accessible through the current FileSystemObject. Table 18-8: FileSystemObject Object Methods Method Description BuildPath Appends a folder name or a relative path to a path. For example, you could append the folder name Documents to the path C:\MyStuff\Personal. The result would be C:\MyStuff\Personal\Documents. The extra backslash is automatically provided, if necessary. CopyFile Copies a file from one location to another. This method is similar to the File object’s Copy method, but no File object is required. CopyFolder Copies a folder and all its contents from one location to another. CreateFolder* Creates a new folder. CreateTextFile Creates a new text file. DeleteFile Deletes a specific file. This method is similar to the File object’s Delete method, but no File object is required. DeleteFolder Deletes a folder and all its contents. DriveExists Determines whether a specific drive exists on your machine. It does not, however, guarantee that the drive is available. FileExists Determines whether the specified file exists. FolderExists Determines whether the specified folder exists. GetAbsolutePathName Determines the physical path from the root of a specific file or folder. GetBaseName* Determines the last element in a physical path string minus any file extension, if one exists. GetDrive Retrieves the Drive object for a given file or folder. GetDriveName Retrieves the name of the drive associated with a particular file or folder. GetExtensionName Retrieves the file extension for the last element in a file specification, if one exists. GetFile Retrieves a File object associated with a specified file. GetFileName Retrieves the name of the last element of a file path. For example, given the argument C:\docs\mystuff\ test.txt, you would retrieve test.txt. 322 Chapter 18 – File Access Component Object Model ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Folder Object A Folder object represents an actual file folder on the current machine. Its properties, collections, and methods are listed in Tables 18-9, 18-10, and 18-11, respectively. GetFolder Retrieves the name of the last folder in a physical path. For example, given the argument C:\docs\ mystuff, you would retrieve the string mystuff. GetParentFolderName* Retrieves the name of the parent folder for the file or folder you specify as an argument. GetSpecialFolder* Retrieves the physical path for any of the special Windows-related folders: Windows, Windows\System, or the Temp folder. You can use this method on any Windows platform. GetTempName Generates a random temporary file or folder for those methods that require one. This method only returns a temporary filename but does not create the actual file. MoveFile Moves a specific file from one location to another. This method is similar to the File object’s Move method, but no File object is required. MoveFolder* Moves a folder and all its contents from one location to another OpenTextFile Opens a specified text file. You can then read from, write to, or append to this file. Table 18-9: older Object Properties Property Description Attributes* The operating system attributes for that folder. Depending on the specific folder attribute, this property could be either read/write or read-only. DateCreated* The date the folder was created on the current drive. DateLastAccessed* The date of the last time a user accessed the folder. DateLastModified* The date the folder was last modified. Drive* A string value containing the drive letter of the drive that holds the current folder. IsRootFolder* A Boolean value indicating whether the current Folder object represents the root folder on a specific drive. Name A string value representing the name of the folder. ParentFolder* Returns a reference to the current Folder object’s parent folder. Path A string value representing the full physical path of the current folder. ShortName The 8.3 format name of the folder. Table 18-8: FileSystemObject Object Methods (continued) Method Description Object Model 323 File Access Object Model ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Folders Collection The Folders collection represents all the folders that exist within the current folder on a particular drive. It does not contain subfolders within the folders on this drive. To retrieve information from subfolders, you must access the Folders collection returned from a call to the SubFolders property of a Folder object. The Folders collection’s properties are shown in Table 18-12, while its single method appears in Table 18-13. ShortPath The 8.3 format physical path of the folder. Size The size in bytes of all of the current folder’s contents. SubFolders Returns a Folders collection that represents all the folders existing within the current folder. Table 18-10: Folder Object Collections Collection Description Files The collection of Files within the current folder only. It does not represent files existing in subfolders of the current folder. Folders The collection of subfolders (retrieved through the SubFolders property of a Folder object) within the current Folder object. Table 18-11: Folder Object Methods Method Description Copy* Copies the folder and its contents from one location to another Delete* Deletes the folder and all its contents Move* Moves the folder and all its contents from one location to another CreateTextFile Opens a new text file Table 18-12: Folders Collection Properties Property Description Count The total number of folders in the current collection. Item Returns a reference to a particular folder in the collection. The Item property is similar to the same property of the Application and Session Contents collections. You can retrieve a specific Folder object using its index in the Folders collection or its name. Table 18-13: Folders Collection Methods Method Description Add Adds a new folder to the Folders collection Table 18-9: older Object Properties (continued) Property Description 324 Chapter 18 – File Access Component Properties Reference ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. TextStream Object The TextStream object allows you to access text files sequentially. This allows you to read, write, or append characters or lines to a text file. The TextStream object’s properties and methods are listed in Tables 18-14 and 18-15, respectively. Properties Reference AtEndOfLine (TextStream Object) fsoObj.AtEndOfLine A Boolean value that indicates whether the file pointer is at the end of the current line. This is a read-only property. Table 18-14: TextStream Object Properties Property Description AtEndOfLine* A Boolean value that indicates whether the current position within the file is at the end of a line AtEndOfStream* A Boolean value that indicates whether the current position within the file is at the end of the text file Column An integer value that indicates the column number of the current position in a line of text Line An integer value that indicates the line number within a text file Table 18-15: TextStream Object Methods Method Description Close* Closes the current text file. Once closed, the file must be reopened before you can read from or write to it. Read Reads a specified number of characters from an open text file. ReadAll Reads all the characters from an open text file into a string. ReadLine* Reads an entire line of text from an open text file. Skip Skips over a specified number of characters in an open text file. In conjunction with the Read method, the Skip method allows you to read a number of characters starting at a specific position. SkipLine Skips over a specified number of lines in an open text file. Write* Writes a specified string to an open text file. WriteBlankLines Writes a specified number of newline characters to an open text file. WriteLine* Writes an entire line of text to an open text file. You specify the string to be written, and the method will include a newline character at the end of the line. AtEndOfStream (FileSystemObject Object) 325 File Access AtEndOfStream (FileSystemObject Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Parameters None Example The following code instantiates a FileSystemObject and a TextStream object. It then uses the Read method to read one character at a time until the end of the line is reached. Notice that the use of the AtEndOfStream and AtEndOfLine properties are identical. <% ' Set up constants. Const constForReading = 1 Const constTristateFalse = 0 ' Dimension local variables. Dim fsoObject ' FileSystemObject Dim tsObject ' TextStream Object Dim strReturned ' String variable to hold file contents ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Using the CreateTextFile method of fsoObject, ' create a text file. Set tsObject = _ fsoObject.OpenTextFile("d:\docs\test.txt", _ constForReading, constTristateFalse) ' Read one character at a time until the end of the ' line has been reached. Do While Not tsObject.AtEndOfLine StrReturned = strReturned & tsObject.Read(1) Loop ...[additional code] %> Notes If you attempt to use the AtEndOfLine property with a text file opened for any purpose other than reading, you will receive an error. The AtEndOfLine property will not inform you that you have reached the end of the file. AtEndOfStream (FileSystemObject Object) fsoObj.AtEndOfStream A Boolean value that indicates whether you have reached the end of the current text file. This is a read-only property. 326 Chapter 18 – File Access Component Attributes (File Object, Folder Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Parameters None Example The following code instantiates a FileSystemObject and a TextStream object. Then it uses the Read method to read one character at a time until the end of the file is reached. Notice that the use of the AtEndOfStream and AtEndOfLine properties are identical. <% ' Set up constants. Const constForReading = 1 Const constTristateFalse = 0 ' Dimension local variables. Dim fsoObject ' FileSystemObject Dim tsObject ' TextStream Object Dim strReturned ' String variable to hold file contents. ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Using the CreateTextFile method of fsoObject, create ' a text file. Set tsObject = _ fsoObject.OpenTextFile("d:\docs\test.txt", _ constForReading, constTristateFalse) ' Read one character at a time until the end of the ' line has been reached Do While Not tsObject.AtEndOfStrean StrReturned = strReturned & tsObject.Read(1) Loop ...[additional code] %> Notes If you attempt to use the AtEndOfStream property with a text file opened for any purpose other than reading, you will receive an error. Attributes (File Object, Folder Object) Obj.Attributes [ = intNewAttributes] An integer containing a combination of values representing various file system attributes. This property is read-only or read/write depending on the specific file attribute in question. The following table lists the values that the Attributes property can contain. To determine whether a File or Folder object has a particular value, use the bitwise And operator to compare the Attributes property value and the specific constant in Attributes (File Object, Folder Object) 327 File Access Attributes (File Object, Folder Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. which you’re interested. If the result is True, then that specific attribute is True. See the following examples. Parameters intNewAttributes An integer containing the sum of a file’s or folder’s attributes. For example, if you wanted to set the Archived and Hidden attributes to True, intNewAttributes would have a value of Hidden + Archive, or 34 (2 + 32). When assigned to the Attributes property, this integer would set these two attributes to True. Example The following code uses the Attributes property first with a File object, and then with a Folder object. <% ' Dimension local variables. Dim fsoObject ' FileSystemObject Dim filObject ' File Object Dim fdrObject ' Folder Object ' Declare constants. Const Hidden = 2 Const Archive = 32 ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Using the GetFile method of fsoObject, initialize the ' File object. Set filObject = fsoObject.GetFile("d:\docs\test.txt") ' Set the Hidden (value = 2) and Archive (value = 32) Attributes Constant Value Description Normal 0 No attributes are set. ReadOnly 1 Read-only. This attribute is read/write. Hidden 2 Hidden. This attribute is read/write. System 4 System file. This attribute is valid only for File objects and is read/write. Volume 8 The drive’s volume label. This attribute is readonly. Directory 16 Directory. This attribute is read-only. Archive 32 Archived. This attribute is read/write. Alias 64 A link or shortcut for another file. This attribute is valid only for File objects and is read-only. Compressed 128 Compressed. This attribute is valid only for File objects and is read-only. 328 Chapter 18 – File Access Component AvailableSpace (Drive Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. ' attributes for the Test.TXT file. filObject.Attributes = (Hidden + Archive) ' Using the GetFolder method of fsoObject, initialize ' the Folder object. Set fdrObject = fsoObject.GetFolder("d:\docs") ' Determine whether the folder is itself hidden. If (fdrObject.Attributes And Archive) Then ' Folder is hidden. Else ' Folder is NOT hidden. End If ...[additional code] %> Notes If you attempt to use the read-only attributes that deal only with File objects with a Folder object, the result is always a False value. However, if you attempt to set any of the read-only attributes for File or Folder objects, the result is an error. Note that you must explicitly declare constants for use with the File Access components. AvailableSpace (Drive Object) drvObj.AvailableSpace The number of bytes of space left on the current drive. This is a read-only property. Parameters None Example <% ' Dimension local variables. Dim fsoObject ' FileSystemObject Dim drvObject ' Drive Object Dim lngAvailBytes ' Number of bytes available ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Using the GetDrive method of fsoObject, initialize a ' Drive object. Set drvObject = fsoObject.GetDrive("\\PublicDocs") ' Retrieve the amount of space (in bytes) available ' on the drive. lngAvailBytes = drvObject.AvailableSpace ...[additional code] %> Drive (File Object, Folder Object) 329 File Access Drive (File Object, Folder Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Notes The only time the value for the AvailableSpace property and the value for the FreeSpace property will be different is if the drive supports quotas. For all practical purposes, you can use these two properties interchangeably. DateCreated (File Object, Folder Object) Obj.DateCreated A date value that represents the date the file or folder was created. This is a readonly value controlled by the operating system. Parameters None Example <% ' Dimension local variables. Dim fsoObject ' FileSystemObject. Dim fdrObject ' Folder object. Dim datCreated ' Date variable. ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Using the GetFolder method of fsoObject, initialize ' a Folder object Set fdrObject = fsoObject.GetFolder("c:\Docs") ' Retrieve the date the folder was created. datCreated = fdrObject.DateCreated ...[additional code] %> Notes The value of this property indicates the date the file was created, not the date the file was written to the current drive. Drive (File Object, Folder Object) Obj.Drive Returns a Drive with which the File or Folder object is associated. This property is read-only. Parameters None 330 Chapter 18 – File Access Component FileSystem (Drive Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Example <% ' Dimension local variables. Dim fsoObject ' FileSystemObject Dim filObject ' File Object Dim objDrive ' Drive name ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Using the GetFile method of fsoObject, initialize ' a File object. Set filObject = fsoObject.GetFile("PublicDocs.txt") ' Retrieve the drive name with which the File object ' is associated. Set objDrive = filObject.Drive ' Note that this drive is actually the current drive ' in this case. ...[additional code] %> Notes The Drive property can represent either a physical, local, or mapped drive or a network share. Because the Drive object’s default property is Path, you can assign the drive name to a string as follows: strDrive = filObject.Drive This is really a shorthand version of: strDrive = filObject.Drive.Path If you wish to manipulate the Drive object, though, you must use the Set statement to assign the reference to an object variable. For example: Set objDrive = filObject.Drive FileSystem (Drive Object) drvObj.FileSystem A string value that represents the file system type used to format the current drive. The recognized file system types are CDFS, NTFS, and FATS. This is a read-only property. Parameters None IsReady (Drive Object) 331 File Access IsReady (Drive Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Example <% ' Dimension local variables. Dim fsoObject ' FileSystemObject Dim drvObject ' Drive Object Dim strFileSys ' File system of drive ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Using the GetDrive method of fsoObject, initialize ' a Drive object. Set drvObject = fsoObject.GetDrive("\\PublicDocs") ' Retrieve the file system for the drive. This value ' will contain one of the following strings: ' NTFS, FAT, or CDFS. strFileSys = drvObject.FileSystem ...[additional code] %> Notes You can rely on the value of the FileSystem property of a Drive object to reflect cluster sizes and security features available for the current drive. IsReady (Drive Object) drvObj.IsReady A Boolean value representing whether the current drive is available for reading or writing. Use this property, for example, to determine whether a floppy disk or CD has been placed in a drive. This is a read-only property. Parameters None Example <% ' Dimension local variables. Dim fsoObject ' FileSystemObject Dim drvObject ' Drive Object ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( "Scripting.FileSystemObject") ' Using the GetDrive method of fsoObject, initialize a ' Drive object. Set drvObject = fsoObject.GetDrive("\\PublicDocs") ' Check to see if the drive is ready. If drvObject.IsReady Then ' Drive is ready for read/write. 332 Chapter 18 – File Access Component IsRootFolder (Folder Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Else ' Drive is not ready. End If ...[additional code] %> Notes It is a good idea to use the IsReady property before attempting to do any drive access. It can be used to determine the readiness of removable-media drives (floppy and CD-ROM drives) and fixed-media drives. IsRootFolder (Folder Object) fdr.IsRootFolder A Boolean value that allows you to determine if the current folder is the root folder. This is a read-only property. Parameters None Example <% ' Dimension local variables. Dim fsoObject ' FileSystemObject Dim fdrObject ' Folder Object ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Using the GetFolder method of fsoObject, initialize a ' File object. Set fdrObject = fsoObject.GetFolder("PublicDocs.txt") ' Determine whether the current folder is a root folder ' or if it is nested. If fdrObject.IsRootFolder Then ' Folder is located directly off the drive letter ' or share name. Else ' The folder is nested within at least one other ' folder. End If ...[additional code] %> Notes The Microsoft documentation shows how to use this property to determine to how many levels the current folder is nested. For convenience, the following code demonstrates this: ParentFolder (File Object, Folder Object) 333 File Access ParentFolder (File Object, Folder Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. <% ' Dimension local variables. Dim fsoObject ' FileSystemObject Dim fdrObject ' Folder Object Dim intNestedLevel ' Level to which the folder is nested ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Using the GetFolder method of fsoObject, initialize a ' File object. Set fdrObject = fsoObject.GetFolder("PublicDocs.txt") ' Determine whether the current folder is a root folder ' or if it is nested. If fdrObject.IsRootFolder Then ' Folder is located directly off the drive letter or ' share name. Else ' For more on the ParentFolder property of the ' Folder object, see the following. Do Until fdrObject.IsRootFolder Set fdrObject = fdrObject.ParentFolder intNestedLevel = intNestedLevel + 1 Loop End If ...[additional code] %> ParentFolder (File Object, Folder Object) Obj.ParentFolder Returns a Folder object representing the folder in which the file or folder is located. This is a read-only property. Parameters None Example The following code demonstrates the use of the ParentFolder property when used with a File object and then with a Folder object. Note that, because Name is the default property of a Folder object, the code in the ASP page appears to treat the value returned by the ParentFolder property as a string. <% ' Dimension local variables. Dim fsoObject ' FileSystemObject Dim filObject ' File Object Dim fdrObject ' Folder Object Dim strFileParent ' Parent folder of file object Dim strFolderParent ' Parent folder of folder object 334 Chapter 18 – File Access Component Methods Reference ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Using the GetFile method of fsoObject, initialize the ' File object. Set filObject = fsoObject.GetFile("d:\docs\test.txt") ' Retrieve the name of the folder containing the file Test.TXT. ' In this example, the value of strFileParent is "docs". strFileParent = filObject.ParentFolder ' Using the GetFolder method of fsoObject, initialize ' the Folder object. Set fdrObject = fsoObject.GetFolder("d:\mystuff\docs") ' Retrieve the name of the folder that contains the ' folder "docs". In this example, the value of ' strFileParent is "mystuff". strFolderParent = fdrObject.ParentFolder ...[additional code] %> Methods Reference Close (TextStream Object) tsObj.Close Closes a text file that has been opened as a TextStream object. Parameters None Example <% ' Dimension local variables. Dim fsoObject ' FileSystemObject Dim tsObject ' TextStream Object ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Using the OpenTextFile method of fsoObject, initialize ' the File object. Set tsObject = fsoObject.OpenTextFile( _ "d:\docs\test.txt", ForReading, False) ' Read into the string the contents of the text file. strContents = tsObject.ReadAll ' Close the open text file. tsObject.Close ...[additional code] %> CopyFolder (FileSystemObject Object) 335 File Access CopyFolder (FileSystemObject Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Notes You can have only a limited number of open files in your application (similar to the use of open files in Visual Basic), so it is important to close all open text files after you are finished with them. Copy (File Object, Folder Object) obj.Copy strDestination [, blnOverWrite] Copies a file from one location to another. Parameters strDestination A string value that represents the full path of the location to which you wish to copy the current file. blnOverWrite A Boolean value that indicates whether a file of the same name as the file to be copied will be overwritten. The default is True. Example <% ' Dimension local variables. Dim fsoObject ' FileSystemObject Dim filObject ' File Object ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Using the GetFile method of fsoObject, initialize ' the File object. Set filObject = fsoObject.GetFile("d:\docs\test.txt") ' Copy the file to a temporary directory. filObject.Copy "e:\storage\temp\test_copy.txt", True ...[additional code] %> Notes The Copy method performs exactly the same function as the CopyFile and Copy- Folder methods of the FileSystemObject object. However, it is important to note that the CopyFile and CopyFolder methods will allow you to copy more than one file at a time. CopyFolder (FileSystemObject Object) fsoObj.CopyFolder strSource, strDestination [, blnOverWrite] Allows you to copy a folder and all of its contents from one location to another. 336 Chapter 18 – File Access Component CreateFolder (FileSystemObject Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Parameters strSource A string value that represents the full path of the location from which you wish to copy the current file. strDestination A string value that represents the full path of the location to which you wish to copy the current file. blnOverWrite A Boolean value that indicates whether a file of the same name as the file to be copied will be overwritten. The default is True. Example <% ' Dimension local variables. Dim fsoObject ' FileSystemObject ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Use the FileSystemObject object's CopyFolder method ' to copy the Temp directory and all its contents from ' the C drive to the D drive, overwriting if necessary. fsoObject.CopyFolder "c:\temp", "d:\temp", True ...[additional code] %> Notes If an error is raised when calling CopyFolder, the method stops immediately and does not reverse any actions already performed. The CopyFolder method is as fast as copying the folder using the command line. CreateFolder (FileSystemObject Object) fsoObj.CreateFolder(strFolderName) Creates a folder in a specified location. Parameters strFolderName A string value that represents the full physical path of the folder you want to create Example <% ' Dimension local variables. Dim fsoObject ' FileSystemObject ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") GetBaseName (FileSystemObject Object) 337 File Access GetBaseName (FileSystemObject Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. ' Create a new directory. fsoObject.CreateFolder("e:\storage\newdir") ...[additional code] %> Notes If you attempt to create a folder that already exists, an error will be raised. Delete (File Object, Folder Object) Obj.Delete blnForce Deletes a file or folder. Parameters blnForce A Boolean value that indicates whether to delete files or folders, even if they are marked as read-only Example <% ' Dimension local variables. Dim fsoObject ' FileSystemObject Dim filObject ' File Object ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Using the GetFile method of fsoObject, initialize the ' File object. Set filObject = fsoObject.GetFile("d:\docs\test.txt") ' Delete the TEST.TXT file—even if the file is marked ' as read-only. filObject.Delete True ...[additional code] %> Notes The Delete method of the File and Folder objects is functionally the same as the DeleteFile and DeleteFolder methods of the FileSystemObject object. If you use the Delete method of a Folder object, that folder and all of its contents will be deleted. The method will not warn you if you attempt to delete a directory that contains files. GetBaseName (FileSystemObject Object) fsoObj.GetBaseName(strPath) Extracts the name of a file—minus any file extension—from a full file path. 338 Chapter 18 – File Access Component GetParentFolderName (FileSystemObject Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Parameters strPath A string representing the full file path of a given file whose base name you want to retrieve Example <% ' Dimension local variables. Dim fsoObject ' FileSystemObject ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Using the GetBaseName method, retrieve the base ' names of several path strings. ' This example returns "searchstart" as the base name. Response.Write fsoObject.GetBaseName( _ "/apps/search/searchstart.asp") ' This example returns "search" as the base name. Response.Write fsoObject.GetBaseName("/apps/search/") ' This example returns "search" as the base name. Response.Write fsoObject.GetBaseName("/apps/search") ' This example returns "nofile" as the base name—even ' though the nofile.txt file does not exist. fsoObject.GetBaseName("/apps/search/nofile.txt") ...[additional code] %> Notes GetBaseName attempts to retrieve the base name for a file from a path string. If the last element in the path string is a folder, the folder name is returned—even if you include a closing slash (/) or backslash (\) character. The path string is not checked for its validity or its existence as a real path on the server. The method just looks at the path as a string. For this reason, the association of this method with the FileSystemObject object is deceiving, since no file manipulation actually occurs. GetParentFolderName (FileSystemObject Object) fsoObj.GetFolderName (strPath) Determines the name of the last parent folder in a given path string. Parameters strPath A string representing the full file path of a given file or folder whose parent folder name you are attempting to retrieve GetSpecialFolder (FileSystemObject Object) 339 File Access GetSpecialFolder (FileSystemObject Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Example <% ' Dimension local variables. Dim fsoObject ' FileSystemObject ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( "Scripting.FileSystemObject") ' Using the GetParentFolderName method, retrieve the ' parent folder names of several path strings. ' This example returns "search" as the parent folder ' name. Response.Write fsoObject.GetParentFolderName( _ "/apps/search/searchstart.asp") ' This example return "apps" as the parent folder name Response.Write fsoObject.GetParentFolderName ("/apps/search/") ' This example also returns "apps" as the parent folder ' name. Response.Write fsoObject.GetParentFolderName ("/apps/search") ' This example returns "nofile" as the parent folder ' name—even though nofile.txt does not exist. Response.Write fsoObject.GetParentFolderName( _ "/apps/search/nofile.txt") ...[additional code] %> Notes Like the GetBaseName method of the FileSystemObject object, the GetParentFolderName method acts only on the path string itself. The path string argument is not checked for validity or existence. GetSpecialFolder (FileSystemObject Object) fsoObj.GetSpecialFolder (intSpecialFolderType) Retrieves the full physical path of a special folder on the web server. Parameters intSpecialFolderType An integer that represents the type of special folder whose full physical path you wish to retrieve. The possible values for this parameter are as follows: Constant Value Description WindowsFolder 0 The Windows or WinNT folder into which your operating system was installed SystemFolder 1 The System folder into which libraries and device drivers are installed TemporaryFolder 2 The Temp folder as it is declared in the environment variables 340 Chapter 18 – File Access Component MoveFolder (FileSystemObject Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Example <% ' Dimension local variables. Dim fsoObject ' FileSystemObject ' Declare file constants. Const WindowsFolder = 0 Const SystemFolder = 1 Const TemporaryFolder = 2 ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Use GetSpecialFolder to retrieve the physical path ' for the Windows, System, and Temp directories. ' This example returns something similar to "C:\WINNT". fsoObject.GetSpecialFolder(WindowsFolder) ' This example returns something similar to ' "C:\WINNT\SYSTEM32". fsoObject.GetSpecialFolder(SystemFolder) ' This example returns something similar to ' "C:\WINNT\TEMP" fsoObject.GetSpecialFolder(TemporaryFolder) ...[additional code] %> Notes Note that you must explicitly declare constants for use with the file access components. MoveFolder (FileSystemObject Object) fsoObj.MoveFolder strSourcePath, strDestinationPath Moves a folder and all its contents from one location to another. Parameters strSourcePath A string representing the path to the folder or folders you wish to move. You can include wildcard characters in the strSourcePath argument in the last segment of the path only. strDestinationPath A string representing the path to which you wish to move the folders referenced in the strSourcePath parameter. The strDestinationPath parameter cannot contain any wildcard characters. Example <% ' Dimension local variables. OpenAsTextStream (File Object) 341 File Access OpenAsTextStream (File Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Dim fsoObject ' FileSystemObject ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Using the MoveFolder method, move all the folders ' under C:\APPS to the D: drive. fsoObject.MoveFolder "C:\APPS\*.*", "D:\" ...[additional code] %> Notes If you attempt to move a folder to a destination that is already a filename, you will receive an error. If the destination you provide represents the name of a preexisting folder, you will receive an error unless the source argument ends with a wildcard or a backslash (\). In this case, the source folder (or folders) and all its contents will be moved to the destination folder. For example, the following code results in an error: <% ' Assume FileSystemObject object is instantiated 'already. Also assume that D:\ apps already exists. fsoObject.MoveFolder "C:\apps", "d:\apps" %> whereas the following code would not result in an error: <% ' Assume FileSystemObject object is instantiated ' already. Also assume that D:\ apps already exists. fsoObject.MoveFolder "C:\apps\*.*", "d:\apps" ' This last line create an apps folder in the D:\apps ' folder (making D:\apps\apps) %> Note that if the web server experiences an error when calling MoveFolder, all actions stop without any rollback of previous actions. For example, if you attempt to move a series of three folders with all their contents and an error occurs on the third folder to be moved, the first two folders remain moved even though the third is not. You must include your own code to check for which files and folders were actually moved and which were not. If you attempt to move folders between volumes, the underlying operating system must support this, and user security on the web server must allow for this. OpenAsTextStream (File Object) filObj.OpenAsTextStream ([intAccessMode)[, intFormat]]) Opens a file and creates a TextStream object that you can use to read or modify the text file. 342 Chapter 18 – File Access Component OpenAsTextStream (File Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Parameters intAccessMode An integer that indicates the input/output mode in which you wish to open the text file. Possible values for this parameter are as follows: intFormat An integer that indicates the format of the file to be opened as a TextStream object. The possible values for this parameter are thought of as a single tristate value. The file is Unicode, ASCII, or whichever is the system default. Possible values for this parameter are: Example <% ' Dimension local variables. Dim fsoObject ' FileSystemObject Dim filObject ' File Object ' Declare File Access constants. Const ForAppending = 8 Const TristateTrue = -1 ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Using the GetFile method of fsoObject, initialize the ' File object. Set filObject = fsoObject.GetFile("d:\docs\test.txt") ' Use the OpenAsTextStream method to open the file for ' appending and in Unicode format. filObject.OpenAsTextStream(ForAppending, TristateTrue) %> Constant Value Description ForReading 1 The file will be opened as read-only and cannot be modified by the current TextStream object. ForWriting 2 The file will be opened for writing. If the file already exists when you call the OpenAsTextStream method, the original file is overwritten. ForAppending 8 The file is opened for appending only. You can only add characters to the end of this file. Constant Value Description TristateUseDefault –2 The file format will be the same as the default for the web server (Unicode or ASCII). TristateTrue –1 The file format will be Unicode. TristateFalse 0 The file format will be ASCII. ReadLine (TextStream Object) 343 File Access ReadLine (TextStream Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Notes The OpenAsTextStream method is virtually equivalent to the OpenTextFile method of the FileSystemObject object. The only difference is that the OpenAsTextStream method also can be used to create a new text file if one does not already exist. Note that you must explicitly declare constants for use with the File Access components. ReadLine (TextStream Object) tsObj.ReadLine The ReadLine method is similar to the Read method of the TextStream object in that it allows you to read from a text file into a string variable or compare the results of such a read to another entity. However, unlike the Read method, which uses an argument to determine how many characters to read, the ReadLine method reads all characters from the current pointer location to the next newline character. Parameters None Example <% ' Dimension local variables. Dim fsoObject ' FileSystemObject Dim filObject ' File Object Dim strBuffer ' Holding buffer ' Declare file access constants. Const ForReading = 1 Const TristateFalse = 0 ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Using the GetFile method of fsoObject, initialize the ' File object. Set filObject = fsoObject.GetFile("d:\docs\test.txt") ' Use the OpenAsTextStream method to open the file for ' reading and in ASCII format. filObject.OpenAsTextStream(ForReading, TristateFalse) ' Use the ReadLine method to read the next line of text ' from the text file into the strBuffer variable. strBuffer = filObject.ReadLine %> 344 Chapter 18 – File Access Component Write (TextStream Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. Notes After calling the ReadLine method, the current location of the pointer within the file is the character immediately after the last newline character or at the end of file marker. Note that you must explicitly declare constants for use with the File Access components. Write (TextStream Object) tsObj.Write(strWriteString) Writes a specified string to an open text file at the current location of the file pointer. Parameters strWriteString A string that represents the text you wish to write to the open file Example <% ' Dimension local variables. Dim fsoObject ' FileSystemObject Dim filObject ' File Object Dim strEnding ' Declare file access constants. Const ForAppending = 8 Const TristateFalse = 0 ' Initialize string variable. This string will be ' written to the end of the file opened next. strEnding = "This is the end, my only friend, the end..." ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Using the GetFile method of fsoObject, initialize the ' File object. Set filObject = fsoObject.GetFile("d:\docs\test.txt") ' Use the OpenAsTextStream method to open the file for ' appending and in Unicode format. filObject.OpenAsTextStream(ForAppending, TristateFalse) ' Write a short string to the end of the opened file. filObject.Write strEnding ...[additional code] %> Notes The Write method does not place any characters at the beginning or end of each written string. For this reason, if you use the Write method to add to a file, make WriteLine (TextStream Object) 345 File Access WriteLine (TextStream Object) ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved. sure that you include any desired characters (like spaces or newline characters) at the beginning or end of the strings you write to the file. WriteLine (TextStream Object) tsObj.WriteLine([strWriteString]) Writes a string’s value into an open file at the location of the pointer within the file. This method also writes a newline character to the end of the added string. Otherwise, it is exactly the same as the Write method. strWriteString A string that represents the text you wish to write to the open text file Example <% ' Dimension local variables. Dim fsoObject ' FileSystemObject Dim filObject ' File Object Dim strEnding ' Declare file access constants. Const ForAppending = 8 Const TristateFalse = 0 ' Initialize a string variable that will be written to ' the end of the file opened next. strEnding = "This is the end, my only friend, the end..." ' Instantiate the FileSystemObject variable. Set fsoObject = Server.CreateObject( _ "Scripting.FileSystemObject") ' Using the GetFile method of fsoObject, initialize the ' File object. Set filObject = fsoObject.GetFile("d:\docs\test.txt") ' Use the OpenAsTextStream method to open the file for ' appending and in Unicode format. filObject.OpenAsTextStream(ForAppending, TristateFalse) ' Write a short string plus a newline character to the ' end of the opened file. filObject.WriteLine strEnding ...[additional code] %> Notes After calling the WriteLine method, the file pointer will point to the character located immediately after the newline character added to the file. 346 ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved.