PARSE

Extract components of a file specification

xcall PARSE(file_spec, [no_preprocessing], [node], [device], [directory], [name], [extension], 
&     [version][, expanded_spec])

Arguments

file_spec

The variable, literal, or record that contains the input file specification whose component elements are to be extracted. (a)

no_preprocessing

(optional) A flag to inhibit normal file open preprocessing. No_preprocessing can contain one of the following values. See the Discussion for details. (n)

0 = Normal file open preprocessing occurs. (default)

nonzero = Parse the filename as is without any preprocessing.

node

(optional) The variable that will be loaded with any node or remote computer name specified in the input file specification. If the node is not specified in the input string, the field is set to blanks. On OpenVMS, if a node is returned, it is terminated with two colons (::). On Windows and Unix, if a remote computer name is returned, it is preceded by an “at” sign (@). (a)

device

(optional) The variable that will be loaded with the device portion of the file specification. On OpenVMS, the default device is SYS$DISK. The returned device is terminated by a colon (:). (Windows, OpenVMS only) (a)

directory

(optional) The variable that will be loaded with the directory portion of the file specification. The default is the home directory. The format of directory depends on the operating system: (a)

System	Directory specification
Windows	\directory
Unix	/directory
OpenVMS	[directory]

name

(optional) The variable that will be loaded with the name portion of the file specification. The name does not include a period or semicolon from the input field. (a)

extension

(optional) The variable that will be loaded with the file extension portion of the file specification. The extension includes a period. The default extension is either .ddf or the extension set by the SETDFN subroutine. (a)

version

(optional) The variable that will be loaded with the version portion of the file specification. The version includes a semicolon (;). (OpenVMS only) (a)

expanded_spec

(optional) Returned with the expanded file specification. (a)

Discussion

The PARSE subroutine enables you to access individual elements of a file specification.

If no_preprocessing is zero (either explicitly or by default), PARSE expands environment variables (including the correct path in a rooted environment variable), adds the default path and extension(s), and honors DBLCASE (on Unix). If no_preprocessing is nonzero, this behavior does not occur.

If the file specification doesn’t contain an extension (either explicitly or implicitly through the default name), a period is returned for the extension. If default name processing is disabled, blanks are returned.

If any other components of the file specification are missing, blanks are returned.

Expanded_spec returns the specification of the file that is opened if file_spec is used in an OPEN statement.

Data is moved to the subroutine arguments (except file_spec and no_preprocessing) according to the rules for moving alpha data.

On Windows and Unix, if system option #35 is set, the PARSE subroutine stops at the semicolon (;) and doesn’t include it in the filename or file extension.

On OpenVMS, the PARSE subroutine uses the RMS $PARSE facility to translate and isolate the node, device, directory, filename, extension, and version fields from the specified file descriptor string. If the file specification doesn’t contain a version number (either explicitly or implicitly through the default name), a semicolon is returned for the version number. If default name processing is disabled, blanks are returned.

You cannot parse a remote filename, except to its lowest local translation. See Examples below.

Examples

record
    node                ,a10
    device              ,a30
    dir                 ,a80
    name                ,a20
    ext                 ,a4
    vers                ,a2
proc
    .
    .
    xcall parse("DTKMAPFIL:", 0, node, device, dir, name, ext, vers)

If DTKMAPFIL is assigned to SYS$DISK:[DBLV5.TOOLKIT] dtkmap.ism;1, for example, the above XCALL on OpenVMS returns the following data:

node	<blank>
device	SYS$DISK:
dir	[DBLV5.TOOLKIT]
name	DTKMAP
ext	.ISM
vers	;1

Using the same program on Windows or Unix with DTKMAPFIL set to DAT:DTKMAP.ism, where DAT is set to DTKMAPFIL:@myserver, the XCALL returns the following:

node	@myserver
device	<blank>
dir	DTKMAPFIL:
name	dtkmap
ext	.ism
vers	<blank>