HP OpenVMS Systems Documentation
OpenVMS User's Manual
12.12 Understanding Symbol Substitution
In certain contexts, DCL uses a string of characters beginning with a letter as a symbol name or a lexical function. In these contexts, DCL tries to replace the symbol or lexical function with its value. Replacing a symbol with its current value is referred to as symbol substitution. If you use a symbol or lexical function in any other context, you must use a substitution operator to request symbol substitution.
DCL automatically evaluates symbols and lexical functions when they are used as follows:
In the following examples, the command interpreter uses any character string beginning with an alphabetic character as a symbol name and any string beginning with a number or with the radix operator (%) as a literal numeric value.
12.12.1 Forced Symbol Substitution
To force substitution of a symbol that is not in one of the positions listed, enclose the symbol with apostrophes ('), as follows:
To force substitution of a symbol within a quoted character string, precede that symbol with two apostrophes (') and follow it with a single apostrophe (') as follows:
When processing a command line, DCL replaces symbols with their values in the following order:
The following example demonstrates the effect of the order in which DCL substitutes symbols. First, the symbols PN, FILE1, and NUM are defined:
Given the preceding symbol definitions, the following commands print the file named [BOLIVAR]TEST_CASE.TXT:
In the first command, forced substitution causes NUM to become 1, making FILE''NUM' become FILE1. If you enter the command SHOW SYMBOL FILE, you see that FILE = " 'FILE1' ".
The second command performs two substitutions. First, 'FILE' is substituted with 'FILE1'. 'FILE1' also requires substitution because it is enclosed in apostrophes ('). Automatic substitution causes FILE1 to become [BOLIVAR]TEST_CASE.TXT. This file name is then appended to the value of PN, which is PRINT/NOTIFY. The resulting string is as follows:
12.12.2 Symbol Substitution Operators
You can use a substitution operator to request symbol substitution in places where DCL does not usually perform it. DCL accepts two substitution operators:
The difference between these two operators is the time when the substitution occurs. Symbols preceded by apostrophes are substituted during the first phase of DCL command processing; symbols preceded by ampersands are substituted during the second phase. For more information on the phases of command processing, see Section 12.13.
The apostrophe (') is the most frequently used substitution operator. Use it to request symbol substitution when you use a symbol in place of a command parameter or qualifier. Use the apostrophes to request symbol substitution on the right side of a string assignment (:=) statement.
To request symbol substitution within a quoted character string, place two apostrophes before the symbol name and one apostrophe after it.
In the following example, the TYPE command requires a file specification. The apostrophes indicate that LIT is a symbol that must be evaluated. If you omit the apostrophes, DCL looks for a file called LIT.LIS (.LIS is the default file type for the TYPE command):
In the following example, the value for NAME is substituted so that FILE becomes REPORT.DAT:
In the following example, the current value of the symbol NAME is FRED:
Therefore, MESSAGE has the following value:
The ampersand (&) is also a substitution operator that the command interpreter recognizes. In many cases, the apostrophe and the ampersand perform the same function. Ampersands are most effective as substitution operators when they are used with apostrophes to affect the order in which substitution is performed.
The action the command interpreter takes when a symbol is undefined depends on the context of the command. For more information, see Section 12.13.5.
In the first command shown here, the command interpreter replaces the symbol NAME with its current value during the first phase of command processing (scanning). The second command replaces the symbol NAME with its current value during the second phase of command processing (parsing). The result is the same, even though the methods are different:
In the following example, the ampersand (&) is used with apostrophes to affect the substitution order:
First, the command interpreter evaluates the symbol enclosed by apostrophes ('COUNT'). The result is as follows:
Second, the command interpreter evaluates the symbol preceded by an ampersand (P1). The result is as follows:
In the following example, apostrophes are used with both P and COUNT:
Working left to right, the command interpreter attempts to evaluate P. Because P is not a defined symbol, DCL gives it a null value. Next, it evaluates the symbol COUNT. The result is as follows:
In the following example, A is equated to the current value of B:
The ampersand (&) does not cause symbol substitution when it is used inside quotation marks (" "). Therefore, when the assignment is made, the value of B is not substituted. However, the TYPE command displays MYFILE.DAT. This occurs because the command interpreter first substitutes the value &B for A. Next, it substitutes MYFILE.DAT for the symbol &B. If you were to redefine B, the result of the TYPE command would change accordingly.
Observe the following rules for using ampersands:
12.13 The Three Phases of Command Processing
The command interpreter performs symbol substitution in three phases.
In command input scanning (also called the lexical input phase), the
command interpreter evaluates symbols preceded by apostrophes from left
to right. Symbols that are preceded by single apostrophes are
translated iteratively, as described in Phase 1 Substitution. Symbols preceded
by two apostrophes are not translated iteratively.
In the command parsing phase:
Symbol substitution during this phase is not iterative.
During the expression evaluation phase:
Note that the command interpreter does not scan any lines that are read as input data by commands or programs executed within a command procedure. Therefore, the command interpreter does not perform symbol substitution within these data lines.
In the following example, the program AVERAGE reads 55, 57, and 9999 from SYS$INPUT (the command input stream). These data lines are never read by the command interpreter. If you enter symbol names as input, they are not evaluated:
12.13.4 Repetitive and Iterative Substitution
Symbol substitution can be repetitive or iterative:
When you use an apostrophe (') to request symbol substitution, the command interpreter performs iterative substitution during the first phase of command processing.
Substitution using apostrophes is not iterative when a symbol is included in a quoted character string.
In the following example, the substitution is iterative:
After the statement B = 'A' the resulting value of the symbol B is 5 because:
Note, however, what happens when you include A in a quoted character string:
In this case, B has the value 'MAC'. The symbol name A is replaced only once because substitution is not iterative within quoted character strings.
The command interpreter performs iterative substitution automatically only when an apostrophe is in the command line. In some cases, you may want to nest command synonym definitions.
In the following example, when EXEC is processed, the command interpreter performs substitution only once:
The result is the string 'MAC'. The command interpreter displays an error message because it does not recognize MAC as a command. This error occurs because during the first phase of command processing, no substitution is performed (the string EXEC is not delimited by apostrophes). During the second phase, the string 'MAC' is substituted for EXEC because EXEC is the first value on the command line. This substitution is not iterative. Therefore, even though 'MAC' is delimited by apostrophes, no additional substitution is performed.
To use the command synonym EXEC correctly, enclose it in apostrophes:
In this case, the symbol EXEC is evaluated during the first phase of command processing. Because this substitution is iterative, ('MAC') is also evaluated and the string TYPE A.B is substituted.
When the command interpreter analyzes an expression in a command, any symbols specified in the expression are replaced only once. You can, however, force iterative substitution by using an apostrophe or an ampersand in the expression. When you force iteration in this way, you must remember the following:
Note, however, that if substitution does not result in a valid symbol name, the command fails.
The following example shows iterative substitution in an IF command:
When the command interpreter scans this line, it replaces the symbol COUNT with its current value. The result is as follows:
Because this string has no apostrophes, the command interpreter does not perform any more substitution. However, when the IF command executes, it automatically evaluates the symbol name P1 and replaces it with its current value.
In the following example, the symbol name FILENAME is invalid:
The command interpreter replaces the symbol FILENAME with its current value (A.B). The result is as follows:
When the IF command executes the command line, A.B is not a valid symbol and an error occurs. For this IF command to be processed correctly, omit the apostrophes, as follows:
12.13.5 Undefined Symbols
If a symbol is not defined when it is used in a command line, the command interpreter either displays an error message or replaces the symbol with a null string, depending on the context. The rules are as follows:
The following example shows how the command interpreter processes an undefined symbol that is preceded by an apostrophe:
When the symbol FILE is created, the symbol FILE_TYPE is replaced with its current value. If FILE_TYPE is not defined, the command interpreter replaces FILE_TYPE with a null string. The absence of a file type in the file specification causes the PRINT command to use the default file type .LIS. Thus, the file specification is interpreted as MYFILE.LIS.
In the following example, the expression is evaluated during the third phase of command processing:
The symbol B is undefined, so the command interpreter cannot evaluate
You can also invoke a command procedure (.COM file type) or executable image (.EXE file type) from DCL level without defining a symbol for that procedure. Using automatic foreign commands, DCL can search a specific set of directories for a command procedure or executable image and run it automatically.
When you enter a command verb that is not a DCL symbol and that is not in the DCL command tables, the system usually displays the following message:
However, if the logical name DCL$PATH is defined (and is not blank), DCL instead performs an RMS $SEARCH for any file that contains the invalid verb in its file name and DCL$PATH:.* as the default file specification.
If DCL finds a .COM or .EXE file, DCL will automatically execute that file with the rest of the command line as its parameters. (This behavior is similar to the PATH options found in DOS, UNIX, and other operating systems.)
In the following example, the DCL symbol SYSGEN is no longer needed. DCL looks in the SYS$SYSTEM directory and finds SYSGEN.EXE. DCL acts like the symbol "SYSGEN" was defined as "$SYS$SYSTEM:SYSGEN" which causes the SYSGEN image to be activated as a foreign command.
In the following example, SS does not need to be defined as "@SS.COM" because DCL will automatically search the SYS$SYSTEM directory for SS.COM or SS.EXE. If that fails, DCL will search the current directory for SS.COM or SS.EXE.
In the example, DCL locates SS.COM and acts like "SS" had been a symbol defined as "@SS.COM". The command procedure is activated with the rest of the command line parsed as parameters. Note that "SS.EXE" does not invoke the image SS.EXE, but instead invokes SS.COM with two parameters, the first being the text string ".EXE". This is consistent with the way command parsing and symbol substitution is performed by the OpenVMS operating system.