| Both sides previous revisionPrevious revision | Next revisionBoth sides next revision |
| symbol_substitution [2018/11/14 23:19] – minor subtitle tweak lricker | symbol_substitution [2018/11/19 23:54] – Add section for ampersand string substitution lricker |
|---|
| - Substitute (interpolate, or insert) the **value** of a //[[DCL Lexical Function]]// into a quoted-string of text | - Substitute (interpolate, or insert) the **value** of a //[[DCL Lexical Function]]// into a quoted-string of text |
| |
| You'll find these techniques and uses of string substitution primarily in DCL command files, or scripts, which exploit many of the same programming techniques as those "more modern" scripting languages. | You'll find these techniques and uses of string substitution primarily in DCL command files, or scripts, which exploit many of the same programming techniques as those more modern scripting languages. |
| |
| ==== String Substitution Examples ==== | ==== String Substitution Examples ==== |
| </code> | </code> |
| |
| Focus on the symbol/variable name '''dev''' as surrounded by one single-quote ''''' mark on either end (as underlined by the ''^^^^^'' carets). That notation -- '''dev''' -- means "substitute the //value//, the //contents//, of the named //variable// as a string of characters right here, completely replacing the '''dev''' with that string of text." | Focus on the symbol/variable name '''dev''' as surrounded by //__one__// //single-quote mark// (''''', also called an //apostrophe//) on either end (as underlined by the ''^^^^^'' carets). That notation -- '''dev''' -- //means// "substitute the //value//, the //contents//, of the named //variable// as a string of characters right here, completely replacing the '''dev''' with that string of text." |
| |
| Assume that the contents of variable ''dev'' is exactly the string of characters "''DSA2:''". After that string substitution is done, what the DCL command interpreter "sees" and processes is exactly this: | Assume that the contents of variable ''dev'' is exactly the string of characters "''DSA2:''". After that string substitution is done, what the DCL command interpreter "sees" and processes is exactly this: |
| </code> | </code> |
| |
| Here, you see a slightly different notation: Instead of '''dev''', with a one single-quote mark ''''' at each end of the variable's name, we see //two// leading single-quote marks at the //beginning//, and //one// single-quote mark //following// that variable name -- why? | Here, you see a slightly different notation: Instead of '''dev''', with a //single// single-quote mark (''''') at each end of the variable's name, we see //two// leading single-quote marks at the //beginning//, and //one// single-quote mark //following// that variable name -- Why? |
| |
| This is still //valid notation// for string substitution, but here the substitution is done __//within//__ a double-quoted literal string of characters: | This is still //valid notation// for string substitution, but here the substitution is done __//within//__ a double-quoted (''"'') literal string of characters: |
| |
| <code> | <code> |
| ==== String Substitution Punctuation and Notation ==== | ==== String Substitution Punctuation and Notation ==== |
| |
| It is //vitally important// that you see -- be able to read and recognize -- the **//difference//** between **single-quote marks** ''''' (sometimes verbally called a "tick mark" or "tick") and **double-quote marks** ''"'' (sometimes called just a "quote"). //Novice DCL programmers who fail to make these important distinctions, both when they read DCL scripts and when they write/code them, get quickly into deep problems and errors.// | It is //vitally important// that you //see// -- be able to read and recognize -- the **//difference//** between **single-quote marks** (''''') (also called a "tick mark" or "//tick//" or "apostrophe") and **double-quote marks** (''"'') (sometimes called just a "//quote//"). //Novice DCL programmers who fail to make these important distinctions, both when they read DCL scripts and when they write/code them, get quickly into deep problems and errors.// |
| |
| So, from the above examples, you can derive two rules: | So, from the above examples, you can derive two rules: |
| |
| - If you are string-substituting directly onto the command line, anywhere **//not//** within a double-quoted, literal text string, put a single-quote mark ''''' on either/both ends of the variable's name; //surround the variable's name with single-quote marks//. | - If you are string-substituting directly onto the command line, anywhere **//not//** within a double-quoted, literal text string, put a single-quote mark ''''' on either/both ends of the variable's name; //surround the variable's name with single-quote marks//. |
| |
| - If you are string-substituting within a literal, double-quoted string of characters, //put two single-quote marks in front of the variable's name, and one single-quote mark at its end//. | - If you are string-substituting within a literal, double-quoted string of characters, //put two single-quote marks in front of the variable's name, and one single-quote mark at its end//. |
| |
| ==== Command File Parameters P1 thru P8 ==== | ==== Command File Parameters P1 thru P8 ==== |
| |
| For the purposes of string substitution (interpolation), the command line parameters ''P1'', ''P2'', ''P3'', ''P4'', ''P5'', ''P6'', ''P7'' and ''P8'' are simply DCL local variables within command files, and therefore everything you've learned above applies to these parameter variables for string substitution/replacement. | For the purposes of string substitution (interpolation), the command line parameters ''P1'', ''P2'', ''P3'', ''P4'', ''P5'', ''P6'', ''P7'' and ''P8'' are simply DCL local variables within command files, and therefore everything you've learned above applies to these parameter variables for string substitution/replacement. For more info on this, see the wiki article [[Command File Parameters]]. |
| |
| Another command file example may suffice to demonstrate this: | Another command file example may suffice to demonstrate this: |
| |
| Copy this simple com-file to your own system and play with it -- experiment with different combinations of com-line parameters and see what happens! | Copy this simple com-file to your own system and play with it -- experiment with different combinations of com-line parameters and see what happens! |
| | |
| | ==== That Tricky Little & ==== |
| | |
| | You might have noticed that the ''tick-varname-tick'' and ''"tick-tick-varname-tick"'' tricks are not the only ways to get DCL to do string substitution for the contents of a variable. Or you might stumble onto a piece of DCL command-file code that looks something like this: |
| | |
| | <code> |
| | $ P3 = "IMPORTANT_FILE.DATA" |
| | $ ... |
| | $ ! later... |
| | $ COUNT = 3 |
| | $ TYPE &P'COUNT' |
| | $ ... |
| | </code> |
| | |
| | ...and you immediately wonder: What the heck is that ''&P'COUNT''' construction used as the ''TYPE'' command's parameter? The short answer is that the ampersand (&) is a delayed string substitution operator, and its substitution is done only when any and all other tick-mark string substitutions are done (for the construct). |
| | |
| | Buried deep in the official VMS documentation set (specifically, see the **OpenVMS User's Manual** (Order Number: AA–PV5JF–TK, June 2002)", Chapter 12, "Defining Symbols, Commands and Expressions," Section 12.12,2 "Symbol Substitution Operators," pp 12-26 through 12-31, for all the details) is information on how to use the seldom-encountered ampersand (''&'') string substitution operator. |
| | |
| | Honestly, you'll very seldom, if ever, need to use the ''&''-operator for string substitution in DCL -- it is used (and useful) for only a //rarely// encountered use-case. Here are the rules and use, just in case you ever run into it when reading someone else's com-file, or if you need it yourself: |
| | |
| | * DCL processes single-quoted symbol (ticked variable) names from left to right in a command line, replacing any such ''tick-varname-tick'' and ''"tick-tick-varname-tick"'' instances with the value of each symbol as encountered. This is called //forced substitution// (or requested substitution). |
| | |
| | * Symbols preceded by single apostrophes (not in double-quotes: ''tick-varname-tick'') are translated //iteratively//; symbols preceded by double apostrophes (as in double-quotes ''"tick-tick-varname-tick"'') are not (substitution inside of double-quotes is once-only, when encountered). |
| | |
| | * DCL performs iterative substitutions in multiple phases or passes (for a given construct like ''&P'COUNT'''): First, any and all single-tick-mark substitutions (''tick-variable-tick'') are done -- yes, an early string substitution could result in a subst-value which itself is single-tick-mark surrounded, hence iterative substitution (very rarely done, and confusing!); then, finally, the ''&''-substitution is done on whatever symbols (variable) name results from the earlier substitution. (Confused yet? Take fresh courage: this is a rare use case!) |
| | |
| | The upshot of this is simply that the ''&''-substitution operator delays its own substitution until any and all earlier tick-mark-substitutions have been done. So, looking again at the previous example: |
| | |
| | <code> |
| | $ TYPE &P'COUNT' |
| | --becomes--> $ TYPE &P3 |
| | --becomes--> $ TYPE IMPORTANT_FILE.DATA |
| | ...and the contents of |
| | the IMPORTANT_FILE.DATA file |
| | are displayed. |
| | </code> |
| | |
| | |
