The $ZPARSE function expands a file name to a full file-specification and then returns the full file-specification or one of its fields (node, device, directory, name, type, or version). The $ZPARSE function is analogous to the DCL F$PARSE lexical function. The order of the operands differs from the DCL F$PARSE function.
The format for the $ZPARSE function is:
$ZPARSE(expr1[,expr2[,expr3[,expr4[,expr5]]]])
The first expression specifies the file-specification to parse; if the file-specification is not valid, $ZPARSE() returns a null string; if the file-specification contains a VMS wildcard (* and/or %), $ZPARSE() returns a file-specification containing the wildcard(s).
The optional second expression specifies the field of the file-specification that $ZPARSE() returns; if this argument is missing or null, $ZPARSE() returns a full file-specification constructed using default values in place of any fields missing for node, directory, file, type, and version.
The optional third and fourth expressions specify default values to use during file name expansion for missing fields (node, device, directory, name, type, or version), if any, in the original file name. For any field missing in the original file name specified in expr1, $ZPARSE() will attempt to substitute the corresponding field from expr3; if that field is not present in expr3, $ZPARSE() will attempt to use the corresponding field from expr4.
If the file name, type, or version is missing from all three of expr1, expr3, and expr4, $ZPARSE() will return a null string for the corresponding field. If the file node, device, or directory is missing from all three of expr1, expr3, and expr4, $ZPARSE() will substitute the information from your current default directory.
The optional fifth expression specifies the mode or type of parse that $ZPARSE() performs.
$ZPARSE() provides a tool for verifying that a file-specification is syntactically correct, for examining specific fields of a file-specification, and for filling in missing pieces in a partial specification based on a hierarchy of defaults. For information about determining whether a file exists, refer to the description of $ZSEARCH().
$ZPARSE() arguments, after the first, are optional. If you use no other arguments, a single argument is sufficient. However, if you use selected arguments $ZPARSE() requires that null strings ("") be filled in for the unspecified arguments.
The acceptable keywords for the second argument are:
"NODE": Node name
"DEVICE": Device name
"DIRECTORY": Directory name
"NAME": File name (excluding file extension)
"TYPE": File type extension
"VERSION": File version number
The keywords may be entered in either upper or lower case. Variables that evaluate to these strings and indirection are acceptable for argument two. When the keywords themselves appear as string literals, they must be enclosed in quotation marks (" ").
The keywords for the fifth argument $ZPARSE() are:
NULL (""): Returns a full file-specification or device
"SYNTAX_ONLY": Disables checking for the existence of the directory or device.
"NO_CONCEAL": Disables the "conceal" attribute in the translation of logical names in a file-specification.
The mode names may be upper or lower case but cannot be abbreviated.