FILE_SEARCH

  Calls the RMS service $SEARCH to search a directory for a file and return
  the partial or full file that you specify.

  FILE_SEARCH returns a string containing the resulting file specification.
  If you do not provide a complete file specification, FILE_PARSE supplies
  defaults in the return string from fields it finds first in the default
  file specification or in the related file specification.  If the file is
  not found in the directory, FILE_SEARCH returns a null string and signals
  an error.

  Syntax

     string4 := FILE_SEARCH (string1 [, string2 [, string3 [, keyword1
                            [,...[,keyword_n]]]]])

  Parameters

     string1              The specification of the file you want to find.

     string2              A default file specification.

     string3              A related file specification

     keyword              A field in the VMS file specification.  The valid
                          keywords are:  NODE, DEVICE, DIRECTORY, NAME,
                          TYPE, VERSION, HEAD, or TAIL.  HEAD returns the
                          NODE, DEVICE, and DIRECTORY.  TAIL returns the
                          NAME, TYPE, and VERSION.  Use one or more keywords
                          to specify which fields of the file specification
                          you want FILE_PARSE to return.  You can use as
                          many of these keywords as you wish with one
                          FILE_PARSE statement as long as there are not
                          duplicate requests.  For example, you cannot use
                          HEAD along with NODE, DEVICE, or DIRECTORY.

  Comments

  Specify the first three parameters as quoted strings.  Logical names and
  device names must terminate with a colon.  If you omit optional parameters
  to the left of a parameter, you must include null strings a place holders
  for the missing parameters.  You must use FILE_SEARCH multiple times with
  the same parameter to get all of the occurrences of a filename in a
  directory.  When all matching files have been found, a null string is
  returned.

  Example

  The following procedure puts each .RNO file in the your current, default
  directory into a separate buffer.  You can use the SHOW (BUFFERS)
  statement to display the buffers created with this procedure.  The initial
  FILE_SEARCH clears the context in case of an incomplete previous file
  search.

     PROCEDURE user_collect_rnos
         LOCAL file_spec;
         file_spec := FILE_SEARCH ('');
         LOOP
            file_spec := FILE_SEARCH ('*.rno');
            EXITIF file_spec = "";
            CREATE_BUFFER (FILE_PARSE (file_spec, "", "", name), file_spec);
         ENDLOOP;
     ENDPROCEDURE;

  Related Topics

     FILE_PARSE