12.14.1. Open directory
The syntax of the command open directory is
OPEN DIRECTORY dir_name PATTERN pattern_value OPTION option_value AS dir_number
The parameter dir_name should be an expression evaluating to a string, which is the name of the directory for which the listing is needed. It can be absolute path or relative to the current working directory. It may but need not contain the trailing slash.
The parameter pattern_value should be an expression evaluating to a string. When the list of the files is gathered this pattern is used to select the files. Only the files matching the pattern will be included in the list of files. The pattern matching uses the same algorithm as the operator LIKE. Altering the joker and wild characters for the operator LIKE also alters the pattern matching mechanism of file selection. The command OPEN DIRECTORY leaves the pattern matching memory in a non-matched state. In other words the function JOKER will return the undef value after executing an OPEN DIRECTORY command until the next LIKE operator is executed.
Pattern matching and selection is done during the execution of the command OPEN DIRECTORY the other file list handling commands and the function NextFile do not interfere with the pattern matching.
Pattern matching while building up the list is a time and processor consuming tasks. If you do not want to perform pattern matching just getting all the file names use value undef or empty string as pattern value. In either case pattern matching is skipped during file list build up. Using * to get all files is a bad idea unless your aim to make your CPU generate heat.
Note that pattern matching can either be case sensitive or insensitive based on the setting of the option `compare'. This option alters the behavior of pattern matching during file list build up on UNIX systems, but not under Windows. Under Windows NT pattern matching during file list build up is always case insensitive, no matter how the option `compare' is set.
The parameter option_value should be an expression evaluating to an integer value. This value is used to drive the behavior of the command. Each bit of the value has a special meaning. To set the correct value ScriptBasic predefines several global constants that you can use. These constants can be used in this value. If more than one constant is needed you have to use the operator and to connect them. The predefined constants and their corresponding meanings are:
- 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 will be the bare file name without any path even if the option bit SbCollectPath is specified.
- 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.
The final parameter dir_number should be an expression evaluating to an integer value between 1 and 512. This number should be used as argument to the function NextFile and as parameter to the commands CLOSE DIRECTORY and RESET DIRECTORY. If this parameter is a variable having an integer value zero then the command will alter the value of the variable assigning a directory number automatically. This is similar to the mechanism when opening files. There is no FreeDir or any similar function.
If the directory does not exist or is not readable by the program for security or for any other reason an error occurs.
Note that the number used to open a directory is separate from the numbers used in opening files. If you use for example the file number 14 to open a file you still can use 14 to open a directory.
File and directory names are collected into a list during the command OPEN DIRECTORY. Any alteration in the file system like deletion of files, new files, modification of files will be reflected in the listing only if the directory is closed using the statement CLOSE DIRECTORY and reopened again using the statement OPEN DIRECTORY.