25.134. OPEN DIRECTORY dir_name PATTERN pattern OPTION option AS dn

Open a directory to retrieve the list of files.

dir_name is the name of the directory.
pattern is a wild card pattern to filter the file list.
option is an integer value that can be composed AND-ing some of the following values
- SbCollectDirectories Collect the directory names as well as file names into the file list.
- SbCollectDots Collect the virtual . and .. directory names into the list.
- SbCollectRecursively Collect the files from the directory and from all the directories below.
- SbCollectFullPath The list will contain the full path to the file names. This means that the file names returned by the function NextFile will contain the directory path specified in the open directory statement and therefore can be used as argument to file handling commands and functions.
- SbCollectFiles Collect the files. This is the default behavior.
- SbSortBySize The files will be sorted by file size.
- SbSortByCreateTime The files will be sorted by creation time.
- SbSortByAccessTime The files will be sorted by access time.
- SbSortByModifyTime The files will be sorted by modify time.
- SbSortByName The files will be sorted by name. The name used for sorting is the bare file name without any path.
- SbSortByPath The files will be sorted by name including the path. The path is the relative to the directory, which is currently opened. This sorting option is different from the value sbSortByName only when the value sbCollectRecursively is also used.
- SbSortAscending Sort the file names in ascending order. This is the default behavior.
- SbSortDescending Sort the file names in descending order.
- SbSortByNone Do not sort. Specify this value if you do not need sorting. In this case directory opening can be much faster especially for large directories.
dn is the directory number used in later references to the opened directory.

Note that this command can execute for a long time and consuming a lot of memory especially when directory listing is requested recursively. When the command is executed it collects the names of the files in the directory or directories as requested and builds up an internal list of the file names in the memory. The command NEXTFILE uses the list to retrieve the next file name from the list.

This implies to facts:

The function NEXTFILE will not ever return a file name that the file was created after, and did not exist when the command OPEN DIRECTORY was executed.
Using CLOSEDIR after the list of the files is not needed as soon as possible is a good idea.

Using a directory number that was already used and not released calling CLOSEDIR raises an error.

If the list of the files in the directory can not be collected the command raises error.