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