1 :Info: do: 07/31/86 do
2
3 Syntax as a command: do -control_args control_string args
4
5
6 Syntax as an active function: do control_string args
7
8
9 Function: substitutes arguments into a control string. The expanded
10 control string is then passed to the command processor or the subsystem
11 request processor for execution.
12
13 As an active function or active request, returns the expanded control
14 string without executing it.
15
16
17 Arguments:
18 control_string
19 is a character string which may contain substitution constructs.
20 See "List of substitutions" below.
21 args
22 are zero or more character string arguments. Any argument supplied
23 but not referenced by an argument substitution designator is
24 ignored.
25
26
27 Control arguments: Control arguments given without a control string
28 affect the execution of subsequent do invocations in the process.
29 When given with a control string and optional arguments, the control
30 arguments must precede the control string; they affect only that
31 invocation of do. See "Notes on modes" below for further details.
32 -abort_line, -abl
33 Default applies only to subsystem request invocations of do. If
34 the request line is aborted during execution, the line containing
35 the "do" request is also aborted.
36 -brief, -bf
37 Default does not print the expanded control string.
38
39
40 -go
41 Default passes the expanded control string to the command
42 processor or subsystem request processor.
43 -inhibit_error, -ihe, -absentee
44 establishes a handler for the any_other condition during the
45 execution of the expanded control string.
46 -long, -lg
47 prints the expanded control string on error_output before executing
48 or returning it.
49 -no_inhibit_error, -nihe, -interactive
50 Default does not catch any signals.
51 -nogo
52 does not pass the expanded control string to the request processor.
53
54
55 -no_abort_line, -nabl
56 applies only to subsystem request invocations of do. If the request
57 line invoked by do is aborted during execution, continue execution
58 with the next request following the "do" request on the invoking
59 line.
60
61
62 List of substitutions:
63 The following expansion designators appearing in the control string
64 are replaced by their expansion value, as described below. Any use
65 of ampersand & other than those below is diagnosed as an error.
66 &0, &1, ... &9
67 expands to the zeroth through ninth arguments. &0 is the control
68 string, &1 is the first argument following the control string, and
69 so on. If the corresponding argument is not present, the designator
70 expands to a null string.
71 &0, &1, ...
72 expands to any argument, including arguments after the ninth.
73 Parenthesis are required when the argument number is two or more
74 digits. If the corresponding argument is not present, the
75 designator expands to a null string.
76
77
78 &q0, &q1, ... &q9, &q0, &q1, ...
79 expands to the corresponding argument following the control string.
80 Quotes within the argument are doubled, according to the quote depth
81 of the surrounding context within the control string. See "Notes on
82 quote doubling" below.
83 &r0, &r1, ... &r9, &r0, &r1, ...
84 expands to the corresponding argument following the control string,
85 enclosed in an added layer of quotes with internal quotes with the
86 argument doubled accordingly. See "Notes on requoting" below. This
87 designator keeps the argument as a single unit after one layer of
88 quote stripping by the command processor.
89
90
91 &f1, &f2, ... &f9, &f1, &f2, ...
92 expands to the Nth through last arguments following the
93 control string, with arguments separated by one space. If N is
94 greater than &n, expands to a null string.
95 &qf1, &qf2, ... &qf9, &qf1, &qf2, ...
96 expands to the Nth through last arguments following the
97 control string, with quotes doubled within arguments, and arguments
98 separated by one space. If N is greater than &n, expands to a null
99 string.
100 &rf1, &rf2, ... &rf9, &rf1, &rf2, ...
101 expands to the Nth through last arguments following the
102 control string, with each argument individually requoted and
103 arguments separated by one space. If N is greater than &n, expands
104 to a null string.
105
106
107 &n
108 expands to the number of arguments given following the control
109 string.
110 &f&n, &qf&n, &rf&n
111 expands to the last argument following the control string, with
112 quotes doubled &qf&n or with requoting &rf&n. Note that &f0 or
113 &f0 is the same as &f1 to be consistent with &f&n when &n is zero.
114 Similarly, &qf0 and &rf0 are respectively the same as &qf1 and &rf1.
115 &control_string
116 expands to the control string without expansions, with quotes
117 doubled. It is equivalent to &q0.
118
119
120 &!
121 expands to a unique-name. Each use of &! is replaced by a
122 15-character identifier. Every use within a single invocation will
123 be replaced by the same string, but the string will be different for
124 every invocation of do.
125 &&
126 expands to a single ampersand, to allow ampersands to be literally
127 inserted into the expanded control string.
128
129
130 Notes: The functions of this command are also available by using the
131 execute_string exs and substitute_arguments sbag commands. Those
132 commands are newer interfaces which provide additional capabilities.
133 The execute_string command is like the do command, but when used as an
134 active function, execute_string performs active function evaluation on
135 the expanded control string. The substitute_arguments active function
136 is like the do active function, but when used as a command
137 substitute_arguments prints the expanded control string without
138 evaluating it. It is recommended that you use the newer commands.
139
140 When the control string is executed, abbreviations will be
141 expanded if the abbrev processor is enabled. Since the control string
142 is usually enclosed in quotes, abbreviations in the control string will
143 not be expanded until after the control string is expanded. For more
144 information on abbreviations, see abbrev.info.
145
146
147 Notes on modes: This command has four modes -- the long/brief mode,
148 the nogo/go mode, the inhibit_error mode, and the abort_line
149 mode. These modes are kept in internal static storage and are thus
150 remembered from one invocation of do to the next within a single
151 process. The modes are set for the life of the process by invoking the
152 do command with control arguments but without a control string. The
153 modes can be set for a single invocation of do by giving the mode
154 control arguments preceding a control string and its arguments.
155
156 The abort_line mode applies only to subsystem request invocations of
157 do. The mode may be set at command level, but may not be set for a
158 single command invocation of do.
159
160
161 Use the inhibit_error mode mainly in an absentee environment, in which
162 any condition that normally enters a new command level terminates the
163 process. In this mode any signal caught by do only terminates
164 execution of the expanded control string, not the process. However, a
165 number of conditions are not handled by do, but are passed on for their
166 standard Multics treatment; they are quit, program_interrupt,
167 command_error, command_query_error, command_question, and
168 record_quota_overflow see the Programmer's Reference Manual.
169
170 The abort_line, inhibit_error and go/nogo modes have no effect on
171 active function and active request invocations of do. The active forms
172 of do only expand the control string and do not execute it.
173
174 The modes of the do command are separate from the modes of the
175 execute_string and substitute_arguments commands, although they provide
176 similar functions.
177
178
179 Notes on quote doubling: Each parameter designator to be expanded is
180 found nested a certain level deep in quotes. If it is found not to be
181 within quotes, then its quote level is zero; if found between a single
182 pair of quotes, then its quote level is one; and so on. If an "&q"
183 construct is found nested to quote-level L, then, as the argument is
184 substituted into the expanded control string each quote character found
185 in the argument is replaced by 2**L quote characters during insertion.
186 This permits the quote character to survive the quote-stripping action
187 to which the command processor subsequently subjects the expanded
188 control string. If the "&q" construct is not between quotes or if the
189 corresponding argument contains no quotes, then quote doubling has no
190 effect.
191
192
193 Notes on requoting: If an "&r" construct is found, the substituted
194 argument is placed between an additional level of quotes before having
195 its quotes doubled. For example, if &r1 is found nested to quote level
196 L, 2**L quotes are inserted into the expanded control string, then the
197 first argument is substituted with each of its quotes replaced by
198 2**L+1 quotes, and finally 2**L more quotes are placed following it.
199 If the selected argument is not given, nothing is placed in the
200 expanded control string; so you can distinguish between unsupplied
201 arguments and arguments that are supplied but are null. If the
202 argument is present, the expansion of an "&r" construct is identical to
203 the expansion of an "&q" construct surrounded by an extra level of
204 quotes.
205
206
207 :Info: execute_string: exs: 07/31/86 execute_string, exs
208
209 Syntax as a command: exs -control_args control_string args
210
211
212 Syntax as an active function:
213 exs -control_args control_string args
214
215
216 Function: substitutes arguments into a control string. The expanded
217 control string is then passed to the command processor or the subsystem
218 request processor for execution. As an active function or active
219 request, evaluates the expanded control string as an active function.
220
221
222 Arguments:
223 control_string
224 is a character string which may contain substitution constructs.
225 See "List of substitutions" below.
226 args
227 are zero or more character string arguments. Any argument supplied
228 but not referenced by an argument substitution designator is
229 ignored.
230
231
232 Control arguments as a command: Control arguments given without a
233 control string affect the execution of subsequent execute_string
234 invocations in the process. When given with a control string and
235 optional arguments, the control arguments must precede the control
236 string; they affect only that invocation of execute_string. See
237 "Notes on modes" below for further details.
238 -abort_line, -abl
239 Default Applies only to subsystem request invocations of
240 execute_string. If the request line is aborted during execution, the
241 line containing the "exs" request is also aborted.
242 -brief, -bf
243 Default Does not print the expanded control string.
244 -go
245 Default Passes the expanded control string to the command
246 processor or subsystem request processor.
247
248
249 -inhibit_error, -ihe
250 Establishes a handler for the any_other condition during the
251 execution of the expanded control string.
252 -long, -lg
253 Prints the expanded control string on error_output before executing
254 it.
255 -no_inhibit_error, -nihe
256 Default Does not catch any signals.
257 -no_abort_line, -nabl
258 Applies only to subsystem request invocations of execute_string. If
259 the request line is aborted during execution, continue execution
260 with the next request following the "exs" request on the same line.
261 -nogo
262 Does not pass the expanded control string to the request processor.
263
264
265 Control arguments as an active function:
266 -brief, -bf
267 Default Does not print the expanded active string.
268 -error_value CONTROL_STRING, -erv CONTROL_STRING
269 CONTROL_STRING is a character string which may contain substitution
270 constructs. If an error occurs, the expanded control string is
271 returned as the result of the active function evaluation. In a
272 subsystem active request, an error is anything which aborts the
273 line. In an active function, an error is anything which raises the
274 active_function_error condition. In inhibit_error mode, an error is
275 any condition which -inhibit_error would handle as a command. See
276 "Notes on modes" below.
277
278
279 -inhibit_error, -ihe
280 Establishes a handler for the any_other condition during the
281 execution of the expanded control string. Valid only if
282 -error_value is also given.
283 -long, -lg
284 Prints the expanded control string on error_output before it is
285 evaluated. Also prints the expanded error value before it is
286 returned.
287 -no_inhibit_error, -nihe
288 Default Does not catch any signals.
289
290
291 -no_rescan, -nrsc
292 Default Does not permit the command processor to rescan the result
293 of the active function for whitespace, semicolons, parentheses or
294 brackets. This is equivalent to ||... evaluation, but the result
295 is not protected from reevaluation after execute_string returns the
296 result unless ||... also encloses the execute_string invocation.
297 -rescan, -rsc
298 Permits the command processor to rescan the result of the active
299 function evaluation.
300
301
302 -rescan_tokens, -rsct
303 Permits the command processor to only rescan the active function
304 result for whitespace and quotes. This is similar to |...
305 evaluation, in that it strips a level of quotes, but it concatenates
306 the tokens back together without requoting, so that information may
307 be lost. Use -no_rescan and place the |... around the
308 execute_string invocation to retain this information.
309
310
311 List of substitutions:
312 The following expansion designators appearing in the control string
313 are replaced by their expansion value, as described below. Any use
314 of ampersand & other than those below is diagnosed as an error.
315 &0, &1, ... &9
316 expands to the zeroth through ninth arguments. &0 is the control
317 string, &1 is the first argument following the control string, and
318 so on. If the corresponding argument is not present, the designator
319 expands to a null string.
320 &0, &1, ...
321 expands to any argument, including arguments after the ninth.
322 Parenthesis are required when the argument number is two or more
323 digits. If the corresponding argument is not present, the
324 designator expands to a null string.
325
326
327 &q0, &q1, ... &q9, &q0, &q1, ...
328 expands to the corresponding argument following the control string.
329 Quotes within the argument are doubled, according to the quote depth
330 of the surrounding context within the control string. See "Notes on
331 quote doubling" below.
332 &r0, &r1, ... &r9, &r0, &r1, ...
333 expands to the corresponding argument following the control string,
334 enclosed in an added layer of quotes with internal quotes with the
335 argument doubled accordingly. See "Notes on requoting" below. This
336 designator keeps the argument as a single unit after one layer of
337 quote stripping by the command processor.
338
339
340 &f1, &f2, ... &f9, &f1, &f2, ...
341 expands to the Nth through last arguments following the
342 control string, with arguments separated by one space. If N is
343 greater than &n, expands to a null string.
344 &qf1, &qf2, ... &qf9, &qf1, &qf2, ...
345 expands to the Nth through last arguments following the
346 control string, with quotes doubled within arguments, and arguments
347 separated by one space. If N is greater than &n, expands to a null
348 string.
349 &rf1, &rf2, ... &rf9, &rf1, &rf2, ...
350 expands to the Nth through last arguments following the
351 control string, with each argument individually requoted and
352 arguments separated by one space. If N is greater than &n, expands
353 to a null string.
354
355
356 &n
357 expands to the number of arguments given following the control
358 string.
359 &f&n, &qf&n, &rf&n
360 expands to the last argument following the control string, with
361 quotes doubled &qf&n or with requoting &rf&n. Note that &f0 or
362 &f0 is the same as &f1 to be consistent with &f&n when &n is zero.
363 Similarly, &qf0 and &rf0 are respectively the same as &qf1 and &rf1.
364 &control_string
365 expands to the control string without expansions, with quotes
366 doubled. It is equivalent to &q0.
367
368
369 &!
370 expands to a unique-name. Each use of &! is replaced by a
371 15-character identifier. Every use within a single invocation will
372 be replaced by the same string, but the string will be different for
373 every invocation of execute_string.
374 &&
375 expands to a single ampersand, to allow ampersands to be literally
376 inserted into the expanded control string.
377
378
379 Notes: The execute_string command is similar to the do command. The do
380 command is an older interface that acts like execute_string as a
381 command and like substitute_arguments as an active function.
382
383 When the control string is executed, abbreviations will be expanded if
384 the abbrev processor is enabled. Since the control string is usually
385 enclosed in quotes, abbreviations in the control string will not be
386 expanded until after the control string is expanded. For more
387 information on abbreviations, see abbrev.info.
388
389
390 Notes on modes: This command has four modes -- the long/brief mode, the
391 nogo/go mode, the inhibit_error mode, and the abort_line mode. These
392 modes are kept in internal static storage and are thus remembered from
393 one invocation of execute_string to the next within a single process.
394 The modes are set for the life of the process by invoking the
395 execute_string command with control arguments but without a control
396 string. The modes can be set for a single invocation of execute_string
397 by giving the mode control arguments preceding a control string and its
398 arguments.
399
400 The abort_line mode applies only to subsystem request invocations of
401 execute_string. The mode may be set at command level, but may not be
402 set for a single command invocation of execute_string.
403
404
405 Use the inhibit_error mode mainly in an absentee environment, in which
406 any condition that normally enters a new command level terminates the
407 process. In this mode any signal caught by execute_string only
408 terminates execution of the expanded control string, not the process.
409 However, a number of conditions are not handled by execute_string, but
410 are passed on for their standard Multics treatment; they are quit,
411 program_interrupt, command_error, command_query_error,
412 command_question, and record_quota_overflow see the Programmer's
413 Reference Manual.
414
415
416 The abort_line and go/nogo modes have no effect on active function and
417 active request invocations of execute_string. The active function is
418 always evaluated, and execution of the containing command line can't
419 continue if there is no active function result. The inhibit_error mode
420 is ignored for active function evaluation if no -error_value control
421 argument is given.
422
423 The modes of the execute_string command are separate from the modes of
424 the do and substitute_arguments commands, although they provide similar
425 functions.
426
427
428 Notes on quote doubling: Each parameter designator to be expanded is
429 found nested a certain level deep in quotes. If it is found not to be
430 within quotes, then its quote level is zero; if found between a single
431 pair of quotes, then its quote level is one; and so on. If an "&q"
432 construct is found nested to quote-level L, then, as the argument is
433 substituted into the expanded control string each quote character found
434 in the argument is replaced by 2**L quote characters during insertion.
435 This permits the quote character to survive the quote-stripping action
436 to which the command processor subsequently subjects the expanded
437 control string. If the "&q" construct is not between quotes or if the
438 corresponding argument contains no quotes, then quote doubling has no
439 effect.
440
441
442 Notes on requoting: If an "&r" construct is found, the substituted
443 argument is placed between an additional level of quotes before having
444 its quotes doubled. For example, if &r1 is found nested to quote level
445 L, 2**L quotes are inserted into the expanded control string, then the
446 first argument is substituted with each of its quotes replaced by
447 2**L+1 quotes, and finally 2**L more quotes are placed following it.
448 If the selected argument is not given, nothing is placed in the
449 expanded control string; so you can distinguish between unsupplied
450 arguments and arguments that are supplied but are null. If the
451 argument is present, the expansion of an "&r" construct is identical to
452 the expansion of an "&q" construct surrounded by an extra level of
453 quotes.
454
455
456 :Info: substitute_arguments: substitute_args: sbag:
457 07/31/86 substitute_arguments, substitute_args, sbag
458
459 Syntax as a command: sbag -control_args control_string args
460
461
462 Syntax as an active function: sbag control_string args
463
464
465 Function: substitutes arguments into a control string and prints the
466 result on user_output. As an active function, the result is returned.
467
468
469 Arguments:
470 control_string
471 is a character string which may contain substitution constructs.
472 See "List of substitutions" below.
473 args
474 are zero or more character string arguments. Any argument supplied
475 but not referenced by an argument substitution designator is
476 ignored.
477
478
479 Control arguments as a command: Control arguments given without a
480 control string affect the execution of subsequent
481 substitute_arguments invocations in the process. When given with a
482 control string and optional arguments, the control arguments must
483 precede the control string; they affect only that invocation of
484 substitute_arguments. See "Notes on modes" below for further
485 details.
486 -brief, -bf
487 Default Does not print the expanded control string.
488 -long, -lg
489 Prints the expanded control string on error_output before it is
490 printed or returned.
491
492
493 List of substitutions:
494 The following expansion designators appearing in the control string
495 are replaced by their expansion value, as described below. Any use
496 of ampersand & other than those below is diagnosed as an error.
497 &0, &1, ... &9
498 expands to the zeroth through ninth arguments. &0 is the control
499 string, &1 is the first argument following the control string, and
500 so on. If the corresponding argument is not present, the designator
501 expands to a null string.
502 &0, &1, ...
503 expands to any argument, including arguments after the ninth.
504 Parenthesis are required when the argument number is two or more
505 digits. If the corresponding argument is not present, the
506 designator expands to a null string.
507
508
509 &q0, &q1, ... &q9, &q0, &q1, ...
510 expands to the corresponding argument following the control string.
511 Quotes within the argument are doubled, according to the quote depth
512 of the surrounding context within the control string. See "Notes on
513 quote doubling" below.
514 &r0, &r1, ... &r9, &r0, &r1, ...
515 expands to the corresponding argument following the control string,
516 enclosed in an added layer of quotes with internal quotes with the
517 argument doubled accordingly. See "Notes on requoting" below. This
518 designator keeps the argument as a single unit after one layer of
519 quote stripping by the command processor.
520
521
522 &f1, &f2, ... &f9, &f1, &f2, ...
523 expands to the Nth through last arguments following the
524 control string, with arguments separated by one space. If N is
525 greater than &n, expands to a null string.
526 &qf1, &qf2, ... &qf9, &qf1, &qf2, ...
527 expands to the Nth through last arguments following the
528 control string, with quotes doubled within arguments, and arguments
529 separated by one space. If N is greater than &n, expands to a null
530 string.
531 &rf1, &rf2, ... &rf9, &rf1, &rf2, ...
532 expands to the Nth through last arguments following the
533 control string, with each argument individually requoted and
534 arguments separated by one space. If N is greater than &n, expands
535 to a null string.
536
537
538 &n
539 expands to the number of arguments given following the control
540 string.
541 &f&n, &qf&n, &rf&n
542 expands to the last argument following the control string, with
543 quotes doubled &qf&n or with requoting &rf&n. Note that &f0 or
544 &f0 is the same as &f1 to be consistent with &f&n when &n is zero.
545 Similarly, &qf0 and &rf0 are respectively the same as &qf1 and &rf1.
546 &control_string
547 expands to the control string without expansions, with quotes
548 doubled. It is equivalent to &q0.
549
550
551 &!
552 expands to a unique-name. Each use of &! is replaced by a
553 15-character identifier. Every use within a single invocation will
554 be replaced by the same string, but the string will be different for
555 every invocation of execute_string.
556 &&
557 expands to a single ampersand, to allow ampersands to be literally
558 inserted into the expanded control string.
559
560
561 Notes: The substitute_arguments active function is similar to the do
562 active function. The do command is an older interface that acts like
563 execute_string as a command and like substitute_arguments as an active
564 function.
565
566
567 Notes on modes: This command has a long/brief mode. This mode is kept
568 in internal static storage and is thus remembered from one invocation
569 of substitute_arguments to the next within a single process. The mode
570 is set for the life of the process by invoking the substitute_arguments
571 command with control arguments but without a control string. The mode
572 can be set for a single command invocation of substitute_arguments by
573 giving the mode control argument preceding a control string and its
574 arguments.
575
576 The modes of the substitute_arguments command are separate from the
577 modes of the do and execute_string commands, although they provide
578 similar functions.
579
580
581 Notes on quote doubling: Each parameter designator to be expanded is
582 found nested a certain level deep in quotes. If it is found not to be
583 within quotes, then its quote level is zero; if found between a single
584 pair of quotes, then its quote level is one; and so on. If an "&q"
585 construct is found nested to quote-level L, then, as the argument is
586 substituted into the expanded control string each quote character found
587 in the argument is replaced by 2**L quote characters during insertion.
588 This permits the quote character to survive the quote-stripping action
589 to which the command processor subsequently subjects the expanded
590 control string. If the "&q" construct is not between quotes or if the
591 corresponding argument contains no quotes, then quote doubling has no
592 effect.
593
594
595 Notes on requoting: If an "&r" construct is found, the substituted
596 argument is placed between an additional level of quotes before having
597 its quotes doubled. For example, if &r1 is found nested to quote level
598 L, 2**L quotes are inserted into the expanded control string, then the
599 first argument is substituted with each of its quotes replaced by
600 2**L+1 quotes, and finally 2**L more quotes are placed following it.
601 If the selected argument is not given, nothing is placed in the
602 expanded control string; so you can distinguish between unsupplied
603 arguments and arguments that are supplied but are null. If the
604 argument is present, the expansion of an "&r" construct is identical to
605 the expansion of an "&q" construct surrounded by an extra level of
606 quotes.