FILE_PARSE

  Performs the equivalent of the DCL F$PARSE lexical function -- that is, it
  calls the RMS service $PARSE to parse a file specification and to return
  either an expanded file specification or the file specification field that
  you request.

  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 an error
  occurs during the parse, FILE_PARSE returns a null string.

  Syntax

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

  Parameters

     string1              The file specification to be parsed.

     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 you do not specify
                          fields that are duplicates of fields returned by
                          the HEAD or TAIL keywords.  For example, you
                          cannot use HEAD along with NODE, DEVICE, or
                          DIRECTORY.

  Comments

  Specify the first three parameters as 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.  The FILE_PARSE built-in does not check that the file
  exists.  It merely parses the file specifications provided and returns the
  requested portions of resulting file specification.

  Example

     spec := FILE_PARSE ("program.pas", "[user]");

  Calls RMS to parse and return a full file specification for the file
  PROGRAM.PAS.  The second parameter provides the name of the directory in
  which the file can be found (in this case [USER]).

  Related Topics

     FILE_SEARCH