Initializes a search for a file or directory.
CALL "CBL_DIR_SCAN_START" using by reference handle pattern by value search-attribute flags returning search-status
handle | usage pointer. | ||
pattern | A group item containing the following subordinate items: | ||
pattern-length | cblt-x2-comp5. | ||
pattern-content | pic x(n) | ||
search-attribute | cblt-x4-comp5. | ||
flags | cblt-os-flags. | ||
search-status | See Library Routines - Key |
pattern-length | Length of pattern string in the pattern-content field. It is associated with the handle and cannot be changed during a scan. A length of zero indicates a null-terminated pattern-content field. You can set pattern-length to less than the length of the pattern-content field, but not to more. | ||||||||||||
pattern-content | String for name searches. It is associated with the handle and cannot be changed during a scan. Can contain a full or partial directory path with or without a filename or just a filename. Elements in a path must be separated by "/". Null-terminated strings are recognised if the null is before the end of the string as provided in pattern-length, or if pattern-length is set to zero. If you set bit 1 of flags, the filename can contain wildcard characters: "*" means any arbitrary sequence of characters and "?" means any single character. If you set bit 0 flags the pling character "!" is available for use as an escape character. For more information about using wildcards and escape characters see the section Comments below. | ||||||||||||
search-attribute | Can be used to specify file properties to be searched for. It is associated
with the handle and cannot be changed during a scan. Valid values are:
| ||||||||||||
flags | You can set one of the following values:
|
handle | Reference for this search. Once you have specified search parameters and obtained a handle, you cannot change the parameters. |
You can use wildcards only in the filename part of the pattern to search against, for example:
main/rts/mf*.h
You cannot use them in the directory name or instead of a drive letter.
You can use escape sequences in patterns, to force the inclusion of any of the following characters:
"\", "/", "!", "*", "?".
To use an escape sequence, enter the escape sequence character, pling ("!"), followed by the character you wish to escape. For example:
"abc?" requests any files in the current folder beginning with "abc" and having only one more character in the name.
"abc!?" requests a file in the current folder with the name "abc?".
You can check the success of the call by examining search-status. Zero means success. Any other values are standard run-time system error codes; see the Run-time System Error Messages in Error Messages.