Filename Alchemy - F$PARSE Defaulting

Pervasive uniform file typing is a well-known feature of OpenVMS. In fact, it is a design choice passed to OpenVMS from its antecedents. Source files for each language have a distinct file type (e.g., .FOR, .C, .CXX, .COB, .PAS, .PLI, .MAR, .BAS). Other files, produced from these source files have their own distinctive file types, .EXE, .LIS, .EXE, .STB, .MAP, to name but a few of the standardized possibilities. Implementing these naming conventions is often incorrectly seen as an unwieldy chore; nothing could be further from the truth. The OpenVMS SYS$PARSE system service, and the corresponding DCL lexical function, F$PARSE provide all that is needed for implementation in a single call.

F$PARSE is often underappreciated and inefficiently used. Most commonly, F$PARSE is used for extracting individual elements (e.g., node, device, directory, name, type) from within a supplied file specification. Extracting elements from a file specification is not the underlying intent of F$PARSE, it is merely a side effect. The underlying, often ignored functionality is far more useful. The online HELP text contains a subtle hint to the intended functionality, to wit:

“...
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.
...”

[from “HELP LEXICALS F$PARSE Arguments”; OpenVMS 7.3-2]

This description has changed little over the years and is indisputably accurate. With all due respect to the authors of the documentation, what is missing is an example of the function's actual intended use. In the online HELP (under HELP LEXICALS F$PARSE Examples) the two provided examples are similarly terse, neither including all three possible specification strings provided for in the F$PARSE interface. Without additional detailed review, users often remain mystified as to the intent behind F$PARSE.

SYS$PARSE is the key to painlessly implementing standard OpenVMS file specification processing. F$PARSE is merely the DCL-accessible wrapper for the underlying system call. This processing is complete with all of its nuances:

• defaulting of filetypes;
• translation of logical names; and
• creation of related file names for listings, objects, symbol tables, maps, and other files.

In short, F$PARSE/SYS$PARSE ensures filename processing fully consistent with COPY, LINK, and other standard OpenVMS utilities. The need for special purpose code is eliminated.

That F$PARSE is able to perform this processing is not random happenstance. It is hardly serendipity that the F$PARSE's five parameters are precisely sufficient to express the different possibilities needed when processing user-specified filenames. F$PARSE is a DCL-level wrapper for the underlying SYS$PARSE RMS entry point; the parameters to the lexical function are precisely the parameters used for the underlying RMS call.

On OpenVMS, this defaulting is so fundamental that it is often below the radar, providing a leitmotif whose implications echo throughout the environment. The pervasive uniform use of file types creates a form of file tagging, where the type of different input files is implicit in the choice of utility. Consider the simple command FORTRAN TEST. Implicitly, the FORTRAN compiler defaults the names of the:

• source file to TEST.FOR;
• compiler listing to TEST.LIS (a filetype of .LIS); and
• object file to TEST.OBJ.

Similarly, the corresponding LINK command, LINK/MAP/SYMBOL_TABLE TEST processes the object file (TEST.OBJ) and produces:

• an executable file (TEST.EXE);
• a map file (TEST.MAP); and
• a symbol table file (TEST.STB).

While these two examples show the default behavior, the names, file types, and actual locations of the output files can be overridden by simply specifying the additional information on relevant DCL command qualifier (e.g., LINK/SYMBOL_TABLE=TESTDBG TEST).

Generating filenames according to these rules with allowances for user-supplied overrides would, on many platforms, require significant investment in developing, debugging, and maintaining code. There would also be the risk, more accurately a virtual certainty, that different code bases would each implement the processing in a slightly different fashion, creating inconsistencies that then lead to user confusion. Such is often the case on other operating system platforms.

On OpenVMS, F$PARSE (and its underlying direct RMS call, SYS$PARSE) reduce all of the processing to a single statement, with all of the processing for logical names and defaults handled by SYS$PARSE. This allows ordinary users to provide OpenVMS-consistent filename handling within locally- developed procedures and applications without incurring any costs for implementation or maintenance.

When enhancements are made to the underlying SYS$PARSE processing (e.g., ODS-5 extended filename support) the enhancements become available throughout the code base implicitly, and honor all of the standard OpenVMS controls (e.g., SET PROCESS/PARSE_STYLE=EXTENDED).

The on-the-ground reality is far simpler than the explanation. Consider a simple example, a command procedure that processes a file with a file type of .XYZ. The DCL required to implement the defaulting of the file type without using the multiple defaults of F$PARSEis along the lines of:

If there is more complicated processing needed, the code gets correspondingly complex. Using F$PARSE as intended presents a far shorter sequence, to wit:

This simple case is contained in the examples as OPENVMS-F$PARSE-EXAMPLE1.COM.

The more embracive cases are more instructive, and of far wider use. In these cases, a command file needs to determine the names of a series of related files, in line with the OpenVMS conventions (a series of files with the default name of the source file, an variety of different file types, and possible overrides of the output name and directory path). This is precisely the behavior familiar to users of one of the compilers on OpenVMS or the OpenVMS linker (invoked using the LINK command).

A compiler uses an input source file to generate a series of outputs. Some of these outputs are intended as some form of executable file; others are listings, maps, and other documentation. On many occasions, I have implemented command files that are “configuration compilers”. A configuration compiler uses a description of the intended configuration to produce one or more command files to be used in system operation. This greatly simplifies maintaining large numbers of machines in a production environment. In the following example, the configuration compiler inputs a .CONF file, performs a series of computations, and produces a collection of related files:

• a listing (.LIS);
• a map of the configuration (.MAP); and
• a command file to be executed at system startup (.COM)

The invoking command line is modeled after a standard compiler:

GENERATE.COM contains a simple series of lines to compute the names of its input and output files:

Except for the need to check for the existence of the source file, and checks for the error- free creation of the output files, this is the totality of the processing needed to generate the file specifiers for the input and outputs of this program. I omit the small amount of logic to process the “switches” on the command line to override the default naming of the output files, if desired.

A command file implementing this processing, on an interactive basis, is included in the example set as OPENVMS-F$PARSE-EXAMPLE3.COM.

In short, using F$PARSE and the underlying SYS$PARSE system service is a far more effective way of dealing with file specifiers than any possible manual process. Using the OpenVMS-provided functions relieves the programmer of the need to deal with the details of breaking down and reassembling the components of the file specifier.

URLs for referencing this entry

• Home
• Services
  • OpenVMS
  • Windows
  • Printers
  • PostScript
  • Architectures
  • Networks
  • Embedded Systems
• Speaking
• Upcoming Events
• TechnicalCounsel^SM News Archive
• Ruminations – An IT Blog 
• The OpenVMS Consultant 
• Presentations
• Publications
• Technology Demonstrations
• Bookstore
• Contact Us

http://www.rlgsc.com

+1 (718) 463 1079