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.

Examples

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]"