HP OpenVMS DCL Dictionary
Parses a file specification and returns either the expanded file
specification or the particular file specification field that you
F$PARSE (filespec [,default-spec] [,related-spec] [,field]
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. For more information, see the
Description section for this lexical function.
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.
Specifies a character string containing the file specification to be
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.
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
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.
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
Specify one of the following field names (do not abbreviate):
File version number
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
You can change how the F$PARSE function parses a file specification by
using one of the following keywords:
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.
The syntax of the file specification is checked without verifying that
the specified directory exists on the specified device.
The F$PARSE function parses file specifications by using the RMS
service $PARSE. For more information on the $PARSE service, see the
OpenVMS Record Management Services Reference Manual.
When you use the F$PARSE function, you can omit those optional
arguments to the right of the last argument you specify. However, you
must include commas (,) as placeholders if you omit optional arguments
to the left of the last argument you specify.
If you omit the device and directory names in the
filespec argument, the F$PARSE function supplies
defaults, first from the default-spec argument and
second from the related-spec argument. If names are
not provided by these arguments, the F$PARSE function uses your current
default disk and directory.
If you omit the node name, the file name, the file type, or the version
number, the F$PARSE function supplies defaults, first from the
default-spec argument and second from the
related-spec argument. (Note that the version number
is not picked up from the related-spec argument.) If
names are not provided by these arguments, the F$PARSE function returns
a null specification for these fields.
The parse operation simply validates that the provided file
specification is syntactically correct; it does not enforce file
specification semantics. For example, fields such as the version number
are verified to contain five or fewer numeric digits, optionally
preceded by a hyphen (-), but are not range checked. File specification
semantics are enforced by services such as Open and Create.
$ 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.
$ 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.
$ 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.