CBL_DIR_SCAN_START

Initializes a search for a file or directory.

Syntax:
CALL "CBL_DIR_SCAN_START" using  by reference   handle
                                                pattern
                                 by value       search-attribute
                                                flags
                                 returning      search-status
Parameters:
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
On Entry:
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:
Value Bit Set Meaning
1 0 Search for a file.
2 1 Search for a directory.
4 2 Search for any entry that is neither a file or a directory.
Bits above those specified are ignored. Bits 0 to 2 are always combined by OR, for example, to search for either a file or a directory set bits 0 and 1 (value 3). To search for all types of entry set bits 0, 1 and 2 (value 7).
flags You can set one of the following values:
Value Bit Set Meaning
1 0 Turns on processing of escape sequences in pattern-content. The default is no processing of escape sequences.
2 1 Turns on the use of wildcards in the pattern-content field. Wildcards have significance as such only if this option is set.
Bits above those specified are ignored. To turn on both processing of escape characters and the use of wildcards set both bits 0 and 1 (value 3).
On Exit:
handle Reference for this search. Once you have specified search parameters and obtained a handle, you cannot change the parameters.
Comments:

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.

See Also: