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:
01 pattern
  03 pattern-length   cblt-x2-comp5. *> pic x(2) comp-5
  03 pattern-content  pic x(n)
search-attribute
Call prototype: cblt-x4-comp5
Picture: pic x(4) comp-5
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 conventional path must be separated by "\". It is also possible to scan an MFDBFH datastore; such scans require a specific URL search string (see The Database URL for more information). 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).
Important: At least one of these bits should be set.
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.
4 2 Turns on the inclusion of the path in returned filenames. By default, the Windows native Run-Time System does not return paths and the UNIX native Run-Time System and the managed Run-Time System do.
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.
search-status
Return status:
0 Success
1 Unable to start search
2 Invalid search handle
3 Search finished
127 Other error

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?".