HP OpenVMS Systems Documentation

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

Return Value

In most cases, the F$PARSE function returns a null string ("") if an error is detected during the parse. For example, a null string is returned if the file specification has incorrect syntax or if a disk or directory does not exist, making the file specification logically incorrect. However, when you specify a field name or the SYNTAX_ONLY parse type, F$PARSE returns the appropriate information.

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

NODE	Node name
DEVICE	Device name
DIRECTORY	Directory name
NAME	File name
TYPE	File type
VERSION	File version number

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.

Description

The F$PARSE function parses file specifications by using the RMS service $PARSE. For more information on the $PARSE service, see the OpenVMS Record Management Services Reference Manual.

When you use the F$PARSE function, you can omit those optional arguments to the right of the last argument you specify. However, you must include commas (,) as placeholders if you omit optional arguments to the left of the last argument you specify.

If you omit the device and directory names in the filespec argument, the F$PARSE function supplies defaults, first from the default-spec argument and second from the related-spec argument. If names are not provided by these arguments, the F$PARSE function uses your current default disk and directory.

If you omit the node name, the file name, the file type, or the version number, the F$PARSE function supplies defaults, first from the default-spec argument and second from the related-spec argument. (Note that the version number is not picked up from the related-spec argument.) If names are not provided by these arguments, the F$PARSE function returns a null specification for these fields.

The parse operation simply validates that the provided file specification is syntactically correct; it does not enforce file specification semantics. For example, fields such as the version number are verified to contain five or fewer numeric digits, optionally preceded by a hyphen (-), but are not range checked. File specification semantics are enforced by services such as Open and Create.

Examples

$ SET DEF DISK2:[FIRST]
$ SPEC = F$PARSE("JAMES.MAR","[ROOT]",,,"SYNTAX_ONLY")
$ SHOW SYMBOL SPEC
  SPEC = "DISK2:[ROOT]JAMES.MAR;"
 
      

In this example, the F$PARSE function returns the expanded file specification for the file JAMES.MAR. The example uses the SYNTAX_ONLY keyword to request that F$PARSE check the syntax, but should not verify that the [ROOT] directory exists on DISK2.

The default device and directory are DISK2:[FIRST]. Because the directory name [ROOT] is specified as the default-spec argument in the assignment statement, it is used as the directory name in the output string. Note that the default device returned in the output string is DISK2, and the default version number for the file is null. You must place quotation marks (" ") around the arguments JAMES.MAR and ROOT because they are string literals.

If you had not specified syntax-only parsing, and [ROOT] were not on DISK2, a null string would have been returned.

$ SET DEFAULT DB1:[VARGO]
$ SPEC = F$PARSE("INFO.COM",,,"DIRECTORY")
$ SHOW SYMBOL SPEC
  SPEC = "[VARGO]"
 
      

In this example the F$PARSE function returns the directory name of the file INFO.COM. Note that because the default-spec and related-spec arguments are omitted from the argument list, commas (,) must be inserted in their place.

$ SPEC= F$PARSE("DENVER::DB1:[PROD]RUN.DAT",,,"TYPE") 
$ SHOW SYMBOL SPEC
  SPEC = ".DAT"
 
      

In this example, the F$PARSE function is used to parse a file specification containing a node name. The F$PARSE function returns the file type .DAT for the file RUN.DAT at the remote node DENVER.