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.

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