X"91" function 69 (deprecated)

Searches a directory for a given file specification.
Restriction:
  • This function is deprecated, and provided for backward compatibility only. We recommend that you use the CBL_DIR_SCAN routines.
  • This routine is not supported when CHARSET"EBCDIC" is in effect.
  • This function is not supported in JVM COBOL.

Syntax:

call X"91" using result
                 function-code
                 parameter

Parameters:

result
Group containing:
01 result
  03 f-error    cblt-x1-compx   *> pic x comp-x. 
  03 f-handle   cblt-x2-compx   *> pic x(2) comp-x. 
  03 f-attrout  cblt-x1-compx   *> pic x comp-x. 
  03 f-time     cblt-x2-compx   *> pic x(2) comp-x. 
  03 f-date     cblt-x2-compx   *> pic x(2) comp-x. 
  03 f-size     cblt-x4-compx   *> pic x(4) comp-x. 
  03 f-fileout  pic x(n)        *> pic x(n)
function-code
Call prototype: cblt-x1-compx
Picture: pic x comp-x.
parameter
Group containing:
01 parameter
  03 f-action   cblt-x1-compx   *> pic x comp-x. 
  03 f-attrin   cblt-x1-compx   *> pic x comp-x. 
  03 f-filein   pic x(m)        *> pic x(m) 

On Entry:

function-code
Contains 69
f-action
Defines the action to perform:
0 Find the first matching file
1 Find the next matching file
2 Terminate the search early
3 Find one matching file
f-attrin
Attribute byte. All normal files, plus those with the attributes specified by setting this parameter, are to be included. To specify attributes, set the bits as follows:
bit 7 Unused
bit 6 Unused
bit 5 Archived file
bit 4 Subdirectory
bit 3 Unused
bit 2 System file
bit 1 Hidden file
bit 0 Read-only file
f-filein
The space-terminated filename specification of the file(s) required. This can contain a drive/directory or any wildcard characters.

On Exit:

f-error
Contains a status of the result:
0 Success/file found
1 No more files
2 Error
f-handle
The find handle. This field is set by the find-first function (see f-action above) and should not be altered until the corresponding terminate search has been done.
f-attrout
Attribute byte of file found:
bit 7 Unused
bit 6 Unused
bit 5 Archived file
bit 4 Subdirectory
bit 3 Volume label
bit 2 System file
bit 1 Hidden file
bit 0 Read-only file
f-time
Time file was created, in DOS format:
bits 15-11 Hour, 0-23
bits 10-5 Minute, 0-59
bits 4-0 Bi-second, 0-29
f-date
Date file was created, in DOS format:
bits 15-9 Year, 0-119 (1980-2099)
bits 8-5 Month, 1-12
bits 4-0 Day, 1-31
f-size
The size of the file in bytes.
f-fileout
The name of the file found, space-terminated.

Comments:

To find a single file, use the find-one function.

To find several files, use the find-first function and then use the find-next function repeatedly. When there are no more matching files, find-next returns with 1 in f-error. If you do not keep calling find-next until this happens, you must finish by calling the terminate-search function.

The f-handle field should be set to zero before you execute the find-first or find-one function. After that, if you are using the first/next/terminate sequence this field should not be changed until after the terminate search. If you are using the find-one function this field is automatically reset to 0 after that call.

If at any time f-error returns 1 or 2, a terminate search has been carried out automatically, and you should not execute the terminate-search function.

This routine cannot be used to check the existence of a network share resource, such as \\server1\share1, but it can be used to locate files or directories on that share, such as \\server1\share1\*.