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.

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.

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

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.