Tech Note 09: File System Control

April 02, 2008


This control is used to access and organize disks, directories and files. It is included with NS Basic. The information in the document is for the most part copied from the official documentation on NewObject's website. For further information, please refer to the official documentation. The information on this page is copyright ZmeY soft and published with their permission.

Background: This control replaces the MSCEFile control in NS Basic/CE and the FileSystemObject (FSO) in NS Basic/Desktop. Code written using this control is interoperable between both NS Basic products.

The File System Control is used to access and organize the disks, directories and files of a system. It is also used to open files for access - see Tech Note 08 for more information on Files.

The methods and properties documented here are a subset of the full capabilities of this control. To see the rest of the features, look at the full documentation from NewObjects. The features not included here will still work well with NS Basic, but are for advanced users.

The SFMain object is very similar to Microsoft's FileSystemObject (FSO). Many of its methods and properties duplicate the behaviour of the similar members of the FSO. However this library provides abstraction and access techniques which include more than just files and directories, therefore SFMain object differs from FSO but has the equivalent role - a root object providing general information and access to the other objects. In typical case you create it and all the other objects you may need later, are created by calling some method of the SFMain object.

Installation: This control requires that NewObjectsPack1.dll be installed and registered.

Creation:

AddObject "newObjects.utilctls.SFMain", "FS"
collection.gif (368 bytes) Drives Collection of the logical drives
method.gif (107 bytes) CreateDirectory Creates a directory in the file system.
method.gif (107 bytes) CreateFile Creates file in the file system and returns a SFStream object for it.
method.gif (107 bytes) OpenDirectory Opens a Directory and returns an object for it.
method.gif (107 bytes) OpenFile Opens a file from the file system and returns a SFStream object for it
method.gif (107 bytes) FileExists Checks if the file exists.
method.gif (107 bytes) FolderExists Checks if the folder exists.
method.gif (107 bytes) Exists Checks if the file or folder exists.
method.gif (107 bytes) DeleteFile Deletes the file from the file system.
method.gif (107 bytes) DeleteFolder Deletes the folder and its contents.
method.gif (107 bytes) CopyFile Copies file(s).
method.gif (107 bytes) GetDriveName Returns the drive part of a path.
method.gif (107 bytes) GetExtensionName Returns the extension of the file name.
method.gif (107 bytes) GetFileName Returns the file name from a given path.
method.gif (107 bytes) GetFilePath Returns the path name of the directory containing the file.

Note: Not all methods are supported on all platforms.


Drives

Returns a collection of SFDrive objects - one for each drive on the system.

Syntax:

Set drvs = FS.Drives

Examples:

AddObject "newObjects.utilctls.SFMain", "Main"
Set drvs = FS.Drives
For Each drv In drvs
   MsgBox drv.DriveLetter & " - " & drv.FreeSpace & " bytes" & "<BR>"
Next 

Remarks:

The following properties are returned in the Drive object: DriveType, DriveLetter, FileSystem, FreeSpace, SerialNumber, TotalSize, VolumeName. On CE devices, only the main store is returned.


CreateDirectory

Create a new directory.

Syntax:

Set Dir = FS.CreateDirectory(path[, flags])

Examples:

AddObject "newObjects.utilctls.SFMain", "Main"
Set Dir = FS.CreateDirectory("C:\myDir)
          

Remarks:

Flags are:


CreateFile

Create a new file. Returns a File (SFStream) Object.

Syntax:

Set newFile = FS.CreateFile(path[, flags])

Examples:

AddObject "newObjects.utilctls.SFMain", "Main"
Set newFile = FS.CreateFile("C:\myDir\Temp.txt")
          

Remarks:

Flags are:


OpenDirectory

Open an existing Directory. Returns a Directory (SFStorage) Object.

Syntax:

Set Dir = FS.OpenDirectory(path[, flags])

Examples:

AddObject "newObjects.utilctls.SFMain", "Main"
Set Dir = FS.OpenDirectory"C:\myDir")
          

Remarks:

Flags are:

Useful members of the returned object include (There are others as well - see
full documentation)

OpenFile

Open an existing file. Returns a File (SFStream) Object.

Syntax:

Set Dir = FS.OpenFile(path[, flags])

Examples:

AddObject "newObjects.utilctls.SFMain", "Main"
Set Dir = FS.OpenFile("C:\myDir\Temp.txt")
          

Remarks:

Flags are:


FileExists

Check if a file exists.

Syntax:

FileExists(path)

Examples:

If FS.FileExists("C:\myDir\Temp.txt") then MsgBox "File Exists"
          

Remarks:

Returns True if file exists.

FolderExists

Check if a folder exists.

Syntax:

FolderExists(path)

Examples:

If FS.FolderExists("C:\myDir") then MsgBox "Folder Exists"
          

Remarks:

Returns True if folder exists.

Exists

Check if a file or folder exists.

Syntax:

Exists(path)

Examples:

If FS.Exists("C:\myDir") then MsgBox "Folder or Folder Exists"
          

Remarks:

Return Values:

DeleteFile

Delete an existing file.

Syntax:

FS.DeleteFile(path[, BoolForce])

Examples:

AddObject "newObjects.utilctls.SFMain", "Main"
FS.DeleteFile("C:\myDir\Temp.txt")
          

Remarks:

Set BoolForce to True to delete even if file is Read only. Default is false.


DeleteFolder

Delete an existing folder and all its contents, recursively.

Syntax:

FS.DeleteFolder(path[, BoolForce])

Examples:

AddObject "newObjects.utilctls.SFMain", "Main"
FS.DeleteFolder("C:\myDir")
          

Remarks:

Set BoolForce to True to delete even if Read only. Default is false.


CopyFile

Copies file (or files if wildcards are used) into the file system.

Syntax:

FS.CopyFile( source, destination [, fReplace = True])

Parameters:

source - Source file full path name or path with wildcards.

destination - Destination full path name of a file or directory. No wildcards are allowed in this parameter. If wildcards are used in the source parameter the destination should be a directory.

fReplace - Optional Boolean flag. The default value is True. Indicates if file replace is allowed in the destination if a file with the same name already exists in that location.

Examples:

AddObject "newObjects.utilctls.SFMain", "Main"
FS.CopyFile("C:\Directory\*.txt","C:\MyTexts")
' Copy all the text files
FS.CopyFile("C:\a.txt","C:\b.txt")
' Copy a.txt into b.txt file

Remarks:

If fReplace is set to False the method will fail if a file with the same name exists in the destination location.

Using full path names for both source and the destination allows the application to copy the selected file under new file name.

If wildcards are used in the source and a full file path (not directory) is used in the destination parameter no error will occur but the source files matching the wildcards will be copied one by one over the same file and the last one will remain as result.

For copy/move operations across the different storage types see the members of SFStorage and SFStream objects.

If the parameters contain non-full path names (file names or relative paths) they are assumed relative to the current work directory as usual.


GetDrive

Extracts the drive name portion of the path

Syntax:

var = FS.GetDrive(path)

Examples:

AddObject "newObjects.utilctls.SFMain", "Main"
myDriveName = FS.GetDrive("C:\myDir\Temp.txt") 'result is "C:"
          

Remarks:

Returns a string containing the drive name portion from the path parameter. In case of mapped drive it will be C:, D: etc. In case of network path it will be something like \\server\share\. The method never fails. Instead an empty string will be returned if the path does not contain recognizable drive name portion.

The method supports mapped and windows networking paths (\\server\share\...).

This method performs only textual analysis - there is no guarantee that the returned value matches any existing drive on the system.


GetExtensionName

Extracts the extension name portion of the path

Syntax:

var = FS.GetExtensionName(path)

Examples:

AddObject "newObjects.utilctls.SFMain", "Main"
myExtensionName = FS.GetExtensionName("C:\myDir\Temp.txt") 'result is ".txt"
          

Remarks:

The file name extension is the portion of the file name after the last "." character in the last file or directory name in the path. The path parameter can be full path, relative path or file/directory name only. If no extension presents an empty string will be returned.

In most cases directories are named not using extensions in their names. However "name extension" term is applicable for them as well - and can be quite useful for certain applications.


GetFileName

Extracts the file name portion of the path

Syntax:

var = FS.GetFileName(path)

Examples:

AddObject "newObjects.utilctls.SFMain", "Main"
myExtensionName = FS.GetFileName("C:\myDir\Temp.txt") 'result is "Temp"
          

Remarks:

The method can be used to extract file or directory names as well. Its behavior for directories depends on the syntax used - if there is trailing "\" in the passed path specification the file/directory name is empty.

Note that the analysis performed is textual - the operation can be performed on existing and non-existing objects. This allows the method to be used in code intended to "plan" future file/directory creation tasks for example.


GetFilePath

Extracts the path name portion of the path

Syntax:

var = FS.GetFilePath(path)

Examples:

AddObject "newObjects.utilctls.SFMain", "Main"
myPathName = FS.GetFilePath("C:\myDir\Temp.txt") 'result is "C:\myDir"
          

Remarks:

The method can be used to extract file or directory names as well. Its behavior for directories depends on the syntax used - if there is trailing "\" in the passed path specification the file/directory name is empty.

Note that the analysis performed is textual - the operation can be performed on existing and non-existing objects. This allows the method to be used in code intended to "plan" future file/directory creation tasks for example.