Introduction of New Directory Search Routines

In earlier versions of Micro Focus COBOL compiler products, there were various Call-By-Number
routines that were provided to help customers perform a variety of functions. One of these routines
was an x"91" function 69 call, which provided directory search functionality. Function 69 was a DOS,
Windows and OS/2 operating system function only. That is, it was not documented or support on
the UNIX environment.

Starting in Object COBOL Developers Suite version 4.0, many of these Call-By-Number functions
were replaced with new Call-By-Name routines, which started with "CBL_...". Given that x"91"
function 69 was never an available UNIX routine; it was not part Micro Focus Object COBOL running
on the UNIX environment.

In Server Express 2.2, Micro Focus enhanced the product further by incorporating the following
CBL_ routines that provided the same functionality as x"91" function 69:

• CBL_DIR_SCAN_BEGIN - Initializes a search for a file or directory

• CBL_DIR_SCAN_END - Terminates a search operation
• CBL_DIR_SCAN_READ - Searches for the next entry in the file system using a search
handle returned by a previous CBL_DIR_SCAN_BEGIN

Details of each of these routines are included below. For further information and other related
routines, please refer to the Micro Focus documentation on File Handling, Chapter 10 - File Handling
Library Routines.

CBL_DIR_SCAN_BEGIN
Initializes a search for a file or directory.

Syntax:

call "CBL_DIR_SCAN_BEGIN" 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 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

Page 1 of 5
 Introduction of New Directory Search Routines

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
recognized 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.

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 Meaning
Set
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:

Page 2 of 5
 Introduction of New Directory Search Routines

\", "/", "!", "*", "?".

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 chapter Run-time System Error Codes in
your Error Messages book.

CBL_DIR_SCAN_END
Terminates a search operation.

Syntax:

call "CBL_DIR_SCAN_END" using by reference handle

returning search-status
Parameters:

handle

usage pointer.

search-status

See Key.

On Entry:

handle

Set by CBL_DIR_SCAN_START. This field identifies the search operation that is to be

terminated.

On Exit:

handle

Undefined

Comments:

You must call CBL_DIR_SCAN_END to release system resources. You might be unable to start
additional searches if you fail to release resources at the end of a scan operation.

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 chapter Run-time System Error Codes in
your Error Messages book.

CBL_DIR_SCAN_READ

Page 3 of 5
 Introduction of New Directory Search Routines

Searches for the next entry in the file system using a search handle returned by a previous
CBL_DIR_SCAN_BEGIN.

Syntax:

call "CBL_DIR_SCAN_READ" using by reference handle

entry
returning search-status
Parameters:

handle usage pointer.

entry A group item containing the following subordinate items:
attribute cblt-os-flags.
date-stamp A group item defined as:
year cblt-x2-comp5
month cblt-x2-comp5
day cblt-x2-comp5
hour cblt-x2-comp5
minute cblt-x2-comp5
second cblt-x2-comp5
millisec cblt-x2-comp5
dst cblt-x1-comp5

size cblt-x8-comp5
name A group item defined as:
max-len cblt-x2-comp5
entry-name pic x(max-len)

search-status See Key.

On Entry:

handle

Set by CBL_DIR_SCAN_START. This field identifies the search operation. Search parameters
cannot be changed for a given handle.

max-len

The length of the entry-name field

On Exit:

attribute
Describes the properties of the entry found. Valid values are
Value Bit Set Meaning
1 0 File found
2 1 Directory found
4 2 An entry that is neither a file or a directory found
8 3 The entry is readable.
16 4 The entry is writable
32 5 The entry is hidden

Page 4 of 5
 Introduction of New Directory Search Routines

If the entry found is a file, any of bits 3, 4 and 5 may be set, to indicate whether or not the
file is readable and so on. These bits may be set if the entry found is not a file, but the
meaning in this case is undefinedNote that this is a return field. The flags in bits 0 to 2
reflect the entry's properties and may not be the same as the search attributes.

date-stamp

This group field holds the date and time that the entry was last written. On some systems
millisec is set to zero. The final field in date-stamp, dst, is the daylight saving time flag: 1
means that daylight saving was in operation when the entry was last written; 0 means that
daylight saving was not in operation.

size

The size of the file in bytes

entry-name

The name of the entry found

Comments:

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 chapter Run-time System Error Codes in
your Error Messages book. Errors associated with an entry-name field that is too small for the
result will be ignored. If you do not supply a large enough field, the result will be truncated to fit. If
you supply a field that is shorter than max-len you will corrupt memory.

Page 5 of 5