| **Navigation:**  [[introduction.htm|Language Reference]] > 13 - Built-in Functions >====== DIRECTORY (get file directory) ====== | [[destroy  remove a control .htm|{{btn_prev_n.gif|Previous page}}]][[introduction.htm|{{btn_home_n.gif|Return to chapter overview}}]][[disable  dim a control .htm|{{btn_next_n.gif|Next page}}]] |
|  ||

**DIRECTORY(** //queue, path, attributes// **)**

{{blk2blue.jpg|blk2blue.jpg}}

| **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).

{{notebox.jpg|NoteBox.jpg}}

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.

{{notebox.jpg|NoteBox.jpg}}

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.

{{tipbox.jpg|TipBox.jpg}}

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:**

[[shortpath  return short filename .htm|SHORTPATH]]

[[longpath  return long filename .htm|LONGPATH]]

[[path  return current directory .htm|PATH]]

[[filedialoga extended file dialog .htm|FILEDIALOG]]