1 03/23/84  exec_com, ec
  2 
  3 Syntax:  ec {-control_args} path {ec_args}
  4 
  5 
  6 Syntax as an active function:  [ec {-control_args} path {ec_args}]
  7 
  8 
  9 Function: executes programs written in the exec_com language, used to
 10 pass command lines to the Multics command processor and pass input
 11 lines to commands reading input. The syntax described here is known
 12 as Version 2, for which the first line of the exec_com program must
 13 be the line consisting of "&version 2". For a description of Version 1
 14 syntax, type "help v1ec".
 15 
 16 
 17 Arguments:
 18 path
 19    is the pathname of an exec_com program, written using the constructs
 20    described in this info segment. The ec suffix is assumed if not
 21    specified. The star convention is NOT allowed.
 22 ec_args
 23    are optional arguments to the exec_com program, and are substituted
 24    for parameter references such as &1. See "List of parameters".
 25 
 26 
 27 Control arguments:
 28    (All control arguments to the exec_com command must precede the
 29     pathname of the exec_com program.)
 30 -no_trace KEYWORD_LIST
 31    turns off tracing of specified types of exec_com lines, overriding
 32    any &trace statements in the exec_com for those types of lines.
 33    The default is -trace_default. KEYWORD_LIST is composed of any of
 34    the keywords "command", "comment", "control", and "input", separated
 35    by commas with no intervening space.
 36 -trace KEYWORD_LIST
 37    turns on tracing of specified types of exec_com lines, overriding
 38    any &trace statements in the exec_com for those types of lines.
 39    The default is -trace_default. KEYWORD_LIST is composed of any of
 40    the following, separated by commas with no intervening space:
 41           command, comment, control, input, all_types
 42                turns on tracing for the corresponding type of line.
 43           unexpanded, expanded, all, all_expansions, both
 44                affects how the expansion of lines is traced. These are
 45                equivalent to &unexpanded, &expanded, &all, and &both in
 46                &trace statements inside the exec_com. The keyword
 47                "all_expansions" is equivalent to "all".
 48           prefix=STR
 49                specifies a prefix for traced lines, equivalent to
 50                &prefix in &trace statements.
 51           osw=SWITCHNAME
 52                specifies an I/O switch on which to write the trace,
 53                equivalent to &osw in &trace statements.
 54 -trace_default
 55    uses &trace statements in the exec_com and the default tracing modes
 56    to determine what and how to trace. (Default)
 57 
 58 
 59 List of parameters:
 60 &1 - &9
 61    expand to the 1st through 9th ec_args, or to defaults defined by a
 62    &default statement or to null string if there is no corresponding
 63    ec_arg. The string &0 is invalid.
 64 &(1) - &(9)
 65    are synonyms for &1 - &9.
 66 &(11), &(12), etc.
 67    expands to the corresponding ec_arg, or to a default defined by
 68    &default or to null string if there is no corresponding ec_arg.
 69    The parentheses are required when there are two or more digits.
 70 
 71 
 72 &q1 - &q9
 73 &q(1), &q(11), etc.
 74    expands to the corresponding argument with quotes doubled according
 75    to the quote depth of the surrounding context. See "Notes on
 76    quoting". This parameter ensures that quotes in the argument to
 77    exec_com are handled correctly under the quote-stripping action of
 78    the command processor.
 79 &r1 - &r9
 80 &r(1), &r(11), etc.
 81    expands to the corresponding argument enclosed in an added layer of
 82    quotes, and internal quotes doubled accordingly. See "Notes on
 83    quoting". This parameter keeps the value of the argument as a
 84    single unit after one layer of quote-stripping by the command
 85    processor.
 86 
 87 
 88 &n
 89    expands to the number of ec_args specified to exec_com.
 90 &f1 - &f9
 91 &f(1), &f(11), etc.
 92    expands to a list of the Nth through last ec_args separated by
 93    spaces. If N is greater than the value of &n, expands to null string.
 94 &qf1 - &qf9
 95 &qf(1), &qf(11), etc.
 96    expands to a list of the Nth through last ec_args, with quotes
 97    doubled, separated by spaces. If N is greater than the value of &n,
 98    expands to null string. This parameter is equivalent to:
 99    &qN &qN+1 &qN+2 ....
100 
101 
102 &rf1 - &rf9
103 &rf(1), &rf(11), etc.
104    expands to a list of the Nth through last ec_args, individually
105    requoted, separated by spaces. If N is greater than the value of
106    &n, expands to null string. This parameter is equivalent to:
107    &rN &rN+1 &rN+2 ....
108 &f&n, &qf&n, &rf&n
109    expands to the last ec_arg specified to exec_com, either as is,
110    with quotes doubled, or requoted.
111 
112 
113 &condition_info_ptr, &cond_info_ptr
114    inside an &on unit (see "List of condition handling statements"),
115    expands to a virtual pointer (<segment_number>|<offset>) to the
116    condition_info structure for the condition that was signalled.
117    Programs can be written to interpret the structure for a particular
118    condition.
119 &condition_name, &cond_name
120    inside an &on unit (See "List of condition handling statements"),
121    expands to the name of the condition that caused the &on unit to
122    be invoked. Outside an &on unit, expands to null string.
123 &ec_dir
124    expands to the pathname of the directory containing the exec_com
125    currently running. It can be used to call other exec_com's in the
126    same directory.
127 
128 
129 &ec_name
130    expands to the entryname of the exec_com currently running, with
131    any ec or absin suffix removed (the absin suffix is for an exec_com
132    invoked by the absentee facility; type "help ear").
133    This parameter can be used to simulate entrypoints in an exec_com
134    segment, by adding multiple names to the segment and transferring
135    to a different &label depending on the name invoked.
136 &ec_path
137    expands to the expanded, suffixed pathname of the current exec_com.
138 &ec_switch
139    expands to the name of the I/O switch over which the exec_com
140    interpreter is reading the exec_com.
141 &handlers
142    expands to a list of condition names for which &on handlers are
143    currently in effect. (See "List of condition handling statements").
144    Condition names are individually requoted and separated by spaces.
145    To test whether a handler is currently in effect for NAME, type:
146           &if [or [equal NAME (&handlers)]] &then ...
147 
148 
149 List of value expressions:
150    (All of these constructs can be nested arbitrarily inside each
151    other.)
152 &(NAME)
153    expands to the value assigned to the variable NAME by a previous
154    &set statement in the same exec_com. If NAME contains &'s, it is
155    first expanded. Therefore, &() constructs can be nested. However,
156    &'s in the expansion are not re-expanded. A second level of
157    expansion must be specified, therefore, by &(&()).
158    If NAME has not been assigned a value by &set, an error occurs.
159    Variable names are allowed to contain any characters except &
160    and cannot consist solely of digits.
161 
162 
163 &(N)
164    where N is a positive integer, expands to the value of the Nth
165    ec_arg to exec_com, or if there is no Nth ec_arg, to the last
166    default value assigned to argument N by a &default statement, or if
167    no default value was assigned, to null string.
168 &q(NAME), &q(N)
169    expands to the same thing as &(NAME) or &(N), but with quotes
170    inside the value doubled according to the quote depoth of the
171    surrounding context.
172 &r(NAME), &r(n)
173    expands to the same thing as &(NAME) or &(N), but requoted and
174    with internal quotes doubled.
175 
176 
177 &[ACTIVE STRING], &||[ACTIVE STRING]
178    expands to the return value of an active string by calling the
179    command processor. This construct ends with the matching right
180    bracket. The &||[...] construct is used in &set statements to treat
181    the expansion as a single argument to &set. It is important to note
182    that &[...] active strings are expanded by exec_com, whereas [...]
183    strings are expanded at command line execution time. Therefore,
184    ||[...] and not &||[...] must be used in a command line to treat
185    the expansion as a single command argument.
186 
187 
188 List of literals:
189    Also see "Notes on white space".
190 &"..."
191    encloses an arbitrary character string to be taken literally.
192    Quotes inside the string must be doubled, and the closing undoubled
193    quote ends the literal string.
194 &&
195    expands to a single & character, not further expanded.
196 &AMP, &AMP(N)
197    expands to a single ampersand character (ASCII 046), in which case
198    it is identical to &&, or to N ampersands where N is a positive
199    integer.
200 &SP, &SP(N)
201    expands to a single space character (ASCII 040) or to N spaces.
202 
203 
204 &BS, &BS(N)
205    expands to a single backspace character (ASCII 010) or to N
206    backspaces.
207 &HT, &HT(N)
208    expands to a single horizontal tab character (ASCII 011) or to N
209    horizontal tabs.
210 &VT, &VT(N)
211    expands to a single vertical tab character (ASCII 013) or to N
212    vertical tabs.
213 &FF, &FF(N), &NP, &NP(N)
214    expands to a single form-feed character (ASCII 014) or to N
215    form-feeds.
216 
217 
218 &NL, &NL(N), &LF, &LF(N)
219    expands to a single newline character (ASCII 012) or to N newlines.
220 &CR, &CR(N)
221    expands to a single carriage return character (ASCII 015) or to N
222    carriage returns.
223 &QT, &QT(N)
224    expands to a single double-quote character (") or to N of them.
225 &!
226    expands to a Multics 15-character unique name, for example
227    "!BBBhjBnWQpGbbc". Multiple occurrences of &! within the same
228    exec_com expand to the same string.
229 
230 
231 List of predicates:
232 &is_defined(NAME)
233    expands to "true" if the variable named NAME has been assigned a
234    value by an &set statement in the current exec_com, "false"
235    otherwise (See "Notes on variables"). This construct expands to
236    "true" if &(NAME) can be expanded, "false" if &(NAME) is an error.
237 &is_defined(N)
238    where N is a positive integer, expands to "true" if an Nth ec_arg
239    was specified to exec_com or an Nth default was defined via the
240    &default statement (see "List of assignment statements"), "false"
241    otherwise.
242 &is_absin
243    expands to "true" if the exec_com is being executed by the
244    absentee facility, "false" if it is being executed by the exec_com
245    command or active function. For example, the segment foo.absin
246    submitted as an absentee job expands &is_absin to "true" but an
247    exec_com that it invokes via "ec ..." expands &is_absin to "false".
248 
249 
250 &is_active_function, &is_af
251    expands to "true" if the exec_com is being executed by the exec_com
252    active function, "false" otherwise.
253 &is_attached
254    expands to "true" if input is currently attached via an &attach
255    statement, "false" otherwise. See "Notes on input attachment".
256    Input is always attached when running as an absentee.
257 &is_input_line
258    expands to "true" if the line in which it appears is being read as
259    an input line by some command, "false" otherwise.
260 &was_attached
261    inside an &on unit (See "List of condition handling statements"),
262    expands to "true" if the parent exec_com was attached via &attach
263    at the time the condition occurred, "false" otherwise. Outside an
264    &on unit, always expands to "false".
265 
266 
267 List of control statements:
268 &attach {&trim on/off}
269    causes any commands subsequently invoked in command lines to read
270    their input from the exec_com rather than from the terminal.
271    See "Notes on input attachment". Specifying "&trim off" causes the
272    input lines to be read intact, without stripping off the leading and
273    trailing white space as is done with most exec_com lines.
274    The default is "&trim on".
275 &detach
276    causes any commands subsequently invoked in command lines to read
277    their input from the terminal. This is the default. See "Notes on
278    input attachment".
279 
280 
281 &if EXPRESSION
282    expands EXPRESSION to get a true or false value. EXPRESSION can
283    contain any exec_com-expandable constructs, such as &[...]
284    (See "List of value expressions"). If the expanded value of
285    EXPRESSION is "true", the following &then statement (if any) is
286    executed next. If the value is "false", the following &else
287    statement (if any) is executed next. If the value is neither "true"
288    nor "false", an error occurs.
289 &then LINE
290 &then &do LINES &end
291 &else LINE
292 &else &do LINES &end
293    where LINE is any exec_com line, including another &if statement.
294    LINE is executed or not depending on the value of the preceding
295    &if clause. The &then and &else statements, unlike other exec_com
296    statements, are allowed to appear on the same line with one
297    another and with &if.  The &do keyword must appear on the same line
298    as &then or &else.  The contents of a &do-&end block reference
299    the same variables as the containing exec_com. No &goto's are
300    allowed into a &do-&end block from outside it.
301 
302 
303 &goto LABEL
304    causes the next statement to be executed to be the statement
305    following the first occurrence of "&label LABEL" in the
306    exec_com.
307 &label LABEL
308    specifies a target for "&goto LABEL" and is otherwise ignored.
309    The string LABEL can contain any characters.
310 
311 
312 &quit
313    terminates execution of the exec_com. If the program was invoked
314    by the exec_com active function, the active function return value
315    is null string.
316 &return LINE
317    terminates execution of the exec_com. If the program was invoked
318    by the exec_com active function, the active function value is the
319    (expanded) value of LINE, the rest of the line. If the program was
320    invoked by the exec_com command, the expanded value of LINE is
321    printed on the terminal.
322 
323 
324 List of assignment statements:
325 &set NAME1 VALUE1 ... NAMEn VALUEn
326    assigns values to the variables NAME1 through NAMEn, which are
327    created if no assignments for them already exist. All NAMEj and
328    VALUEj arguments are fully expanded before any values are set.
329    Therefore, the statement:
330           &set a &(b) b &(a)
331    exchanges the values of the variables a and b. Arguments to &set
332    are delimited by white space. White space and literals inside them
333    must be enclosed in "...", for example:
334           &set answer "&[response Answer?]"
335    Alternatively, the &||[...] construct can be used, causing the
336    entire return value to be taken as a single argument:
337           &set answer &||[response Answer?]
338    There is no restriction on the lengths of NAMEj or VALUEj; NAMEj
339    cannot be all digits. If VALUEj is the unquoted keyword &undefined,
340    any existing value for NAMEj is deleted, and the &is_defined(NAMEj)
341    construct will expand to "false".
342 
343 
344 &default VALUE1 ... VALUEn
345    assigns default values for the exec_com parameters &(1) through
346    &(n).  The default value of &(j) only matters if no jth ec_arg was
347    specified to exec_com. The &(j) parameter reference expands to the
348    value of the jth ec_arg, or if there is none, to the jth default
349    value set by &default, or if there is none, to null string.
350    VALUEj arguments are separated by white space, and each is fully
351    expanded before default values are set. White space and literal 's
352    in them must be enclosed in &"...". If VALUEj is the keyword
353    &undefined, no jth default value is set. This keyword is used as
354    a place-holder to skip the jth position.
355 
356 
357 List of printing statements:
358 &print LINE
359    prints the expanded remainder of the line, followed by a newline
360    character. If &print appears on a line by itself, a single newline
361    character is printed.
362 &print_nnl LINE
363    prints the expanded remainder of the line, without appending a
364    newline character.
365 
366 
367 List of condition handling statements:
368 &on CONDITION_LIST &begin LINES &end
369    establishes a condition handler (&on unit) to be invoked whenever
370    any of the conditions named in CONDITION_LIST is signalled.
371    Condition names are separated by white space. LINES is any sequence
372    of exec_com lines, optionally including &goto statements to transfer
373    to labels either inside the &on unit or outside (ie., in the parent
374    exec_com). When executed, LINES is treated as a separate exec_com
375    in the sense that changes to its &attach, &ready_proc and &trace
376    modes (initially off) do not affect the parent exec_com. However,
377    &on units share the parent ec's variables and any changes to
378    variables affect the parent exec_com. The &begin and &end keywords
379    are required for delimiting LINES, even if it consists of a single
380    line. No &quit statement is required.
381 &revert CONDITION_LIST
382    reverts any &on units for the conditions named in CONDITION_LIST.
383    Condition names are separated by white space.
384 &signal CONDITION_NAME
385    signals the specified condition.
386 
387 
388   (The following statements are allowed only inside &on units.)
389 &exit {&continue}
390    causes the &on unit to exit immediately. This statement is useful
391    for conditionally exiting part-way through an &on unit.
392    If &continue is specified, the condition continues to be propagated
393    to other handlers down the stack.
394 
395 
396 List of tracing statements:
397 &list_variables {match_names} {&control_args}
398 &lsv {match_names} {&control_args}
399    lists the values of all or selected exec_com variables, where
400    match_names are starnames and/or qedx regular expressions surrounded
401    by /'s. Control args are "&exclude match_name" or "&ex match_name" to
402    prevent certain names from being listed, &variable or &var to list
403    just the variable names, and &value or &val to list just the values.
404 &ready on
405 &ready off
406    turns ready messages on or off. Turning them on causes the system
407    ready procedure to print a ready message when it is called.
408    The default is off. This statement does not affect whether the
409    ready procedure is called. The ready procedure is normally called
410    after the execution of a command line (type "help ready_on").
411    The &ready statement is ignored in the absentee environment.
412 &ready_proc on
413 &ready_proc off
414    determines whether or not the system ready procedure is called
415    after each command line is executed. The default is on for the
416    exec_com command, off for the active function. This statement is
417    ignored in the absentee environment.
418 
419 
420 &trace {TYPES} STATE {&prefix PREFIX} {&osw SWITCHNAME}
421    sets tracing for one or more kinds of lines specified by TYPES.
422    TYPES can be any combination of the following:
423      &command       command lines.
424      &comment       comments, including those sharing other lines.
425      &control       control lines, for example &print....
426      &input         lines being read as input to some command.
427    The default if TYPE is omitted is all four types.
428 
429    STATE can be one of the following--
430      off, false     disables tracing entirely.
431      on, true       enables tracing, in whichever of the following
432                     modes was last specified. The default mode is
433                     "&expanded" for command and input lines, "&both"
434                     for control lines.
435      (continued)
436 
437 
438      &unexpanded    prints lines as they appear in the exec_com
439                     segment. Implies "on".
440      &expanded      prints lines after all expansion has been done.
441                     Implies "on".
442      &all           prints at each stage of expansion. Implies "on".
443      &both          prints each line as it appears in the exec_com,
444                     and again after all expansion. Implies "on".
445 
446    Defaults for ec's invoked by the exec_com command/active function
447    are "&expanded" for command and input lines, "&unexpanded" for
448    control lines, and "off" for comments.
449    Defaults in the absentee environment are "&expanded" for command and
450    control lines, "off" for control lines and comments.
451 
452 
453    PREFIX specifies a string to be printed at the start of each line.
454    Default prefixes are all null string.
455 
456    SWITCHNAME specifies an I/O switch on which to write the trace.
457    The default for all types of lines in ec's invoked by the exec_com
458    command or active function is user_output. The default in the
459    absentee environment is user_io.
460 
461 
462 Notes on absentee environment:
463 An exec_com/absin runs in the absentee environment only when it has
464 been invoked directly by the absentee facility, ie. is running an
465 absentee process. Exec_com's called within an absentee process are said
466 to run in the normal exec_com environment.
467 
468 
469 Input lines in an absentee process come from the absin segment running
470 the process. These, along with output lines, are directed to an
471 absout file. Since both input and output lines are written to the same
472 switch, the default switch is chosen to be user_io for the absentee
473 environment rather than user_output as for exec_com's. This default
474 applies to all tracing, and ensures that even if user_output is
475 redirected somewhere, the input lines driving the process still appear
476 in the absout.
477 
478 
479 The &attach and &detach statements have no effect in the absentee
480 environment, since input to the absentee process always comes from the
481 absin file. The &is_attached predicate always returns true.
482 
483 The &ready and &ready_proc statements also have no effect in the
484 absentee environment. Instead, the ready_on and ready_off commands
485 should be used.
486 
487 
488 Notes on version:
489 The current version of exec_com is known as Version 2. In many ways
490 similar to the old Version 1, it adds automatic variables, parameter
491 defaults, literal character escapes, indentation, comments on lines,
492 line continuation, expansion of active strings in control lines, and
493 tracing of comments and control lines.
494 
495 In addition, there are two incompatible changes between the versions.
496 Whereas V1 leaves unrecognized &strings alone, V2 rejects them as
497 syntax errors. This change makes V2 an extensible language.
498 Secondly, V2 parses lines into control keywords and tokens (separated
499 by whitespace) before expansion, so that expansion can only change the
500 values of tokens but not the syntax of a line.
501 
502 
503 A Version 2 exec_com has "&version 2" as its first line. If this first
504 line is not present, the exec_com is interpreted as Version 1.
505 Version 1 exec_com's can optionally begin with "&version 1"; at some
506 future time, Version 2 will be the default and "&version 1" will be
507 required.
508 
509 A conversion command is available to translate Version 1 exec_com's to
510 Version 2. Type "help cvec".
511 
512 
513 Notes on white space:
514 White space (SPACE, HORIZONTAL TAB, VERTICAL TAB, and FORM-FEED)
515 is ignored at the beginning and end of each line, with the exception
516 of input lines specifically read via "&attach &trim off". As a result,
517 exec_com lines can be indented freely. Intentional white space at the
518 beginning or end of a line (for example, an editor input line) must be
519 specified by literal escapes such as &SP. See "List of literals".
520 
521 
522 Notes on comments:
523 Comments are specified by the character sequence &- anywhere in a line.
524 Where this sequence appears (outside of &"..."), the remainder of the
525 line is a comment and can contain any characters. White space preceding
526 the comment, if any, is ignored. Therefore, comments can be aligned
527 at a particular column without affecting the executable text.
528 White space before a comment can be specified by the literal escapes
529 described in "List of literals".
530 
531 
532 Notes on continuation:
533 Long command lines and other portions of text that must not be broken
534 can be continued on successive lines by means of the character sequence
535 &+ at the beginning of each continuation line. White space preceding
536 the &+ is ignored and whitespace following the &+ is part of the
537 executable line.
538 
539 Continuation is not affected by intervening comments, whether at the
540 end of executable text lines or on lines by themselves. This feature
541 can be used to comment parts of statements.
542 
543 
544 Notes on quoting:
545 The exec_com interpreter strips one layer of exec_com quotes (&"...")
546 from the text. It does not perform command processor-type stripping of
547 regular quotes ("...").
548 
549 
550 To defeat one or more levels of command processor quote-stripping, the
551 values of variable and parameter expansions can be quote-doubled or
552 requoted using the "q" and "r" prefixes. Quote-doubling doubles
553 existing quote characters in a string according to the depth of quotes
554 inside which the string is currently nested, so that one level of
555 quote-stripping by the command processor will result in the internal
556 quotes looking the same as they do inside the original string.
557 Requoting goes a step further by first quote-doubling, then surrounding
558 string with an additional layer of quotes, thus causing the entire
559 string to remain a single argument after one level of quote stripping
560 by the command processor. In the examples below, "Level" refers to the
561 number of levels deep in quotes that the parameter reference appears in
562 the exec_com text. Assume that the value of the first ec_arg to
563 exec_com is the string a"b containing a single quote character:
564 
565 
566           &1        &q1            &r1
567 Level 0   a"b       a"b            "a""b"
568 Level 1   "a"b"     "a""b"         """a""""b"""
569 Level 2   """a"b""" """a""""a"""   """""""a""""""""b"""""""
570 
571 The exact number of quote characters is unimportant; the important
572 thing is that &q protects internal quotes from one level of quote
573 stripping by the command processor, and &r ensures that the
574 value remains a single argument to the comand processor. These prefixes
575 are very useful since, if the value of the first ec_arg (for example)
576 contains a space, the value of &1 substituted into a command line will
577 be parsed into more than one command line argument.
578 
579 
580 If a value is null, the &q prefix does not affect it, and the &r prefix
581 results in a pair of quotes, doubled according to the quote depth of
582 the context.
583 
584 The "q" and "r" prefixes can be used in the following constructs--
585           &q1, &q(1)          &r1, &r(1)
586           &qf1, &qf(1)        &rf1, &rf(1)
587           &q&n, &qf&n         &r&n, &rf&n
588           &q(VAR NAME)        &r(VAR NAME)
589 
590 
591 Notes on input attachment:
592 By default, commands invoked by command lines within an exec_com read
593 their input from the terminal. By preceding a command line with an
594 &attach statement, the command can be caused to read input lines from
595 the text of the exec_com instead. Note that "&attach" must precede the
596 line on which the input-reading command is invoked.  The &detach
597 statement causes any later input-reading command to get its
598 input from the terminal.
599 
600 While &attach is in effect, the &is_attached predicate expands to
601 "true"; after &detach, it expands to "false".
602