VMS Help Lexicals, F$PARSE  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    Parses a file specification and returns either the expanded file
    specification or the particular file specification field that you
    request.

    Format

      F$PARSE(filespec [,default-spec] [,related-spec] [,field]

             [,parse-type])

1 - Return Value

    A character string containing the expanded file specification
    or the field you specify. If you do not provide a complete file
    specification for the filespec argument, the F$PARSE function
    supplies defaults in the return string.

    In most cases, the F$PARSE function returns a null string ("")
    if an error is detected during the parse. For example, a null
    string is returned if the file specification has incorrect
    syntax or if a disk or directory does not exist, making the file
    specification logically incorrect. However, when you specify a
    field name or the SYNTAX_ONLY parse type, F$PARSE returns the
    appropriate information.

2 - Arguments

 filespec

    Specifies a character string containing the file specification to
    be parsed.

    The file specification can contain the asterisk (*)  and the
    percent sign (%) wildcard characters. If you use a wildcard
    character, the file specification returned by the F$PARSE
    function contains the wildcard.

 default-spec

    Specifies a character string containing the default file
    specification.

    The fields in the default file specification are substituted in
    the output string if a particular field in the filespec argument
    is missing. You can make further substitutions in the filespec
    argument by using the related-spec argument.

 related-spec

    Specifies a character string containing the related file
    specification.

    The fields in the related file specification are substituted in
    the output string if a particular field is missing from both the
    filespec and default-spec arguments.

 field

    Specifies a character string containing the name of a field
    in a file specification. Specifying the field argument causes
    the F$PARSE function to return a specific portion of a file
    specification.

    Specify one of the following field names (do not abbreviate):

    NODE       Node name
    DEVICE     Device name
    DIRECTORY  Directory name
    NAME       File name
    TYPE       File type
    VERSION    File version number

 parse-type

    Specifies the type of parsing to be performed. By default,
    the F$PARSE function verifies that the directory in the file
    specification exists on the device in the file specification;
    however, the existence of the directory is not verified if you
    provide a field argument. Note that the device and directory can
    be explicitly given in one of the arguments, or can be provided
    by default.

    Also, by default the F$PARSE function translates logical names if
    they are provided in any of the arguments. The F$PARSE function
    stops iterative translation when it encounters a logical name
    with the CONCEALED attribute.

    You can change how the F$PARSE function parses a file
    specification by using one of the following keywords:

    NO_CONCEAL  Ignores the "conceal" attribute in the translation
                of a logical name as part of the file specification;
                that is, logical name translation does not end when a
                concealed logical name is encountered.
    SYNTAX_     The syntax of the file specification is checked
    ONLY        without verifying that the specified directory exists
                on the specified device.

3 - Examples

    1.$ SET DEF DISK2:[FIRST]
      $ SPEC = F$PARSE("JAMES.MAR","[ROOT]",,,"SYNTAX_ONLY")
      $ SHOW SYMBOL SPEC
        SPEC = "DISK2:[ROOT]JAMES.MAR;"

      In this example, the F$PARSE function returns the expanded
      file specification for the file JAMES.MAR. The example uses
      the SYNTAX_ONLY keyword to request that F$PARSE check the
      syntax, but should not verify that the [ROOT] directory exists
      on DISK2.

      The default device and directory are DISK2:[FIRST]. Because the
      directory name [ROOT] is specified as the default-spec argument
      in the assignment statement, it is used as the directory name
      in the output string. Note that the default device returned
      in the output string is DISK2, and the default version number
      for the file is null. You must place quotation marks (" ")
      around the arguments JAMES.MAR and ROOT because they are string
      literals.

      If you had not specified syntax-only parsing, and [ROOT] were
      not on DISK2, a null string would have been returned.

    2.$ SET DEFAULT DB1:[VARGO]
      $ SPEC = F$PARSE("INFO.COM",,,"DIRECTORY")
      $ SHOW SYMBOL SPEC
        SPEC = "[VARGO]"

      In this example the F$PARSE function returns the directory
      name of the file INFO.COM. Note that because the default-spec
      and related-spec arguments are omitted from the argument list,
      commas (,)  must be inserted in their place.

    3.$ SPEC= F$PARSE("DENVER::DB1:[PROD]RUN.DAT",,,"TYPE")
      $ SHOW SYMBOL SPEC
        SPEC = ".DAT"

      In this example, the F$PARSE function is used to parse a file
      specification containing a node name. The F$PARSE function
      returns the file type .DAT for the file RUN.DAT at the remote
      node DENVER.