Documentation component QDIR By Jacques Philippe Beta Version 0.0.3 October 28th, 2002

Version 1.0.0 available
-------------
Not BETA anymore ???
- the proprety .WithDotsDirs did not work under .DIR
- add .WithDotsDirs in documentation

Appendix A: QDIR

QDIR Component

QDIR is a analog of "DOS" DIR and DIR /S command

QDIR Internal Types   See File Times for addition information

Type QDIR_FILETIME
    lowDateTime As Long
    highDateTime As Long
End Type

Type QDIR_WIN32_FIND_DATA             '   WIN32 NAMES
    attributes As Long                                      '   dwFileAttributes As Long
' RAPIDQ BUGS WITH NESTED TYPES so REPLACED BY ! No Differences
'   ftCreationTime As FILETIME
    creationLowDateTime As Long                 '   ftCreationTime.dwLowDateTime As Long
    creationHighDateTime As Long                 '   ftCreationTime.dwHighDateTime As Long

'   ftLastAccessTime As FILETIME
    lastAccessLowDateTime As Long             '   ftLastAccessTime.dwLowDateTime As Long
    lastAccessHighDateTime As Long             '   ftLastAccessTime.dwHighDateTime As Long

'   ftLastWriteTime As FILETIME
    lastWriteLowDateTime As Long               '   ftLastWriteTime.dwLowDateTime As Long
    lastWriteHighDateTime As Long               '   ftLastWriteTime.dwHighDateTime As Long

    fileSizeHigh As Long                                 '   nFileSizeHigh As Long
    fileSizeLow As Long                                 '   nFileSizeLow As Long
    dwReserved0 As Long
    dwReserved1 As Long
    cFileName As String * 260
    cAlternate As String * 14
End Type

Type QDIR_SYSTEMTIME   ' VB integer = RQ Short
    year As Short                       ' the year as a number
    month As Short                     'the month as a number
    dayOfWeek As Short            ' number of the day of the week SUNDAY = 0, MONDAY = 1, ...
    day As Short                          'day in the month 1, 2, 3,... 12, 13, 14, ... 28/30/31
    hour As Short                         'the hour as a number
    minute As Short                     'the minute as a number
    second As Short                     'the second as a number
    milliseconds As Short              'the milliseconds as a number
    ' Extended
    DateTime As Double                 ' The DateTime As A Number
    date As String * 10                   ' Date as a String mm/dd/yyyy
    dateEU As String * 10              ' EU date Foramt dd/mm/yyyy
    dateAlpha As String * 16          ' "ddd" "mmm" DD, yyyy
    dateAlphaEU As String * 15     ' "ddd" DD "mmm" yyyy
    time As String * 8                     ' without ms HH:MM:SS
    timems As String * 12                 ' Time As a String HH:MM:SS.iii
    strDayOfWeek As String * 3    ' day of the week as in Day(0 To 6) : "Mon", "Tue", "Wed", ... "Sun"
    nWeekDay As String * 1          ' "0", "1", "2", ... "6"
    strMonthOfYear As String * 3 ' day of the week as in Months(1 To 12) : "Jan", "Feb", ... "Dec"
End Type

QDIR Properties

Field	Type	R/W	Défault
*Find Files Parameters*
fileName	string	R/W
the name of the founded file
dosFileName	string	R/W
dos the name of the founded file
path	String	R/W	applicationPath = Command$(0) - Application.exeName
Absolute path to the file ie : C:\myDir\otherDir\
pathFileName	string	R/W
Absolute path + the fileName ie : c:\Windows\system.dat
size	Double	R/W
the size as a double (use StrF$(size, ffFixed, 18, 0) to exp (ffNumber to have thousands separators)
*Date and Time Variable*
creation	as QDIR_SYSTEMTIME
the Type contaning informations about the creationTime
lastAccess	as QDIR_SYSTEMTIME
the Type contaning informations about the lastAccessTime
lastWrite	as QDIR_SYSTEMTIME
the Type contaning informations about the lastWriteTime
*File Times* The File Time Properties decribed below for lastwriteTime may be found here for all three File Times : ie - QDir.Creation.dateAlphaEU - QDir.lastAccess.dateEU and even - QDir.lastWrite.timems (which is equal to QDir.timems) These three time TYPES give access to 3 x 18 porpeties (=54), not used every day :) To compare dates and times, use dateTime. The dateTimes are DOUBLE precision numbers (64 bit Integer, converted here in DOUBLE) holding a date and time associated with a file. That DOUBLE specifies the number of 100-nanosecond intervals which have passed since January 1, 1601 (10,000,000 for each elapsed second since then).
dateTime	Double
the lastWriteTime of the file as a double
time	String
the lastwriteTime of the file, format HH:MM:SS
timems	String
the lastWriteTime of the file + milliseconds, format HH:MM:SS,mmm
date	String
the lastWriteTime date, format MM/DD/YYYY
dateEU	String
the lastWriteTime date, EU foramt DD/MM/YYYY
dateAlpha	String
the lastWriteTime in alphanumeric format "mon dec 24 2001"
dateAlphaEU	string
the lastWriteTime in alphanumeric EU format "mon 24 dec 2001"
strDayOfWeek	string
the lastWriteTime Day Of The Week : "Mon", "Tue", "Wed", Thu" ...
strMonthOfYear	String
the lastWriteTime Month Of The Year : "Jan", "Feb", "Mar", "Apr", ...
*Attibutes*
attributes	Long
the attributes af the file (sum of attributes)
attributesAsString	String
the attributes transformed in a string "ADHNRSTC0" If Instr(myDir.AttributesAsString, "A") Then ....
*Text Month, WeekDay*
days(0 To 6)	As String		days(0) = "Sunday" '"Dim" ' May Be Changed days(0 To 6) days(1) = "Monday" '"Lun" days(2) = "Tuesday" '"Mar" days(3) = "Wednesday" '"Mer" days(4) = "Thursday" '"Jeu" days(5) = "Friday" '"Ven" days(6) = "Saturday" '"Sam"
the 7 names of the strDayOfWeek. Source for AlphaNumeric dates
months(1 To 12)	As String		months(1) = "January" ' May be Changed months(1 To 12) months(2) = "February" months(3) = "March" months(4) = "April" months(5) = "May" months(6) = "June" months(7) = "July" months(8) = "August" months(9) = "September" months(10) = "October" months(11) = "November" months(12) = "December"
the 12 names of strMonthOfYear. Source for AlphaNumeric dates

QDIR Methods

Method Description

Function Close As Long CLOSE FIND

Function GetFirstFile (sPathFilter As String) As String FIND FIRST FILE

Function GetNextFile As String FIND NEXT FILE

Sub Dir (sPathFilter As String, sRejectedAttributes As String, sMustAttributes As string) File Search without Scanning The Sub Directories

Sub Dirs (sPathFilter As String, sRejectedAttributes As String, sMustAttributes As String) File Search with Scanning the Sub Directories
Dirs chosen to remember the Command Dir /s
Note!
Dir and Dirs will only return when ALL the directory job has been done.
There is no DoEvents in QDir.
- Once a QDir.Dir or QDir.Dirs is Started, a busy flag forbids to start another occurence of QDir.Dir or QDir.Dirs, until the first job is
finished. To start more than one QDir.Dir or QDir.Dirs simultneously, you must DECLARE (DIM) two or more Variables As QDIR.

Functioni ChangeFileDateAndTime ( ... ) As Long ChangeFileDateAndTime (pathFileName$, Year%, month%, day%, hour%, minute%, second%, optionWhichTimes$)
Return 0 (False) on Failure or 1 (True) on success

EXAMPLES :
- ChangeFileDateAndTime ("c:\myDir\myFile", 1983, 6, 21, 17, 22, 33) ' the LastWriteTime Of MyFile is set to June 21 st 1983 at 17:22:23

- ChangeFileDateAndTime("c:\myDir\myFile", 1983, 6, 21, 17, 22, 33, "Access") ' the LastAccessTime Of myFile is set to June 21 st 1983 at 17:22:23

- ChangeFileDateAndTime("c:\myDir\myFile", 1983, 6, 21, 17, 22, 33, "ACCESS Write CREATION")
' the LastAccessTime, CreationTime and LastWriteTime Of myFile are set to June 21 st 1983 at 17:22:23

Used in the Event OnFileFound with Qdir.pathFilename can change the Date and Time of all matching files.
A File is Stored on Disk with Three Different Dates and Times Named :
- the creationTime
- the lastAccesstime
- the lastWriteTime (the one mostly mostly used shown)

Six NUMERIC Parameters **MUST** be Passed to the Functioni :
- the First is the YEAR of the new Date Time For the File
- the Second is the MONTH of the new Date Time For the File
- the Third is the DAY of the new Date Time For the File
- the Fourth is the HOUR of the new Date Time For the File
- the Fifth is the MINUTE of the new Date Time For the File
- the Sixth is the SECOND of the new Date Time For the File

The FILENAME With or Without a Path must be Passed as a STRING !

The optionWhichTimes Parameter is a STRING that Indicates to the Functioni
which file Times must be Changed. If that String contains :
- "CREATION" the creationTime will be Changed ("CRE" is enough)
- "ACCESS" the lastAccessTime will be changed ("ACC" is enough)
- "WRITE" the lastWriteTime will be changed ("WRI" is enough)
Not case sensitive
If that string is not Passed or is Empty, the lastWriteTime only will
be changed

ERROR : on error a ShowMessage is POPED UP and the Functioni Returns 0 (False

Function ChangeFileAttributes (sPathFileName As string, attributesAsString As String) As Long

- attributes are passed as a String, elements of that string are :
"A" for Archive
"D" for Directory
"H" for Hidden
"N" for Normal
"R" for Read Only
"S" for System
"T" for Temporary
"C" for Compressed
"0" for No Attribute Set (?=N?)

EXAMPLE :
-------
ChangeFileAttributes ("c:\myDir\myFile","AR")
the attributes of myFile are set to Archive and ReadOnly

The function returns 1 (True) if attributes have been changed and 0 if
an error has occured.

Used in the Event OnFileFound with Qdir.pathFilename can change the
attributes of all matching files.

Parameters description

sPathFilter - Path + FileMask, i.e "C:/Rapid-Q/*" or "c:\\Windows\\*.txt".

Path may be relative or absolute ie : dir2\myfile.Ext or c:\dir1\dir2\myfile.Ext.

relative path is relative to APPLICATION directory (where the .EXE is)

filter may be any kind of filter using wild card "*.Txt", "*name.Txt"

sRejectedAttributes - in rejectedAttributes$, if more than one attribute is rejected, all file having one of these rejected attributes set is rejected from the search.

sMustAttributes - in mustAttributes$, if more than one attibute is present, to be accepted a file must have all these attributes set. ie : no file can match "0A"
rejectedAttribites and mustAttributes maybe any of these letters in ANY order "ADHNRSTC0"
- attributes are passed as a String, elements of that string are :
"A" for Archive
"D" for Directory
"H" for Hidden
"N" for Normal
"R" for Read Only
"S" for System
"T" for Temporary
"C" for Compressed
"0" for No Attribute Set (?=N?)
- You can use multiple attributes in any order ie : "HTCA"
- an unknown attribute letter will be ignored.
- attributes are not case sensitive

sPathFileName -- Path , i.e "C:/Rapid-Q/" or "c:\\Windows\\".

Path may be relative or absolute ie : dir2\ or c:\dir1\dir2\

relative path is relative to APPLICATION directory (where the .EXE is)

attributesAsString - the attributes transformed in a string "ADHNRSTC0" If Instr(myDir.AttributesAsString, "A") Then ....

QDIR Events

Event Type Occurs when... Params

OnFileFound Sub OnFileFound OnFileFound = 0

QDIR Examples

$INCLUDE "QDir.Inc"

Declare Sub ShowFileParamsShortList
Declare Sub ShowFileParamsLongList
Declare Sub ChangeAttributes

$ESCAPECHARS ON
$TYPECHECK ON
$INCLUDE "RAPIDQ.INC"

'-------------- SHORT DOC valid for ALL 4 Examples -------------
'
' path : relative to the Application Directory and absolute path are accepted
' directory separator maybe "\" or "/"
' filter : accept Wild Cards like "dir/*.ba?" ...
'
' rejectedAttribites and mustAttributes maybe any of these letters in ANY
' order "ADHNRSTC0"
' ----------------------------------------------------------------------------------

Dim myFile As QFileStream
Dim myDir As QDir
DefInt iCount

'---------------------------------------------------------------------------------
'   EXAMPLE 1      SIMPLE DIR with Event myDir.OnFileFound
' ---------------------------------------------------------------------------------
    myFile.Open ("dirOut.txt", fmCreate)
        myDir.OnFileFound = ShowFileParamsLongList
        myDir.Dir ("C:/Rapid-Q/*", "D", "A")
        ' all files with archive attribute set in this directory
        ' Directories not listed
        ' Attributes : "ADHNRSTC0"
    myFile.Close
    Print "path    = ";myDir.path
    Print "EXAMPLE 1          FINISHED"

' ---------------------------------------------------------------------------------
' EXAMPLE 2     RECURSIVE DIR SEARCH with Event myDir.OnFileFound
' ---------------------------------------------------------------------------------
    iCount = 0
    myFile.Open ("dirOut.txt", fmCreate)
        myDir.OnFileFound = ShowFileParamsShortList
        myDir.Dirs ("c:\\Windows\\*.txt", "D", "")
        ' all files with extention ".txt" in directory Windowsand sub directories
        ' Directories not listed
        ' Attributes : "ADHNRSTC0"
    myFile.Close
    Print "path    = ";myDir.path
    Print "EXAMPLE 2          FINISHED"
' ---------------------------------------------------------------------------------

' ---------------------------------------------------------------------------------
' EXAMPLE_3
' ---------------------------------------------------------------------------------
'   xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
'   !!!!!!!! WARNING : This will change Selected Files dates !!!!!!!!!
'   xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
'   To test this, create a directory c:/tmp/ and copy any file in it
    myFile.Open ("dirOut.txt", fmCreate)
        myDir.OnFileFound = ChangeAttributes
        myDir.Dir ("c:/tmp/*", "D", "")
        myDir.OnFileFound = ShowFileParamsLongList
        myDir.Dir ("c:/tmp/*", "D", "")
    myFile.Close
    Print "path    = ";myDir.path
    Print "EXAMPLE 3          FINISHED"
' ---------------------------------------------------------------------------------

' Redate files to Sat Jan 01/02/1982 01:02:03
' and set the archive, readonly and compressed attributes

'****************************************************************************
Sub ChangeAttributes
        myDir.ChangeFileDateAndTime (myDir.pathFilename, 1982, 1, 2, 1, 2, 3, "cre acc wri")
        myDir.ChangeFileAttributes (myDir.pathFileName, "ARC")
End Sub

'Print Routines
'****************************************************************************
Sub ShowFileParamsShortList
     DefStr sLine
    sLine = Space$(9)
    With myDir
        sLine = Replace$ (sLine, .AttributesAsString, 1)
        sLine = sLine & .pathFileName & " " & StrF$(.Size,ffFixed, 18, 0)
        Print sline
        myFile.WriteLine (sLine)
    End With
End Sub

'****************************************************************************
Sub ShowFileParamsLongList
    DefStr sLine
    With myDir
sLine = ""
sLine =         "\n       FileName = " & .fileName
sLine = sLine & "\n        DosName = " & .dosFileName
sLine = sLine & "\n         path\\ = " & .path
sLine = sLine & "\n path\\fileName = " & .pathFileName
sLine = sLine & "\n           Size = " & Strf$(.Size, ffFixed, 18, 0)
sLine = sLine & "\n      Attributs = " & Str$(.Attributes)
sLine = sLine & "\n Attr_AsString = " & .AttributesAsString
sLine = sLine & "\n   CreationTime = " & Strf$(.creation.DateTime, ffFixed, 18, 0)
sLine = sLine & "\n             or = " & .creation.strDayOfWeek & " " & .creation.strMonthOfYear & " " & .creation.date _
                                                        & " " & .creation.time & " WeekDay#=" & .creation.nWeekDay
sLine = sLine & "\n LastAccessTime = " & Strf$(.lastAccess.DateTime, ffFixed, 18, 0)
sLine = sLine & "\n        or = " & .lastAccess.strDayOfWeek & " " & .lastAccess.strMonthOfYear & " " & .lastAccess.date _
                                                        & " " & .lastAccess.time & " WeekDay#=" & .lastAccess.nWeekDay

sLine = sLine & "\n     LastWriteTime = " & Strf$(.DateTime, ffFixed, 18, 0)
sLine = sLine & "\n                or = " & .strDayOfWeek & " " & .strMonthOfYear & " " & .date _
                                               & " " & .time & " WeekDay#=" & .lastWrite.nWeekDay
sLine = sLine & "\n              Time = " & .Time
sLine = sLine & "\n              Date = " & .date
sLine = sLine & "\n            DateEU = " & .dateEU
sLine = sLine & "\n         DateAlpha = " & .dateAlpha
sLine = sLine & "\n       DateAlphaEU = " & .dateAlphaEU
Print sline
myFile.WriteLine (sLine)
    End With
End sub
' ---------------------------------------------------------------------------------
' EXIT CONSOLE

Method	Description
Function Close As Long	CLOSE FIND
Function GetFirstFile (sPathFilter As String) As String	FIND FIRST FILE
Function GetNextFile As String	FIND NEXT FILE
Sub Dir (sPathFilter As String, sRejectedAttributes As String, sMustAttributes As string)	File Search without Scanning The Sub Directories
Sub Dirs (sPathFilter As String, sRejectedAttributes As String, sMustAttributes As String)	File Search with Scanning the Sub Directories Dirs chosen to remember the Command Dir /s *Note!* Dir and Dirs will only return when ALL the directory job has been done. There is no DoEvents in QDir. - Once a QDir.Dir or QDir.Dirs is Started, a busy flag forbids to start another occurence of QDir.Dir or QDir.Dirs, until the first job is finished. To start more than one QDir.Dir or QDir.Dirs simultneously, you must DECLARE (DIM) two or more Variables As QDIR.
Functioni ChangeFileDateAndTime ( ... ) As Long	ChangeFileDateAndTime (pathFileName$, Year%, month%, day%, hour%, minute%, second%, optionWhichTimes$) Return 0 (False) on Failure or 1 (True) on success
EXAMPLES : - ChangeFileDateAndTime ("c:\myDir\myFile", 1983, 6, 21, 17, 22, 33) ' the LastWriteTime Of MyFile is set to June 21 st 1983 at 17:22:23 - ChangeFileDateAndTime("c:\myDir\myFile", 1983, 6, 21, 17, 22, 33, "Access") ' the LastAccessTime Of myFile is set to June 21 st 1983 at 17:22:23 - ChangeFileDateAndTime("c:\myDir\myFile", 1983, 6, 21, 17, 22, 33, "ACCESS Write CREATION") ' the LastAccessTime, CreationTime and LastWriteTime Of myFile are set to June 21 st 1983 at 17:22:23 Used in the Event OnFileFound with Qdir.pathFilename can change the Date and Time of all matching files. A File is Stored on Disk with Three Different Dates and Times Named : - the creationTime - the lastAccesstime - the lastWriteTime (the one mostly mostly used shown) Six NUMERIC Parameters MUST be Passed to the Functioni : - the First is the YEAR of the new Date Time For the File - the Second is the MONTH of the new Date Time For the File - the Third is the DAY of the new Date Time For the File - the Fourth is the HOUR of the new Date Time For the File - the Fifth is the MINUTE of the new Date Time For the File - the Sixth is the SECOND of the new Date Time For the File The FILENAME With or Without a Path must be Passed as a STRING ! The optionWhichTimes Parameter is a STRING that Indicates to the Functioni which file Times must be Changed. If that String contains : - "CREATION" the creationTime will be Changed ("CRE" is enough) - "ACCESS" the lastAccessTime will be changed ("ACC" is enough) - "WRITE" the lastWriteTime will be changed ("WRI" is enough) Not case sensitive If that string is not Passed or is Empty, the lastWriteTime only will be changed ERROR : on error a ShowMessage is POPED UP and the Functioni Returns 0 (False
Function ChangeFileAttributes (sPathFileName As string, attributesAsString As String) As Long
- attributes are passed as a String, elements of that string are : "A" for Archive "D" for Directory "H" for Hidden "N" for Normal "R" for Read Only "S" for System "T" for Temporary "C" for Compressed "0" for No Attribute Set (?=N?) EXAMPLE : ------- ChangeFileAttributes ("c:\myDir\myFile","AR") the attributes of myFile are set to Archive and ReadOnly The function returns 1 (True) if attributes have been changed and 0 if an error has occured. Used in the Event OnFileFound with Qdir.pathFilename can change the attributes of all matching files.

Parameters description sPathFilter - Path + FileMask, i.e "C:/Rapid-Q/" or "c:\\Windows\\.txt". Path may be relative or absolute ie : dir2\myfile.Ext or c:\dir1\dir2\myfile.Ext. relative path is relative to APPLICATION directory (where the .EXE is) filter may be any kind of filter using wild card ".Txt", "name.Txt" sRejectedAttributes - in rejectedAttributes$, if more than one attribute is rejected, all file having one of these rejected attributes set is rejected from the search. sMustAttributes - in mustAttributes$, if more than one attibute is present, to be accepted a file must have all these attributes set. ie : no file can match "0A" *rejectedAttribites* and mustAttributes maybe any of these letters in ANY order "ADHNRSTC0" - attributes are passed as a String, elements of that string are : "A" for Archive "D" for Directory "H" for Hidden "N" for Normal "R" for Read Only "S" for System "T" for Temporary "C" for Compressed "0" for No Attribute Set (?=N?) - You can use multiple attributes in any order ie : "HTCA" - an unknown attribute letter will be ignored. - attributes are not case sensitive sPathFileName -- Path , i.e "C:/Rapid-Q/" or "c:\\Windows\\". Path may be relative or absolute ie : dir2\ or c:\dir1\dir2\ relative path is relative to APPLICATION directory (where the .EXE is) attributesAsString - the attributes transformed in a string "ADHNRSTC0" If Instr(myDir.AttributesAsString, "A") Then ....

Event	Type	Occurs when...	Params
OnFileFound	Sub OnFileFound		OnFileFound = 0