Difference between revisions of "F$PARSE()"

From VSI OpenVMS Wiki
Jump to: navigation, search
(Examples)
 
(One intermediate revision by the same user not shown)
Line 6: Line 6:
 
If any fields in the middle are missing, make sure to add a comma. For example:
 
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>
+
<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.
 
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.
Line 59: Line 61:
  
 
=Examples=
 
=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:
 +
 +
<nowiki>
 +
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
 +
 +
</nowiki>
 +
 +
In the following example, the directory part of the specification for INFO.COM found in the default directory is received:
 +
 +
<nowiki>
 +
$ SET DEFAULT DB1:[VARGO]
 +
$ SPEC = F$PARSE("INFO.COM",,,"DIRECTORY")
 +
$ SHOW SYMBOL SPEC
 +
  SPEC = "[VARGO]"
 +
 +
</nowiki>
  
 
[[Category: Lexical Functions]]
 
[[Category: Lexical Functions]]

Latest revision as of 15:22, 26 November 2019

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