Find file


Section contents


Overview

Defined in

cfile.oxh

Description

Use this class to search for each occurrence of a filename in one or more directories. To search for more than one filename, variants are provided which accept wildcard characters. If the initial search is successful, subsequent searches can be carried out to find further occurrences of the filename.

After a successful search for a file, the full filename of the file can be retrieved. Filenames can be manipulated, interrogated and components extracted using the Parse class. After using one of the variants which do not accept the use of wildcards, the filename can be accessed using File(). If wildcards were used, the entry for each matching file can be accessed through the Dir object which is returned.


Construction / destruction


NewFindFile - Constructor

Usage

this& = NewFindFile&:(fs&)

Description

The C++ constructor constructs the FindFile object with a file server session.

Return Value
this& An value which represents the created find file entry
Error Handling

If the object could not be created then an error is generated which should be trapped by an ONERR handler.

Example
  LOCAL this&,fs&

  this& = NewFindFile&:(fs&)
  DeleteFindFile:(this&) 

DeleteFindFile - Destructor

Usage

DeleteFindFile:(BYREF this&)

Description

Destroys the find file object.

Arguments
BYREF this& A handle to a find file entry object
Example
  LOCAL this&

  this& = NewFindFile&:
  DeleteFindFile:(this&) 

Methods provided


FindFileFile - get file specification

Usage

name$ = FindFileFile$:(this&)

Description

Use this function to get the full file specification, including drive, path and filename, of a file which was found by a successful call to one of the search variants which do not accept wildcards. After a successful search using one of the variants which do accept wildcards, this information is accessible through the EntryName function of the Dir class object returned.

Arguments
this& A handle to a find file object
Return value
name$ On return contains the full file specification of the file which was found.

FindFileFind - recommence search for file

Usage

err% = FindFileFind%:(this&)

Description

Use this function to recommence searching after a successful FindByPath() or FindByDir(), to find the next occurrence of the filename in the path or drive list.

Arguments
this& A handle to a find file object
Return value
err% K32ErrNone% if a further occurrence of the file was found or K32ErrNotFound% if no more occurrences were found.

FindFileFindByDir - search for file in drive list

Usage

err% = FindFileFindByDir%:(this&,name$,dir$)

Description

Use this function to search for a file in a directory on all available drives. If a drive is specified, the directory on that drive is searched first, then the drive letter is discarded and the other drives are searched. Otherwise the session default drive is searched first. The available drives are then searched in alphabetical order. The search ends when the first occurrence of the file name is found, or when every available drive has been unsuccessfully searched. For a search using wildcards, use FindFileFindWildByDir. If a file is found, to recommence searching for the next occurrence, use FindFileFind.

Arguments
this& A handle to a find file object
name$ Filename to search for. A path may be specified. If so, it overrides Dir$.
dir$ Single path indicating a directory to search on each drive.
Return value
err% K32ErrNone% if the file was found, K32ErrNotFound% if not.

FindFileFindByPath - search for file in directory list

Usage

err% = FindFileFindByPath%:(this&,name$,path&)

Description

Use this function to search for a single file in one or more directories. The search ends when the first occurrence of the file name is found, or when every directory listed in the path list has been unsuccessfully searched. For a search using wildcards, use FindFileFindWildByPath. After a file has been found, to search for the next occurrence, use FindFileFind.

Arguments
this& A handle to a find file object
name$ Filename to search for. A directory may be specified. If so, it will be searched first, followed by the directories specified in the pathlist.
path& A descriptor containing a list of directories to search. The directories are searched in the order in which they occur in the path list. Each path must be delimited by a semicolon. A semicolon is not required after the final path. The paths may be absolute or may be relative to the session path. If no drive is specified in a path, that path is searched on every available drive, in alphabetical order.
Return value
err% K32ErrNotFound% if the file name was not found in any of the directories, or K32ErrNone% if it was found.

FindFileFindWild - recommence search for file with wildcards

Usage

err% = FindFileFindWild%:(BYREF dirlist&)

Description

Use this function to recommence searching after a successful FindFileindWildByPath or FindFileFindWildByDir, to find the next occurrences of the filename in the path or drive list.

Arguments
this& A handle to a find file object
BYREF dirlist& On return, contains the entries for all the matching files found in the next directory.
Return value
err% K32ErrNone% if a further occurrence of the file was found or K32ErrNotFound% if no more occurrences were found.

FindFileFindWildByDir - search for file in drive list with wildcards

Usage

err% = FindFileFindWildByDir%:(this&,name$,dir$,BYREF dirlist&)

Description

Use this function to search for a file in a directory on all available drives. If a drive is specified, the directory on that drive is searched first, then the drive letter is discarded and the other drives are searched. Otherwise the session default drive is searched first. The available drives are then searched in alphabetical order. The search ends when the first occurrence of the file name is found, or when every available drive has been unsuccessfully searched. For a search using wildcards, use FindFileFindWildByDir. If a file is found, to recommence searching for the next occurrence, use FindFileFind.

Arguments
this& A handle to a find file object
name$ Filename to search for. A path may be specified. If so, it overrides Dir$.
dir$ Single path indicating a directory to search on each drive.
BYREF dirlist& On return, contains the entries for all files matching name$ found in the directory.
Return value
err% K32ErrNotFound% if no matching file was found in the directory on any of the drives, or K32ErrNone% if any were found.

FindFileFindWildByPath - search for file in directory list with wildcards

Usage

err% = FindFileFindWildByPath%:(this&,name$,path$,BYREF dirlist&)

Description

Use this function to search for one or more files in the directories specified in a path list. The search ends when one of the directories specified is found to contain one or more file names matching name$, or when every directory in the path list has been unsuccessfully searched. To recommence searching, use FindFileFindWild. This function differs from FindFileFindByPath in that it accepts wildcards in the filename.

Arguments
this& A handle to a find file object
name$ Filename to search for. May contain wildcards. A directory may be specified. If so, it will be searched first, followed by the directories specified in the pathlist.
path$ List of directories to search. The directories are searched in the order they occur in the list. Each path must be delimited by a semicolon. A semicolon is not required after the final path. The paths may be absolute or may be relative to the session path. If no drive is specified in a path, that path is searched on every available drive, in alphabetical order.
BYREF dirlist& On return, contains the entries for all files matching name$ found in a directory.
Return value
err% K32ErrNotFound% if no matching file was found in any of the directories, or K32ErrNone% if any were found.