ONE_FIND_FILE

Returns successive file names that match a file specification

Description:

This routine is intended to provide some of the faciltes provided on a VAX by the standard VMS routine LIB$FIND_FILE. It is passed a file specification that can contain wild card characters such as ’∗’, eg ’∗.∗’. On the first call the Context variable should be set to zero, and the routine will return the name of the first file that matches the file specification. On subsequent calls the calling routine should continue to call using the value of Context returned by the previous call, and each call will return the name of the next file that matches the specification. When the last file that matches the specification has been returned, subsequent calls will return a blank string as the file name and an error code (an even value) as the function value. Finally, a call to ONE_FIND_FILE_END with the last returned value of Context will close down any files opened or memory allocated by ONE_FIND_FILE.

Invocation

FOUND = ONE_FIND_FILE (FILESPEC,LISDIR,FILENAME,CONTEXT,STATUS)

Arguments

FILESPEC = CHARACTER (Given)
The file specification to be matched. May contain wildcards. Case sensitive.
LISDIR = LOGICAL (Given)
TRUE if directory contents are to be listed for directories that match the file specification. Should be set to FALSE if matching directory names should be returned without opening the directories themselves. Note that even if true, this routine will not recurse into all subsubdirectories that match. To be more explicit: TRUE is equivalent to ’ls’, FALSE is equivalent to ’ls -d’. Neither is equivalent to ’find . -name "filespec"’
FILENAME = CHARACTER (Returned)
The name of a file that matches FILESPEC.
CONTEXT = INTEGER (Given and Returned)
A variable used to remember the context of a series of calls for the same file specification. Should be set to zero by the caller for the first call for a new specification and the value then returned by this routine should be used in subsequent calls.
STATUS = INTEGER (Given and Returned)
A status code as follows

  • SAI__OK for success

  • ONE__NOFILES - No more files found

  • ONE__LENGTHERR - Bad parameter length

  • ONE__PIPEERR - Pipe error

  • ONE__MALLOCERR - Malloc error

Returned Value

ONE_FIND_FILE = LOGICAL
TRUE if File Found FALSE if error or no more files

Notes:

This routine returns bad status (ONE__NOFILES) even when the status is not technically bad. In general, the caller should annul this particular status condition before proceeding.

Bugs:

This routine does not provide all the facilities offered by the original VAX version; it only accepts the first three arguments as listed above, and almost of necessity it uses and expects UNIX syntax for the file specs. This means that ’/usr/users/ks/ ∗.∗’ is OK, but ’[ks]∗.∗’ is not. Note that ’∗’ and ’∗.∗’ will give quite different results under UNIX, whereas under VMS they would be the same. There is no way of specifying recursion; ’/usr/user/ks/...’ for example is meaningless. Nevertheless, it is hoped that it is close enough in functionality to the VMS original to act as a useable substitute in most cases. It cannot handle specifications that the standard shell (sh) cannot handle in an ’ls’ command - there are some variations of the ’ls’ command involving complex wildcarding that will cause sh on a SUN to hang, and they will also hang this routine.

It is not at all clear that the method used here is in any way the best solution to the problem, and there are a number of possible alternatives that could be tried, including using ’find’ rather than ’ls’, or using routines such as readdir() to search the file system and do any pattern matching in this routine itself. The program as it stands should be regarded (tolerantly!) as an initial attempt and the author would be glad to be sent a better version.

Copyright © 2000 Council for the Central Laboratory of the Research Councils