cFilesystem class

The cFilesystem class is a collection of functions to access files and directories through windows kernel API.

This help file is divided into tree sections.

  • Properties
  • Binary file access
  • File and directory access

This class is not limited to handle file sizes of 2 GB but can handle huge files sizes. You can also have as many open file connections as you like. Also you can get a status for each of the file and directory operations to tell if the operation was successful. This is just some of the benefits you gain when using this class.

All filenames used in this class is in OEM format. Any method that return filenames are also in OEM format. You do not have to worry about converting filenames into ANSI format to be able to access filenames with international characters. This is all taking care of by the cFilesystem class.

There are also some helper methods included. These are used by other parts of cFilesystem you can use them to if you find them useful.

Example of use:

You may want to create an object of this class in your .src file like this:

Use cFilesystem.pkg
Object oFilesystem is a cFilesystem
End_Object

This ensures that you have easy access to the filesystem object from all over your application. But this is not a requirement. You can easily create an object of the cFilesystem class i.e. in a view where it is needed.

In the example code for the rest of this help file it is assumed that there is an object called oFilesytem of the cFilesystem class instantiated earlier in the application like the example above.

Copyright (c) 2001-2009 NOVAX A/S


Properties
Navigation: cFilesystem class >

Properties

pbEOF - End of the binary file had been reached.

pbError - Error has occurred during file or directory operation.

pbErrorAsVDFError - How are error messages shown.


pbEOF
Navigation: cFilesystem class > Properties >

pbEOF

Type: Boolean

Default value: False

True then the end of the binary file had been reached - not when $1A (EOF) is met.


pbError
Navigation: cFilesystem class > Properties >

pbError

Type: Boolean

Default value: False

True if any error has occurred during any file or directory operations.

This is set false at the beginning for every file or directory operation. If some error occurs during the operation, the pbError is then set true. Therefore you can check this property's value to see if the operation has failed.

Most messages returns this status but there are a few other messages that returns other information like FileSearch . So to find out whether the FileSearch message did succeed but did not find any files or an error occurred you have to check the status of this property.


pbErrorAsVDFError
Navigation: cFilesystem class > Properties >

pbErrorAsVDFError

Type: Boolean

Default value: False

If error messages should be called with the ERROR command set this to true. Otherwise error messages is shown as a warning message to user with OK button and an exclamation icon.


Binary file access
Navigation: cFilesystem class >

Binary file access

Binary file access is used for accessing files in a binary mode. This means that you can read all data from a binary file without worrying about if the method changes any of the data. You can also write binary data back to the file. You can control if the binary file is to be opened or created in shared or exclusive mode. Or even just in read only mode. This makes it possible to read and write data from a file that is opened by other applications.

All binary file access is done with windows kernel api calls instead of using the Direct_Input or Direct_Output commands. This has another advances that it is possible to get a return status for whether the file operation was successful or not.

All methods for binary file access starts with "BinaryFile" in the message name.


BinaryFileNextFilenumber
Navigation: cFilesystem class > Binary file access >

BinaryFileNextFilenumber

Type: Function, Return type: Integer

Parameters: none

Returns the next available file number for a binary file access to be used with the BinaryFileOpen method. It is not nessasary to get this number as you can specify any number you like for BinaryFileOpen. However doing so you have to be careful not to use a number already in use. If you try to use a filenumber that is in use you will get an error.

Note that the first available file number is 0. This is a perfectly legal number to use for the binary file access.

Example of use:

Integer iFileNumber
Get BinaryFileNextFilenumber of oFilesystem to iFileNumber


BinaryFileOpen
Navigation: cFilesystem class > Binary file access >

BinaryFileOpen

Type: Function, Return type: Boolean

Parameters: Integer iFilenumber String sFilename {Boolean bShared {Boolean bCreate {Boolean bReadOnly}}}

iFilenumber
This can be 0 or any positive number that you want to access the opened file with any of the other binary file methods. This can also be the number retrieved from the BinaryFileNextFilenumber function. It is not necessary to get this number from the BinaryFileNextFilenumber function. If you specify your own filenumber you have to be careful not to use a number already in use. If you try to use a filenumber that is in use you will get an error.

sFilename
The filename of the file to be opened or created. For more information. see File Names, Paths, and Namespaces on msdn.

bShared
If true the file is opened with both read and write access in shared mode.
If false or not applied the file is opened in exclusive access mode.

bCreate
If true the file is created if it does not exists. If the file exists it will open the file normally.
If false or not applied the file has to exists for the method to succeed. Otherwise an error is reported.

bReadOnly
If true the file is opened in read mode only.
If false or not applied the file is opened in both read and write mode.

This opens a file for binary access if it exists before the methods is called. If bCreate is true the file is created if it does not exists before it is opened.

The function returns true if the file was opened without error.

You can combine any of the bShared, bCreate and bReadOnly modes as you wish. If you for example opens a file with bShared and bReadOnly to true, the file is opened in shared read only mode. Note that the file has to exists for the method to success. Further more if another application has opened the file in advance it too has to have the file opened in shared read only mode. Otherwise an error occurs.

You have to match the same access modes when opening a file as the first application used when it opened the file. You can not open a file with shared read and write mode if the file has already been opened earlier in the application or with another application that used shared read only mode. More information, see Creating and Opening Files on msdn.

Example of use:

Integer iFileNumber
Boolean bOk
Get BinaryFileNextFilenumber of oFilesystem to iFileNumber
Get BinaryFileOpen of oFilesystem iFileNumber "D:\Test\Thisfile.bin" to bOk

This will open an existing file "D:\Test\Thisfile.bin" for binary exclusive read and write access.

Example of use:

Integer iFileNumber
Boolean bOk
Get BinaryFileNextFilenumber of oFilesystem to iFileNumber
Get BinaryFileOpen of oFilesystem iFileNumber "D:\Test\Thisfile2.bin" False True to bOk

This will create a file "D:\Test\Thisfile2.bin" if it does not exists and then open the file. If it does exist it will open the file. The file is opened in binary exclusive read and write mode in both cases.


BinaryFileClose
Navigation: cFilesystem class > Binary file access >

BinaryFileClose

Type: Function, Return type: Boolean

Parameters: Integer iFilenumber

iFilenumber
This is the filenumber that where previously used to open the file with the BinaryFileOpen function.

This closes a file that where previously opened with the BinaryFileOpen function. It also releases the filenumber so it can be used again by a subsequent call to the BinaryFileNextFilenumber function.

The function returns true if the file was closed without error.

Example of use:

Integer iFileNumber
Boolean bOk
Get BinaryFileNextFilenumber of oFilesystem to iFileNumber
Get BinaryFileOpen of oFilesystem iFileNumber "D:\Test\Thisfile.bin" to bOk
Get BinaryFileClose of oFilesystem iFileNumber to bOk


BinaryFileRead
Navigation: cFilesystem class > Binary file access >

BinaryFileRead

Type: Function, Return type: Integer

Parameters: Integer iFilenumber Integer iNumberOfBytes String ByRef sReadBuffer

iFilenumber
This is the filenumber that where previously used to open the file with the BinaryFileOpen function.

iNumberOfBytes
The number of bytes you want to read from the binary file.

sReadBuffer
The read buffer where data from the binary file are placed.

This read a specific number of bytes from a binary file that where previously opened with the BinaryFileOpen function and places the data in the sReadBuffer variable. The reading starts from the current binary file position. When the reading is done the current binary file position is moved according to the actual bytes read.

The function returns the number of bytes actually read from the binary file. If the function returns 0 either the end of the binary file has been reached or an error has occurred.

You can check the pbEOF property to see if the end of file has been reached.

You can check the pbError property to see if an error has occurred.

The data read from the file are placed in sReadBuffer and the function returns the number of bytes actually read. To speed up the reading process you should read a block of data at a time instead of just one byte at a time. A good number to use for iNumberOfBytes could be 2000 but you may want to try out different sizes to find one that works best for you.

No error occurs if you try to read past the end of the binary file.

Note that the number of bytes to read at a time must not exceed the argument size otherwise an error occurs. You can set argument size with the set_argument_size command. However you could also get the current argument size with the get_argument_size command and read blocks of data in that quantity. Refer to the Visual DataFlex Help for more information on argument size.

Example of use:

Integer iFileNumber iBytesRead
Boolean bOk bEOF
String sData
Get BinaryFileNextFilenumber of oFilesystem to iFileNumber
Get BinaryFileOpen of oFilesystem iFileNumber "D:\Test\Thisfile.bin" to bOk
If (bOk = True) Begin
    Repeat

        Get BinaryFileRead of oFilesystem iFileNumber 2000 (&sData) to iBytesRead

        // Process the data.
        Get pbEOF of oFilesystem to bEOF
    Until (iBytesRead = 0 or bEOF = True)
    Get BinaryFileClose of oFilesystem iFileNumber to bOk
End

In this example the file "D:\Test\Thisfile.bin" is read from the beginning to the end of the binary file in blocks of 2000 bytes at a time. It tests for the pbEOF property to se if the end of file has been reached. It is not nessasary to do that. You could just stop when the number of bytes read is zero. But by checking the pbEOF property you can skip the last call to the BinaryFileRead function as it would return nothing anyway.


BinaryFileWrite
Navigation: cFilesystem class > Binary file access >

BinaryFileWrite

Type: Function, Return type: Boolean

Parameters: Integer iFilenumber String ByRef sWriteData

iFilenumber
This is the filenumber that where previously used to open the file with the BinaryFileOpen function.

sWriteData
The write buffer for the data that are to be written to the binary file.

This writes the data from the write buffer variable to a binary file that where previously opened with the BinaryFileOpen function. The binary file must be opened with both read and write mode. The writing starts from the current binary file position. When the writing is done the current binary file position is moved according to the actual bytes written.

The function returns true if all the data was written without any errors.

To speed up the writing process you should write a block of data at a time instead of just one byte at a time.

If you write past the end of the binary file the data are automatically appended to the binary file with the remaining data. If you have set the binary file pointer past the end of the file it is extended to the point of where the current binary file pointer is and then the data are written.

Example of use:

Integer iFileNumberFrom iBytesRead iFileNumberTo iBlockSize
Boolean bOk bEOF bWrittenOk
String sData
Get_Argument_Size to iBlockSize
Get BinaryFileNextFilenumber of oFilesystem to iFileNumberFrom
Get BinaryFileOpen of oFilesystem iFileNumberFrom "D:\Test\Thisfile.bin" to bOk
If (bOk = True) Begin
    Get BinaryFileNextFilenumber of oFilesystem to iFileNumberTo
    Get BinaryFileOpen of oFilesystem iFileNumberTo "D:\Test\Thisfilecopy.bin" False True to bOk

    If (bOk = True) Begin
        Repeat
            Get BinaryFileRead of oFilesystem iFileNumberFrom iBlockSize (&sData) to iBytesRead
            If (iBytesRead > 0) Begin

                Get BinaryFileWrite of oFilesystem iFileNumberTo (&sData) to bWrittenOk

            End
            Get pbEOF of oFilesystem to bEOF
        Until (iBytesRead = 0 or bEOF = True or bWrittenOk = False)
        Get BinaryFileClose of oFilesystem iFileNumberTo to bOk
    End
    Get BinaryFileClose of oFilesystem iFileNumberFrom to bOk
  End

This example makes a complete copy of "D:\Test\Thisfile.bin" to "D:\Test\Thisfilecopy.bin". It does this by readning as many bytes as possible within the current argument size at a time. Note the use of "by reference" for the data. This means that the data is never copied between methods ones it is stored in the sData variable. Even the call to the windows kernel API uses the sData variable directly.

Example of use:

Integer iFileNumber
Boolean bOk bWrittenOk
Get BinaryFileNextFilenumber of oFilesystem to iFileNumber
Get BinaryFileOpen of oFilesystem iFileNumber "D:\Test\Thisfile.bin" to bOk

If (bOk = True) Begin
    Get BinaryFileWrite of oFilesystem iFileNumber "This is some binary data or text." to bWrittenOk
    Get BinaryFileClose of oFilesystem iFileNumber to bOk
End

Here is the text "This is some binary data or text." written to the beginning of the "D:\Test\Thisfile.bin" binary file. It does not matter if you specify the text directly or with a string variable. Note that the binary file has to exists and it does not truncate the binary file. It just replaces whatever was in the beginning of the binary file with the text. The rest of the binary file is untouched (if it is longer that the length of the text written).


BinaryFileWriteHex
Navigation: cFilesystem class > Binary file access >

BinaryFileWriteHex

Type: Function, Return type: Boolean

Parameters: Integer iFilenumber String ByRef sWriteHex

iFilenumber
This is the filenumber that where previously used to open the file with the BinaryFileOpen function.

sWriteData
The write buffer for the data in hexadecimal format that are to be written to the binary file.

This writes Hexadecimal formatted data to a binary file by first translating the hexadecimal format to binary data and then call the BinaryFileWrite method. Please see BinaryFileWrite for more information on writing data to a binary file.

The function returns true if all the hexadecimal formatted data was written without any errors.

If the formatted data can not be translated as a valid hexadecimal format to binary data an error occurs and nothing are written to the binary file.

Example of use:

Integer iFileNumber
Boolean bOk bWrittenOk
Get BinaryFileNextFilenumber of oFilesystem to iFileNumber
Get BinaryFileOpen of oFilesystem iFileNumber "D:\Test\Thisfile.bin" to bOk

If (bOk = True) Begin
    Get BinaryFileWriteHex of oFilesystem iFileNumber "4E4F56415820412F53" to bWrittenOk
    Get BinaryFileClose of oFilesystem iFileNumber to bOk
End

This write the text "NOVAX A/S" formatted as hexadecimal values to the beginning of the "D:\Test\Thisfile.bin" binary file.


BinaryFileSize
Navigation: cFilesystem class > Binary file access >

BinaryFileSize

Type: Function, Return type: BigInt

Parameters: Integer iFilenumber

iFilenumber
This is the filenumber that where previously used to open the file with the BinaryFileOpen function.

This receives the current file size of a binary file that where previously opened with the BinaryFileOpen function.

The function returns -1 if an error occurred.

Example of use:

Integer iFileNumber
Boolean bOk
BigInt biFileSize
Get BinaryFileNextFilenumber of oFilesystem to iFileNumber
Get BinaryFileOpen of oFilesystem iFileNumber "D:\Test\Thisfile.bin" to bOk

If (bOk = True) Begin
    Get BinaryFileSize of oFilesystem iFileNumber to biFileSize
    Get BinaryFileClose of oFilesystem iFileNumber to bOk
End

This gets the current file size of the "D:\Test\Thisfile.bin" binary file.


BinaryFilePosition
Navigation: cFilesystem class > Binary file access >

BinaryFilePosition

Type: Get/Set Property, Type: BigInt

Parameters: Integer iFilenumber

iFilenumber
This is the filenumber that where previously used to open the file with the BinaryFileOpen function.

It gets the current file position of a binary file that where previously opened with the BinaryFileOpen function. Note that this property only gets updated when requesting its value.

It has the value of -1 if an error occurred while trying to retrieve the current file position of the binary file.

When this property is set the current file position of the binary file is moved to the location specified by the value. It does not yet extend the file size to the new file position until one of the BinaryFileWrite, BinaryFileWriteHex or BinaryFileEndOfFile methods are used.

Example of use:

Integer iFileNumber
Boolean bOk
BigInt biFileposition
Get BinaryFileNextFilenumber of oFilesystem to iFileNumber
Get BinaryFileOpen of oFilesystem iFileNumber "D:\Test\Thisfile.bin" to bOk

If (bOk = True) Begin
    Get BinaryFilePosition of oFilesystem iFileNumber to biFileposition
    Get BinaryFileClose of oFilesystem iFileNumber to bOk
End

This gets the current file position of the "D:\Test\Thisfile.bin" binary file. In this example the BinaryFilePosition function returns zero because the binary file has just been opened.

Example of use:

Integer iFileNumber
Boolean bOk bWrittenOk
BigInt biFileposition
Get BinaryFileNextFilenumber of oFilesystem to iFileNumber
Get BinaryFileOpen of oFilesystem iFileNumber "D:\Test\Thisfile.bin" to bOk

If (bOk = True) Begin
    Set BinaryFilePosition of oFilesystem iFileNumber to 10000
    Get BinaryFileWrite of oFilesystem iFileNumber "Some data" to bWrittenOk
    Get BinaryFilePosition of oFilesystem iFileNumber to biFileposition
    Get BinaryFileClose of oFilesystem iFileNumber to bOk
End

In this example the "D:\Test\Thisfile.bin" binary file is opened and the current file position is set to 10000. Then the text "Some data" is written to the file. If the file was not large enough to start writing at file position 10000 it is extended to a file size of 10000 and then the data is written. Then the current binary file position is requested and the property's value is now 10009.


BinaryEndOfFile
Navigation: cFilesystem class > Binary file access >

BinaryEndOfFile

Type: Set Property, Type: BigInt

Parameters: Integer iFilenumber

iFilenumber
This is the filenumber that where previously used to open the file with the BinaryFileOpen function.

It sets the end of file of a binary file that where previously opened with the BinaryFileOpen function. Note that this property is a write only property.

When set the binary file is truncated or extended to the specified file position. If the specified file position is -1 the current binary file position is used as the End Of File position.

Example of use:

Get BinaryFileNextFilenumber of oFilesystem to iFileNumber
Get BinaryFileOpen of oFilesystem iFileNumber "D:\Test\Thisfile.bin" to bOk

If (bOk = True) Begin
    Set BinaryFileEndOfFile of oFilesystem iFileNumber to 5000
    Get BinaryFileClose of oFilesystem iFileNumber to bOk
End

The "D:\Test\Thisfile.bin" binary file is either truncated or extended to have a file size of 5000.


BinaryFileHandle
Navigation: cFilesystem class > Binary file access >

BinaryFileHandle

Type: Function, Return type: Handle

Parameters: Integer iFilenumber

iFilenumber
This is the filenumber that where previously used to open the file with the BinaryFileOpen function.

This receives the open windows file handle of a binary file that where previously opened with the BinaryFileOpen function. If there is no open file handle with the specified filenumber the function returns zero.

This function is only used if you need to make your own low-level windows kernel API calls.


File and directory access
Navigation: cFilesystem class >

File and directory access

The file and directory access methods are used for copying, moving, deleting/removing and searching for files and directories with windows kernel API. This makes it possible to have a return status for whether the file operation was successful or not. The methods are also used to get information like file size, last write date, associated icon and much more.

All methods for file and directory access starts with "File" or "Directory" in the message name.


FileExists
Navigation: cFilesystem class > File and directory access >

FileExists

Type: Function, Return type: Boolean

Parameters: String sFilePathMask {Integer iFileDirMode}

sFilePathMask
The name of the file or directory to search for, or partial name if wildcards are used.

iFileDirMode
Directory search mode. This can be one of these:

  • DIRMODE_FILES_ONLY (default)
  • DIRMODE_DIRECTORIES_ONLY
  • DIRMODE_FILES_AND_DIRECTORIES

Searches a directory for a file or subdirectory with a name that matches the sFilePathMask. Wildcards can be an asterisk (*) or a question mark (?).

The function returns true if a file or directory could be found.

If iFileDirMode is DIRMODE_FILES_ONLY or not applied the search is limited to files only. If the mode is DIRMODE_DIRECTORIES_ONLY the search is limited to subdirectories only. The last option DIRMODE_FILES_AND_DIRECTORIES includes both the files and subdirectories.

Example of use:

Boolean bFound
Get FileExists of oFilesystem "D:\Test\Thisfile.bin" to bFound

This searches for a specific file called "Thisfile.bin" located in the directory "D:\Test". If it is found the function returns true.

Example of use:

Boolean bFound
Get FileExists of oFilesystem "D:\Test\This*.*" to bFound

This searches the "D:\Test" directory for any file that has a filename that begins with "This". If such a file are found it returns true. Note that the default behaviour is to skip any subdirectories during the search. So this example does not return true even if such a subdirectory would have a name that starts with "This".

Example of use:

Boolean bFound
Get FileExists of oFilesystem "D:\Test\This*.*" DIRMODE_FILES_AND_DIRECTORIES to bFound

Now both filenames and subdirectorynames are search for a name that begins with "This".


FileDelete
Navigation: cFilesystem class > File and directory access >

FileDelete

Type: Function, Return type: Boolean

Parameters: String sFilename {Integer iRetryAttempts}

sFilename
Full path and filename for the file to be deleted.

iRetryAttempts
You can select a maximum number of retries that the function can do if it does not succeed the first time. If the fileoperation is not sucessfull it will wait one second before another attempt is made. It will continue to do so until either the fileoperation succeed or the maximum number of retries has been reached.

This deletes an existing file with the specified name.

The function returns true if the file was deleted.

For removing a directory use the DirectoryRemove method.

Example of use:

Boolean bDeleted
Get FileDelete of oFilesystem "D:\Test\Thisfile.bin" to bDeleted

This will delete the "D:\Test\Thisfile.bin" file.


FileRename
Navigation: cFilesystem class > File and directory access >

FileMove and FileRename

Type: Function, Return type: Boolean

Parameters: String sExistingFileName String sNewFileName {Integer iRetryAttempts}

sExistingFileName
Full path and filename for the file or directory to be moved.

sNewFileName
Full path and filename for the new location of the file or directory.

iRetryAttempts
You can select a maximum number of retries that the function can do if it does not succeed the first time. If the fileoperation is not sucessfull it will wait one second before another attempt is made. It will continue to do so until either the fileoperation succeed or the maximum number of retries has been reached.

This moves a file or directory (with all its children) from one location to another.

The function returns true if the move was done without error.

FileRename has the same function as FileMove.

It is possible to move a directory with all its children but the function will fail on directory moves when the destination is on a different volume. For more information, see MoveFile Function at msdn. Also have a look on the About cFilesystem .

Example of use:

Boolean bMoved
Get FileMove of oFilesystem "D:\Test\Thisfile.bin" "F:\Test\Thisfile.bin" to bMoved

This will move the "Thisfile.bin" from "D:\Test" to "F:\Test" while keeping the filename.


FileCopy
Navigation: cFilesystem class > File and directory access >

FileCopy

Type: Function, Return type: Boolean

Parameters: String sExistingFileName String sNewFileName {Boolean bFailIfExists {Integer iRetryAttempts}}

sExistingFileName
Full path and filename for the file to be copied.

sNewFileName
Full path and filename for the new location of the file.

bFailIfExists
If this is true and a file with the same name already exists at the destination the file copy is aborted and an error occurs. If this is false or not applied any existing file with the same name will be replaced.

iRetryAttempts
You can select a maximum number of retries that the function can do if it does not succeed the first time. If the fileoperation is not sucessfull it will wait one second before another attempt is made. It will continue to do so until either the fileoperation succeed or the maximum number of retries has been reached.

This copies a file from one location to a new location as a new file.

The function returns true if the file copy was done without error.

Example of use:
Boolean bCopied
Get FileCopy of oFilesystem "D:\Test\Thisfile.bin" "F:\Test\Thisfile.bin" to bCopied

This will copy the "Thisfile.bin" from "D:\Test" to "F:\Test" while keeping the filename. If the file "F:\Test\Thisfile.bin" exists before the copy, it will be replaced without an error.


FileSize
Navigation: cFilesystem class > File and directory access >

FileSize

Type: Function, Return type: BigInt

Parameters: String sFilename

sFilename
Full path and filename for the file that you wish to get the file size from.

The function returns the file size of the specified file.

The function returns -1 if an error occurs.

Example of use:

BigInt biFileSize
Get FileSize of oFilesystem "D:\Test\Thisfile.bin" to biFileSize

This returns the current file size of the "D:\Test\Thisfile.bin" file.


FileDate
Navigation: cFilesystem class > File and directory access >

FileDate

Type: Function, Return type: Date

Parameters: String sFilename

sFilename
Full path and filename for the file that you wish to get the file date from.

The function returns the last write date of the specified file.

The function returns zero if an error occurs.

Example of use:

Date dFileDate
Get FileDate of oFilesystem "D:\Test\Thisfile.bin" to dFileDate

This returns the last write date of the "D:\Test\Thisfile.bin" file.


FileIcon
Navigation: cFilesystem class > File and directory access >

FileIcon

Type: Function, Return type: Handle

Parameters: String sFilename

sFilename
Full path and filename for the file that you wish to get the associated icon from.

This function takes an icon found in a file or an icon found in an associated executable file for the specified filename and returns a handle for the icon.

When the icon is no longer needed, close it by calling the DestroyFileIcon procedure.

The function returns zero if an error occurs.

Example of use:

Handle hIcon
Get FileIcon of oFilesystem "D:\Test\Thisfile.bin" to hIcon
// Process the icon
Send DestroyFileIcon of oFilesystem hIcon

This gets an icon handle for the ".bin" associated executable file. After the icon has been processed the icon handle is destroyed.


FileSearch
Navigation: cFilesystem class > File and directory access >

FileSearch

Type: Function, Return type: tsSearchResult[]

Parameters: String sFilePathMask {Integer iFileDirMode {Boolean bReturnOnlyOne}}

sFilePathMask
The name of the file or directory to search for, or partial name if wildcards are used.

iFileDirMode
Directory search mode. This can be one of these:

  • DIRMODE_FILES_ONLY
  • DIRMODE_DIRECTORIES_ONLY
  • DIRMODE_FILES_AND_DIRECTORIES (default)

bReturnOnlyOne
If this is set true the function will return only one result item. If there are not found any items the function returns an empty array without any errors.

Searches a directory for files and subdirectories with names that matches the sFilePathMask. Wildcards can be an asterisk (*) or a question mark (?).

The function returns a struct of tsSearchResult for each of the file and directory that could be found. If nothing was found the function returns an empty array.

If iFileDirMode is DIRMODE_FILES_ONLY the search is limited to files only. If the mode is DIRMODE_DIRECTORIES_ONLY the search is limited to subdirectories only. The last option DIRMODE_FILES_AND_DIRECTORIES includes both the files and subdirectories with is the default option if iFileDirMode is not applied.

This is how the tsSearchResult struct look like:

Struct tsSearchResult
    String sFilename
    String sAlternateFileName
    DateTime dtCreationDateTime
    DateTime dtLastAccessDateTime
    DateTime dtLastWriteDateTime
    BigInt biFileSize
    Integer iFileAttributes
End_Struct

For more information on file attributes, see File Attributes on msdn.

Example of use:

tsSearchResult[] lsSearchResult
Get FileSearch of oFilesystem "D:\Test\*.*" to lsSearchResult

This searches for all files and directories that exists in the "D:\Test" directory and returns an array of tsSearchResult. Each tsSearchResult has information on one file or directory found.

Example of use:

tsSearchResult[] lsSearchResult
Get FileSearch of oFilesystem "D:\Test\Thisfile.txt" to lsSearchResult
If (SizeOfArray(lsSearchResult) = 1) Begin
    If (lsSearchResult[0].iFileAttributes iand FILE_ATTRIBUTE_READONLY = FILE_ATTRIBUTE_READONLY) ;
        Send Info_Box "This file is writeprotected."
End

This finds the "D:\Test\Thisfile.txt" file and checks the readonly attribute of the file. If it is set an info_box is sent to the user to inform that the file is write protected.


FileTempPath
Navigation: cFilesystem class > File and directory access >

FileTempPath

Type: Function, Return type: String

Parameters: none

This function returns the current Windows Temp path.

Example of use:

String sTempPath
Get FileTempPath of oFilesystem to sTempPath


FileTempFileName
Navigation: cFilesystem class > File and directory access >

FileTempFileName

Type: Function, Return type: String

Parameters: {String sPathName {String sPrefix}}

sPathName
The path where the temporary file is created.

sPrefix
The first tree letters for the temporary filename.

This generates a new temporary file and returns the filename with full path. You can prefix the first tree letters of the filename if needed.

The function returns blank if an error occurred.

If the path name is applied it will create the temporary file in that directory. If it is not applied the TEMP environment variable is used. If that is also not available the current directory is used.

The file is not deleted automatically. Use the FileDelete method to delete the file when it is not needed anymore.

Example of use:

String sTempFile
Boolean bDeleted
Get FileTempFileName of oFilesystem to sTempFile
// Do some work with the temporary file.
Get FileDelete of oFilesystem sTempFile to bDeleted

This generates a new temporary file and then deletes it again right after.

Example of use:

String sTempFile
Boolean bDeleted
Get FileTempFileName of oFilesystem "D:\Temp" to sTempFile
// Do some work with the temporary file.
Get FileDelete of oFilesystem sTempFile to bDeleted

This generates a temporary file in the "D:\Temp" directory and returns something like "D:\Temp\C6.tmp".


FilePreservedFilename
Navigation: cFilesystem class > File and directory access >

FilePreservedFilename

Type: Function, Return type: String

Parameters: String sFileName

sFileName
Full path and filename for the file or directory to be cased acording to the preserved path and filename.

This examines the path and filename and returns the current casing that is preserved in the windows filesystem.

The function returns blank if an error occurred.


DirectoryCreate
Navigation: cFilesystem class > File and directory access >

DirectoryCreate

Type: Function, Return type: Boolean

Parameters: String sDirectoryName

sDirectoryName
This is the name for the new directory.

This creates a new directory.

The function returns true if the new directory was created without errors.

Example of use:

Boolean bCreated
Get DirectoryCreate of oFilesystem "D:\Test\A new directory" to bCreated

This creates a new subdirectory in the "D:\Test" directory called "A new directory".


DirectoryRemove
Navigation: cFilesystem class > File and directory access >

DirectoryRemove

Type: Function, Return type: Boolean

Parameters: String sDirectoryName

sDirectoryName
This is the name for the directory to be removed.

This removes an empty directory. It the directory is not empty an error occurs and the function returns false.

The function returns true if the directory was removed without errors.

Example of use:

Boolean bRemoved
Get DirectoryRemove of oFilesystem "D:\Test\An empty directory" to bRemoved

This removes the subdirectory "An empty directory" in the "D:\Test" directory.


DirectoryRemoveRecursive
Navigation: cFilesystem class > File and directory access >

DirectoryRemoveRecursive

Type: Function, Return type: Boolean

Parameters: String sDirectoryName

sDirectoryName
This is the name for the directory to be removed.

This removes a directory including all its contents. If the directory has any subdirectories they will be deleted also.

The function returns true if the directory and all its content was removed without errors.

Example of use:

Boolean bRemoved
Get DirectoryRemoveRecursive of oFilesystem "D:\Test\A directory" to bRemoved

This removes the subdirectory "A directory" with all its content in the "D:\Test" directory.


Helper methods
Navigation: cFilesystem class >

Helper methods

Some of these methods are used by the other methods in the cFilesystem class. But they are all stand alone methods that you may find them useful.


DestroyFileIcon
Navigation: cFilesystem class > Helper methods >

DestroyFileIcon

Type: Procedure

Parameters: Handle hIcon

hIcon
This is the handle for a icon.

This procedure destroys the specified icon handle that where previously created by the FileIcon function.

Example of use:

See FileIcon.


ListOfFiles
Navigation: cFilesystem class > Helper methods >

ListOfFiles

Type: Function, Return type: String[]

Parameters: String sSearchPaths String sSearchFiles

sSearchPaths
This is a list of paths to directories to search in. Each separated by a semicolon (;)

sSearchFiles
This is a list of files or part of filenames if wildcards are used. Each separated by a semicolon (;)

This function searches each directory from the search path for any file that matches any of the filenames from the search file list. It only searches for files not directories.

The function returns a list of the found files with full path and filenames.

sSearchFiles may not contain paths but may contain wildcards. Wildcards can be an asterisk (*) or a question mark (?).

sSearchPaths may only contain paths.

Example of use:

String[] sFiles
Get ListOfFiles of oFilesystem "D:\Test;C:\Windows" "*.txt;*.log" to sFiles

This will find all the files in the directories "D:\Test" and "C:\Windows" that has the file extension ".txt" or ".log".


CountOfFields
Navigation: cFilesystem class > Helper methods >

CountOfFields

Type: Function, Return type: Integer

Parameters: String sFields {String sDelimiter}

sFields
A list of fields separated by a delimiter.

sDelimiter
The delimiter in the list of fields that separates each field.

This counts the number of fields in a list of fields represented by a single string.

If the delimiter is not applied semicolon (;) is used as the default delimiter.

Example of use:

Integer iNoOfFields
Get CountOfFields of oFilesystem "D:\Test;C:\Windows" to iNoOfFields

This returns 2 which is the number of paths in the field list.

Example of use:

Integer iNoOfFields
Get CountOfFields of oFilesystem "AA|AB|AC|BA|CA|DA" "|" to iNoOfFields

This returns 6 which is the number of fields seperated by a pipe ( | ) delimiter.


FieldAtIndex
Navigation: cFilesystem class > Helper methods >

FieldAtIndex

Type: Function, Return type: String

Parameters: String sFields Integer iIndex {String sDelimiter}

sFields
A list of fields separated by a delimiter.

iIndex
The index number from the list of fields that is to be returned as a field.

sDelimiter
The delimiter in the list of fields that separates each field.

This retrives the field at a specific index number from a list of fields represented in a single string.

If the delimiter is not applied semicolon (;) is used as the default delimiter.

Note that the index is 1-based. That means that in order to get the first field from the list you will have to specify 1 as the index and not 0 (zero).

Example of use:

String sPath
Get FieldAtIndex of oFilesystem "D:\Test;C:\Windows" 1 to sPath

This returns "D:\Test" as the first path in the list.

Example of use:

String sPath
Get FieldAtIndex of oFilesystem "AA|AB|AC|BA|CA|DA" 4 "|" to sPath

This returns "BA" as the fourth field in the field list. Note that the field is returned without the delimiter.


DoShowError
Navigation: cFilesystem class > Helper methods >

DoShowError

Type: Procedure

Parameters: Integer iErrorNumber {String sAppendErrorText}

iErrorNumber
The error number retrieved from the GetLastError windows kernel function. For more information, see GetLastError as msdn.

sAppendErrorText
Text that is appended to the fetched error message.

This procedure fetches the error message from the system message table using the default language. Then it shows the error message including the appended error text if applied.

How the error message is shown depends on the property pbErrorAsVDFError . If this is false the error message is shown with a call to the Message_Box function with the OK button and a exclamation icon enabled. If it is true the error message is shown using the ERROR command.

Example of use:

Move (fsGetLastError()) to iErrorNumber
If iErrorNumber Send DoShowError of oFilesystem iErrorNumber

This fetches the last error number and shows the error message for that error number.


About cFilesystem

About cFilesystem Previous
Navigation: cFilesystem class >

About the cFilesystem class

cFilesystem class is made by Allan Kim Eriksen, NOVAX A/S. It is a redesign of the akefs.pkg package that I made many years ago for Visual DataFlex 5 and up. This is still available at www.vdf-guidance.com but it is using some very old technique and all methods are global. It also makes use of some global variables. Not very object oriented, so I decided to make a class of it all.

The cFilesystem class is based on a cObject class and makes use of the new native array and struct options. It also uses the variable type BitInt for file sizes. Therefore it is necessary to use a recent version of Visual DataFlex. I made this class with Visual DataFlex 15.0 but it should be possible to use the class down to Visual DataFlex 11.0.

This class also breaks the 2GB file limit that the old akefs.pkg has. Now you can use this class to handle huge files in theory up to 9 EB (etabyte) files!

Another design goal was to speed up the file access and the transfer of data between methods. You will notice that some of the methods will take parameters by reference instead of by value. Further more you can now subclass and argument the methods for your own need.

During the rewrite I killed to methods called RecursiveRemoveDirectory and RecursiveCopyDirectory. The purpose of these functions was to remove or copy a directory with all its children. While they worked okay, the where somewhat slow in the process. If you still need this functionality I recommend using the shell methods with vWin32fh.pkg by Wil van Antwerpen at www.vdf-guidance.com .

This class is open source and you may use it in commercial or non-commercial software free of charge. For more information, see VDF GUIdance Open License Statement.