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,
 CATEGORY:
  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.
                 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