| Both sides previous revisionPrevious revisionNext revision | Previous revisionLast revisionBoth sides next revision |
| symbol_substitution [2018/11/14 23:19] – minor subtitle tweak lricker | symbol_substitution [2018/11/20 18:36] – move "Literal Quotes in DCL Strings" to separate wiki article 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 ==== |
| Lines ''1'' through ''4'' are just internal documentation, and inform us that the [[Command File Parameters|DCL parameter symbol]] ''P1'' is used to collect the __name of the device to show__ from the command line; if the user does not specify that device name on the command line (tested at Line ''5''), s/he is prompted for it at Line ''6''; if P1 is specified on the command line, its value is simply copied to the variable (symbol) ''dev'' at Line ''7''. | Lines ''1'' through ''4'' are just internal documentation, and inform us that the [[Command File Parameters|DCL parameter symbol]] ''P1'' is used to collect the __name of the device to show__ from the command line; if the user does not specify that device name on the command line (tested at Line ''5''), s/he is prompted for it at Line ''6''; if P1 is specified on the command line, its value is simply copied to the variable (symbol) ''dev'' at Line ''7''. |
| |
| In either case, that variable ''dev'' is recomputed (overwritten) by assigning the result of the lexical function ''F$GETDVI'' at Line ''8''; the function's argument ''"DEVNAM"'' makes it look up the proper physical device name for whatever is specified as its first input argument (again by the ''dev'' variable's initial value). And Line ''12'' re-uses that lexical function to test (determine) whether or not that physical device is a Shadow-Set Volume. | In either case, that variable ''dev'' is recomputed (overwritten) by assigning the result of the __lexical function__ ''F$GETDVI'' at Line ''8'' (an example of #3 from the list above); the function's argument ''"DEVNAM"'' makes it look up the proper physical device name for whatever is specified as its first input argument (again by the ''dev'' variable's initial value). And Line ''12'' re-uses that lexical function to test (determine) whether or not that physical device is a Shadow-Set Volume. |
| |
| The __actual examples of string substitution__ happen at Lines ''11'', ''13'', ''14'' and ''16'' -- | The __actual examples of string substitution__ (#2 from the list above) happen at Lines ''11'', ''13'', ''14'' and ''16'' -- |
| |
| Lines ''11'', ''14'' and ''16'' are of the form (with variations): | Lines ''11'', ''14'' and ''16'' are of the form (with variations): |
| </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//. |
| |
| ==== Producing Quotes in Quotes ==== | ==== Producing Quotes in Quotes ==== |
| |
| What if you want to produce literal double-quote marks to be printed in a string of text? -- like: | What if you want to produce literal double-quote marks to be printed in a string of text? -- like this: |
| |
| <code> | <code> |
| </code> | </code> |
| |
| When you want a //literal __double__-quote mark// to appear in a literal text string, you can produce it in either of these two ways: | ...or surround some text with single quotes? -- like this: |
| <code> | <code> |
| $ WRITE sys$output "This is ""double-quoted-text""." | This is 'singled-quoted-text'. |
| | ^^ ^^ | ! Use two double-quotes where you want one printed, | |
| ^ ^ ! and these two double-quotes delimit the literal string. | |
| </code> | </code> |
| |
| ...or: | These are pretty common use-cases -- See the wiki article [[Literal Quotes in DCL Strings]] for full details. |
| <code> | |
| $ DQUOTE = """" ! Create a variable whose content/value is a single double-quote mark! | |
| $ WRITE sys$output "This is " + DQUOTE, "double-quoted-text" + DQUOTE + "." | |
| $ ! This ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| $ ! concatenates several substrings (including the value of DQUOTE) into | |
| $ ! a single string for printing. | |
| </code> | |
| | |
| ...or: | |
| <code> | |
| $ DQUOTE = """" ! Create a variable whose content/value is a single double-quote mark! | |
| $ message = "This is " + DQUOTE, "double-quoted-text" + DQUOTE + "." | |
| $ ! This ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| $ ! concatenates several substrings (including the value of DQUOTE) into | |
| $ ! a single string variable for any purpose, including printing... | |
| $ WRITE sys$output message | |
| </code> | |
| | |
| ...or even: | |
| <code> | |
| $ DQUOTE = """" ! Create a variable whose value is a single double-quote mark! | |
| $ WRITE sys$output "This is ", DQUOTE, "double-quoted-text", DQUOTE, "." | |
| $ ! The WRITE ^^^^^^^^^^ ^^^^^^ ^^^^^^^^^^^^^^^^^^^^ ^^^^^^ ^^^ | |
| $ ! command takes several expressions (here, just literal strings) and | |
| $ ! concatenates them itself for printing. | |
| </code> | |
| | |
| This suggests a similar way to produce a //literal __single__-quote mark (tick)// in text: | |
| <code> | |
| $ SQUOTE = "'" ! Create a variable whose value is a single single-quote mark! | |
| $ WRITE sys$output "This is ", SQUOTE, "singe-quoted-text", SQUOTE, "." | |
| </code> | |
| | |
| ...or: | |
| <code> | |
| $ SQUOTE = "'" ! Create a variable whose value is a single single-quote mark! | |
| $ WRITE sys$output "This is " + SQUOTE + "singe-quoted-text" + SQUOTE + "." | |
| </code> | |
| | |
| ...both produce: | |
| <code> | |
| This is 'single-quoted-text'. | |
| </code> | |
| |
| ==== 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-varname-tick'') are done -- yes, an early(er) 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(s). Confused yet? Take fresh courage: this is a rarely used feature of DCL! |
| | |
| | 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> |
| | |
