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:

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.


[<<<] [>>>]