DCL Symbols: Starting at the Beginning

Those unfamiliar with OpenVMS DCL symbol substitution often find it a source of confusion. This powerful DCL feature is avoided out of misunderstanding. This is very unfortunate, since symbol substitution dramatically shortens development tasks and reduces the cost of ongoing maintenance.

The fact that DCL symbol substitution can be used for some of the same purposes as logical names admittedly contributes to some of the confusion.

However, while logical names and DCL symbols can be used for some similar purposes, they are completely different mechanisms. A previous series of articles in this column discussed the fundamentals of logical names (The OpenVMS Consultant: Logical Names (Part 1) is the first article in that series).

Logical names are used implicitly by RMS and other OpenVMS system services. They can be explicitly defined and accessed from within user-mode programs using system service and run-time library calls, and can be explicitly accessed from within DCL using the F$TRNLNM lexical function. Some logical name tables (e.g., LNM$SYSTEM, LNM$GROUP, and LNM$JOB) are accessible outside the scope of an individual process).

By contrast, symbols are purely creatures of DCL and are limited by the DCL implementation to certain semantics and uses. They are restricted to the context of a single process, although by default, both local and global symbols are copied to sub-processes created using the SPAWN command or LIB$SPAWN run-time library routine.

As a simple example, consider the common DCL command:

        $ directory/size/date *.lis

This command will produce a listing of all files in the current directory with the file type of *.lis together with the size and creation date of each file. The command is not complex, but it requires typing 25 characters. Even using the OpenVMS DCL feature of allowing for only enough of verbs and qualifiers to resolve ambiguity, 17 characters must be typed.

This example is only a simple case. It is not uncommon to have commands that require more than 80 characters (a common problem across all platforms; many utility functions have many different parameters).

The simple OpenVMS solution to this is to use DCL symbols to define command shortcuts. This eliminates the need to type the entire command each time:

        $ dsd :== directory/size/date

Once this symbol is defined in our process, DCL will automatically substitute the full value when that symbol appears as the first item in a DCL statement. So there is far less typing involved, to wit:

        $ dsd *.lis

For the simple case of a command, with extremely simple parameters, this works quite well. When there is a more complex need, with more extensive processing, there is often a need to use DCL symbols in a more advanced fashion to build and dissect strings needed by the computation.

Command shortcuts are merely the simplest use of a feature with far more capabilities. Using the more advanced capabilities requires the use of a DCL command file.

So, let us start by building a small command file to take a file type, without the accompanying punctuation, and list all files of that type in the current directory.

        $! DCL Program to List Directory Contents
        $! Author:  Robert Gezelter , 1-March-2009
        $ FILETYPE = P1
        $ DIRECTORY/SIZE/DATE *.'FILETYPE'
        $ EXIT $STATUS

Admittedly, this five line example is simplistic. However, it is sufficient to have the same structure as far larger DCL command procedures, even those consisting of hundreds or thousands of lines of code.

The comment lines identifying the file, its author, and its date of origin are the first common feature. Often, these comments (lines beginning with $!) include information about the purpose, background and history of the command procedure.

The remaining three statements each fall into a different category: setup, work, and returning status.

The setup in this procedure is straightforward. It begins by making use of the DCL feature that parses the input line into separate sub-strings separated by whitespace (e.g., space, tab) and separates it into a defined set of DCL local symbols, numbered P1 through P8. As convenient as it is for DCL to place the parameters in P1 through P8, these parameters are not particularly mnemonic. [do they survive sub procedures]

A common first step is to convert the DCL-supplied parameters into local symbols that accurately reflect their contents. The line $ FILETYPE = P1 accomplishes this function in our sample.

The actual processing is done by the second command, the $ DIRECTORY/SIZE/DATE *.'FILETYPE' command. Here, a DCL symbolic substitution is marked by a symbol name wrapped with ASCII single quote (“'”) characters.

The last step is to return the result of the command procedure to whatever invoked it. Often, this is the user themselves at the command prompt, but it could just as easily be an outer command procedure. Just as conventional programs are often separated into different routines; it is common to have both internal and external DCL command procedures.

The preceding is admittedly one of the more simple uses of symbols. Future columns will review more advanced uses of DCL symbols.

URLs for referencing this entry

Picture of Robert Gezelter, CDP
RSS Feed Icon RSS Feed Icon
Add to Technorati Favorites
Follow us on Twitter
Bringing Details into Focus, Focused Innovation, Focused Solutions
Robert Gezelter Software Consultant Logo
http://www.rlgsc.com
+1 (718) 463 1079