DCL Command Procedure Parameter Hinting

I write and modify a fair number of DCL command procedures; both for my own use and as part of my consulting practice. DCL command procedures allow one to effectively extend the DCL environment beyond what is provided by baseline OpenVMS.[1] Many, if not most, of these command procedures have parameters.[2] The parameter(s) may seem obvious in some cases; in other cases, the parameters are more complex and/or extensive.

There is also a question of context. When one works with a single system and suite of command procedures, parameters become familiar with repeated use. However, uninterrupted repeated use is often a short-term luxury. Memory fades over longer time spans. What is used daily is familiar, what was used a week or a month ago is far less so. Dealing with multiple client systems magnifies the challenge.

One can always edit or type the command file in question to refresh one’s memories. However, reading command files takes time and attention, both frequently in short supply. We can do better.

In some systems, it is common to provide for some manner of assistance when a user types a command. The -? option in many UNIX, linux and Windows command lines are good examples. Another approach is to respond with hints when the command is entered without parameters.

I have found this hinting valuable when using OpenVMS command procedures. It is an easy way to remind the user of options, default filetypes, and other inputs.[3] It is also simplicity itself to implement, often merely a question of adding a small number of lines to the pro forma used when writing command procedures.

Consider a command file that processes an input file to produce an output file, FINDCOMPANIES.COM. Less than 10 lines of code provide a simple hint, as shown below.

$ F$LENGTH(P1) .EQ. 0
@FINDCOMPANIES <input-file> <output-file>
$ EXIT 1

With this addition, executing the command procedure without parameters yields a reminder of the correct syntax, as shown below.

$ @findcompanies
@FINDCOMPANIES <input-file> <output-file>

Using the hint is far better than editing or typing the file to analyze the code. The hint is also available to users who either do not have access to FINDCOMPANIES.COM due to file protections or access controls, as well as users who are not DCL-literate.

Command procedure hinting is a small thing, but small things often repeated add up to significant time and effort savings. It takes less than a minute to edit the pro forma to provide the hint information, and reduces confusion, error, and time each time the command procedure is used.


[1] R. Gezelter (2015, September 29) Extending DCL with Command Files,
[2] VMS Software, Inc. (2020, July) VSI OpenVMS User's Manual Section 14.2 Using Parameters to Pass Data, Section
[3] R. Gezelter (2010, October 18) Filename Alchemy - F$PARSE Defaulting


URLs for referencing this entry

Picture of Robert Gezelter, CDP
RSS Feed Icon RSS Feed Icon
Follow us on Twitter
Bringing Details into Focus, Focused Innovation, Focused Solutions
Robert Gezelter Software Consultant Logo
+1 (718) 463 1079