| Navigation: Language Reference > 13 - Built-in Functions >====== DIRECTORY (get file directory) ====== |    |
DIRECTORY( queue, path, attributes )
| DIRECTORY | Gets a file directory listing (just like the DIR command in DOS). |
| queue | The label of the QUEUE structure that will receive the directory listing. |
| path | A string constant, variable, or expression that specifies the path and filenames directory listing to get. This may include the wildcard characters (* and ?). |
| attributes | An integer constant, variable, or expression that specifies the attributes of the files to place in the queue. |
The DIRECTORY procedure returns a directory listing of all files in the path with the specified attributes into the specified queue.
The queue parameter must name a QUEUE with a structure that begins the same as the following structure contained in EQUATES.CLW:
ff_:queue QUEUE,PRE(ff_),TYPE
name STRING(13)
date LONG
time LONG
size LONG
attrib BYTE !A bitmap, the same as the attributes EQUATEs
END
or the following structure (for long filename support):
FILE:queue QUEUE,PRE(File),TYPE
name STRING(FILE:MAXFILENAME) !FILE:MAXFILENAME is an EQUATE
shortname STRING(13)
date LONG
time LONG
size LONG
attrib BYTE !A bitmap, the same as the attributes EQUATEs
END
Your QUEUE may contain more fields, but must begin with these fields. It will receive the returned information about each file in the path that has the attributes you specify. The date and time fields will contain standard Clarion date and time information (the conversion from the operating system's storage format to Clarion standard format is automatic).
The attributes parameter is a bitmap which specifies what filenames to place in the queue. The following equates are contained in EQUATES.CLW:
ff_:NORMAL EQUATE(0) !Always active
ff_:READONLY EQUATE(1) !Not for use as attributes parameter
ff_:HIDDEN EQUATE(2)
ff_:SYSTEM EQUATE(4)
ff_:DIRECTORY EQUATE(10H)
ff_:ARCHIVE EQUATE(20H) ! NOT Win95 compatible
The attributes bitmap is an OR filter: if you add the equates, you get files with any of the attributes you specify. This means that, when you just set the attributes to ff_:NORMAL, you only get files (no sub-directories) without the hidden, system, or archive bits set. If you add ff_:DIRECTORY to ff_:NORMAL, you will get files AND sub-directories from the path. Since ff_:NORMAL is an equate for zero (0), you will always get files.
DIRECTORY() and BYTES() return negative values for files greater than 2Gb and less than 4Gb. A transformation from LONG to ULONG gives the correct positive value of file size (See example below).
DIRECTORY doesn't clear the passed QUEUE before populating it, so you can use multiple DIRECTORY statements to build a QUEUE that combines the files returned for each statement.
For example:
DIRECTORY(DirQ, '*.exe', ff_:NORMAL)
DIRECTORY(DirQ, '*.dll', ff_:NORMAL)
will populate DirQ with all exe and dll files.
Short filenames used in applications
Applications should avoid the use of the short filenames returned by DIRECTORY. This includes
never using the DIRECTORY(ff_:Queue…) syntax, which retrieves only short names. Instead, use the DIRECTORY(FILE:QUEUE…) syntax, and avoid using the ShortName field.
Short file names do not exist under all file systems. The short file name returned in the queue is sometimes the long file name, truncated to 13 bytes. Under Windows NT/2000/XP systems, the registry key NtfsDisable8dot3NameCreation allows turning off short file names. Files created after this key is enabled will not have a short file name generated.
Setting NtfsDisable8dot3NameCreation=1 in the Windows system registry improves performance. This setting may become more popular and eventually can be the default. Developers using short file names in applications released to the general public may run into problems in the near future.
Sometimes you can run into a user running your applications on a Novell server without the long file name NLM loaded, so you can't rely on all file systems supporting long file names. Therefore, the safest strategy is to name your files with legal 8.3 short names, and as noted above, only use the long file name queue field returned by DIRECTORY.
Example:
| DirectoryList PROCEDURE |
| AllFiles QUEUE(File:queue),PRE(FIL) !Inherit exact declaration of File:queue |
| END |
| LP LONG |
| Recs LONG |
| CODE |
| DIRECTORY(AllFiles,'*.*',ff_:DIRECTORY) !Get all files and directories |
| Recs = RECORDS(AllFiles) |
| LOOP LP = Recs TO 1 BY -1 |
| GET(AllFiles,LP) |
| IF BAND(FIL:Attrib,ff_:DIRECTORY) AND FIL:ShortName <;> '..' AND FIL:ShortName <;> '.' |
| CYCLE !Let sub-directory entries stay |
| ELSE |
| DELETE(AllFiles) !Get rid of all other entries |
| END |
| END |
| !*additional example: |
| PROGRAM |
| MAP |
| GetFileSize PROCEDURE(STRING FileName2Get, <;*LONG OutDate>,<;*LONG OutTime>),ULONG |
| END |
| MySize ULONG |
| CODE |
| MySize = GetFileSize('myfile.zip') |
| |
| |
| GetFileSize PROCEDURE(STRING FileName2Get, <;*LONG OutDate>,<;*LONG OutTime>) |
| FilesQ QUEUE(FILE:Queue),PRE(FilesQ) |
| END |
| CODE |
| DIRECTORY(FilesQ,FileName2Get,ff_:NORMAL+ff_:READONLY+ff_:HIDDEN+ff_:SYSTEM) |
| GET(FilesQ,1) |
| IF ERRORCODE() |
| CLEAR(FilesQ) !Return 0 if file not found |
| END |
| IF ~OMITTED(2) |
| OutDate=FilesQ:Date |
| END |
| IF ~OMITTED(3) |
| OutTime=FilesQ:Time |
| END |
| RETURN FilesQ:Size |
| !Note: Return as ULONG to work with files over 2GB in size |
See Also: