FINDDATA

Name

finddata

Purpose

Find valid file or directory names, using groups of path strings.

Description

Searches for targets which are valid files and/or directories.
Various combinations of path names are searched for a named item.
Specifically, paths of the form a/r/t are checked, where 'a' is taken from
the array of abspaths, 'r' from the relpaths, and 't' is a scalar
string, the actual target,

File I/o

Calling Sequence

finddata, abspaths,relpaths,target,results

Inputs

abspaths - An array of strings comprising initial path components for search.
It may also be a single string with entries separated by :
It may be a null string.
The abspaths are used as the lefthand parts of the trial
search paths. They usually start with a '/' but this is
not a requirement.
relpaths - An array of strings comprising final path components for search.
It may also be a single string with entries separated by :
It may be a null string.
The relpaths are used as the righthand parts of the trial
search paths. They usually do not start with a '/' but this is
not a requirement.
target - String representing the target of search.
Target is normally a single path component and does not include
'/' characters but this is not a requirement. A target is
considered valid and returned, by default, if it is a readable
file or directory.
If target is an empty string, a recursive search will
return all files and/or directories under the search
paths- a non-recursive search returns those concantenations
of abspath and relpaths that are locatable. Using a
null string for target and including a null string in
both abspaths and relpaths returns everything eligible
within the current working directory.

Optional Input Parameters

Keyword Input Parameters

CACHE - Path of file to save list cache. The default is for there to
be no cache. If /ONEONLY is not set the cache is updated only.
DEBUG - Flag, if set, will generate verbose debugging output.
FILEONLY- Flag, if set, returns readable file targets only.
DIRONLY- Flag, if set, returns readable directory targets only.
ONEONLY - Flag, if set, forces the search to end as soon as the first
target is found. Otherwise the entire range of paths generated
is checked for multiple matches.
RECURSIVE -Flag, if set the search will be recursive on each of the paths
to find any target of the form a/../../....../r/t where 'a' is
taken from the abspaths, 'r' from the relpaths and 't' is a
target. Otherwise the paths selected are of the form a/r/t

Outputs

results - String array, one or more pathnames to the targets located.
If the search found nothing, this will contain one
element equal to ''

Keyword Output Parameters

COUNT - Count of matches found.

Common Blocks

Side Effects

writes a cache list file if enabled to do so by specifying the CACHE keyword.

Restrictions

Can be very slow.
Because of the underlying file search used, paths returned may be slightly
edited relative to the expected concatenation of paths, eg leading
'./' may be elided.
The cache is not currently working and is silently turned off if invoked.
This routine does not currently locate symbolic links or file names beginning
with '.'
This routine could usefully look for other combinations of permissions.

Procedure

Modification History

2006/08/15, Written by Peter L. Collins, Lowell Observatory.
2006/08/25, PLC, generalized functionality