F$PARSE() is a lexical function that parses a file specification and returns either the expanded file specification or the particular file specification field that you request.
F$PARSE(filespec [,default-spec] [,related-spec] [,field] [,parse-type])
If any fields in the middle are missing, make sure to add a comma. For example:
In this example, the related-spec and parse-type fields are missing. Since related-spec is followed by field, a comma is added, but parse-type is not followed by anything, so no comma is added.
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.
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.
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 specification.
Specify one of the following field names (do not abbreviate):
|VERSION||File version number||;1|
If the field is not specified, an empty string is returned. If a wildcard is specified, a wildcard is returned.
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_ONLY: The syntax of the file specification is checked without verifying that the specified directory exists on the specified device.
In the following example, the F$PARSE function returns the expanded file specification for the file TEST1.DIR. Note that if the default spec is not specified, it is assumed that the file is in the default directory; the existence of the file is not checked. If the default spec if specified, it is used to fill in the directory field:
SMAN43$ set def [.test1] SMAN43$ sh def DSA1:[JDOE.TEST1] SMAN43$ a = f$parse("test1.dir") SMAN43$ sho sym a A = "DSA1:[JDOE.TEST1]TEST1.DIR;" SMAN43$ a = f$parse("test1.dir","[test1]") SMAN43$ show sym a A = "DSA1:[TEST1]TEST1.DIR;" SMAN43$ dir %DIRECT-W-NOFILES, no files found
In the following example, the directory part of the specification for INFO.COM found in the default directory is received:
$ SET DEFAULT DB1:[VARGO] $ SPEC = F$PARSE("INFO.COM",,,"DIRECTORY") $ SHOW SYMBOL SPEC SPEC = "[VARGO]"