F$PARSE()
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.
Contents
Format
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:
f$parse("accounts.dat",dka0:[accounts],,"VERSION")
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.
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.
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):
| Field | Description | Example |
|---|---|---|
| NODE | Node name | SMAN01 |
| DEVICE | Device name | DKA0: |
| DIRECTORY | Directory name | [ACCOUNTS] |
| NAME | File name | BALANCE_SHEET |
| TYPE | File type | .LOG |
| 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.
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_ONLY: The syntax of the file specification is checked without verifying that the specified directory exists on the specified device.
