View source for F$PARSE()

'''F$PARSE()''' is a [[Lexical functions|lexical function]] that 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])

If any fields in the middle are missing, make sure to add a comma. For example:

<nowiki>f$parse("accounts.dat",dka0:[accounts],,"VERSION")</nowiki>

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.

==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):

{| class="wikitable"
|-
! 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.

=Examples=