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
$ THEN
$ TYPE SYS$INPUT
@FINDCOMPANIES <input-file> <output-file>
$ EXIT 1
$ ENDIF
$!

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.

Notes

^[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 4.8.3.2
^[3]	R. Gezelter (2010, October 18) Filename Alchemy - F$PARSE Defaulting

References

Gezelter, R (2015, September 29) Extending DCL with Command Files 2015 OpenVMS Bootcamp, Nashua, New Hampshire Retrieved from http://www.rlgsc.com/openvms-bootcamp/2015/extending-dcl-with-command-files.html on September 5, 2022
Gezelter, R (2010, October 18) Filename Alchemy - F$PARSE Defaulting Retrieved from http://www.rlgsc.com/blog/openvms-consultant/filename-alchemy-with-fparse.html on September 5, 2022>
Gezelter, R (1995, December 5) DCL Lexicals: OpenVMS Jujitsu Fall 1995 US DECUS Symposium, Session VS012, San Francisco, California Retrieved from http://www.rlgsc.com/decus/usf95/vs012.pdf on September 5, 2022
VMS Software Inc. (2021, January) VSI OpenVMS DCL Dictionary: A—M Document Number: DO–DDCLAM–01A Retrieved from https://docs.vmssoftware.com/docs/vsi-openvms-dcl-dictionary-a-m.pdf on September 5, 2022
VMS Software Inc. (2020, July) VSI OpenVMS User's Manual Document Number: DO-OSUSMN-01A Retrieved from https://docs.vmssoftware.com/docs/vsi-openvms-user-s-manual.pdf on September 5, 2022
VMS Software Inc. (2020, May) VSI OpenVMS DCL Dictionary: N—Z Document Number: DO–DDCLNZ–01A Publication Date: May 2020 Retrieved from https://docs.vmssoftware.com/docs/vsi-openvms-dcl-dictionary-n-z.pdf on September 5, 2022

URLs for referencing this entry

Long:	http://www.rlgsc.com/blog/openvms-consultant/dcl-procedure-parameter-hinting.html
Short:	http://rlgsc.com/r/20220906.html