:Info: do: 07/31/86 do Syntax as a command: do {-control_args} {control_string {args}} Syntax as an active function: [do control_string {args}] Function: substitutes arguments into a control string. The expanded control string is then passed to the command processor or the subsystem request processor for execution. As an active function or active request, returns the expanded control string without executing it. Arguments: control_string is a character string which may contain substitution constructs. See "List of substitutions" below. args are zero or more character string arguments. Any argument supplied but not referenced by an argument substitution designator is ignored. Control arguments: Control arguments given without a control string affect the execution of subsequent do invocations in the process. When given with a control string and optional arguments, the control arguments must precede the control string; they affect only that invocation of do. See "Notes on modes" below for further details. -abort_line, -abl (Default) applies only to subsystem request invocations of do. If the request line is aborted during execution, the line containing the "do" request is also aborted. -brief, -bf (Default) does not print the expanded control string. -go (Default) passes the expanded control string to the command processor or subsystem request processor. -inhibit_error, -ihe, -absentee establishes a handler for the any_other condition during the execution of the expanded control string. -long, -lg prints the expanded control string on error_output before executing or returning it. -no_inhibit_error, -nihe, -interactive (Default) does not catch any signals. -nogo does not pass the expanded control string to the request processor. -no_abort_line, -nabl applies only to subsystem request invocations of do. If the request line invoked by do is aborted during execution, continue execution with the next request following the "do" request on the invoking line. List of substitutions: The following expansion designators appearing in the control string are replaced by their expansion value, as described below. Any use of ampersand (&) other than those below is diagnosed as an error. &0, &1, ... &9 expands to the zeroth through ninth arguments. &0 is the control string, &1 is the first argument following the control string, and so on. If the corresponding argument is not present, the designator expands to a null string. &(0), &(1), ... expands to any argument, including arguments after the ninth. Parenthesis are required when the argument number is two or more digits. If the corresponding argument is not present, the designator expands to a null string. &q0, &q1, ... &q9, &q(0), &q(1), ... expands to the corresponding argument following the control string. Quotes within the argument are doubled, according to the quote depth of the surrounding context within the control string. See "Notes on quote doubling" below. &r0, &r1, ... &r9, &r(0), &r(1), ... expands to the corresponding argument following the control string, enclosed in an added layer of quotes with internal quotes with the argument doubled accordingly. See "Notes on requoting" below. This designator keeps the argument as a single unit after one layer of quote stripping by the command processor. &f1, &f2, ... &f9, &f(1), &f(2), ... expands to the Nth through last arguments following the control string, with arguments separated by one space. If N is greater than &n, expands to a null string. &qf1, &qf2, ... &qf9, &qf(1), &qf(2), ... expands to the Nth through last arguments following the control string, with quotes doubled within arguments, and arguments separated by one space. If N is greater than &n, expands to a null string. &rf1, &rf2, ... &rf9, &rf(1), &rf(2), ... expands to the Nth through last arguments following the control string, with each argument individually requoted and arguments separated by one space. If N is greater than &n, expands to a null string. &n expands to the number of arguments given following the control string. &f&n, &qf&n, &rf&n expands to the last argument following the control string, with quotes doubled (&qf&n) or with requoting (&rf&n). Note that &f0 or &f(0) is the same as &f1 to be consistent with &f&n when &n is zero. Similarly, &qf0 and &rf0 are respectively the same as &qf1 and &rf1. &control_string expands to the control string (without expansions), with quotes doubled. It is equivalent to &q0. &! expands to a unique-name. Each use of &! is replaced by a 15-character identifier. Every use within a single invocation will be replaced by the same string, but the string will be different for every invocation of do. && expands to a single ampersand, to allow ampersands to be literally inserted into the expanded control string. Notes: The functions of this command are also available by using the execute_string (exs) and substitute_arguments (sbag) commands. Those commands are newer interfaces which provide additional capabilities. The execute_string command is like the do command, but when used as an active function, execute_string performs active function evaluation on the expanded control string. The substitute_arguments active function is like the do active function, but when used as a command substitute_arguments prints the expanded control string without evaluating it. It is recommended that you use the newer commands. When the control string is executed, abbreviations will be expanded if the abbrev processor is enabled. Since the control string is usually enclosed in quotes, abbreviations in the control string will not be expanded until after the control string is expanded. For more information on abbreviations, see abbrev.info. Notes on modes: This command has four modes -- the long/brief mode, the nogo/go mode, the inhibit_error mode, and the abort_line mode. These modes are kept in internal static storage and are thus remembered from one invocation of do to the next within a single process. The modes are set for the life of the process by invoking the do command with control arguments but without a control string. The modes can be set for a single invocation of do by giving the mode control arguments preceding a control string and its arguments. The abort_line mode applies only to subsystem request invocations of do. The mode may be set at command level, but may not be set for a single command invocation of do. Use the inhibit_error mode mainly in an absentee environment, in which any condition that normally enters a new command level terminates the process. In this mode any signal caught by do only terminates execution of the expanded control string, not the process. However, a number of conditions are not handled by do, but are passed on for their standard Multics treatment; they are quit, program_interrupt, command_error, command_query_error, command_question, and record_quota_overflow (see the Programmer's Reference Manual). The abort_line, inhibit_error and go/nogo modes have no effect on active function and active request invocations of do. The active forms of do only expand the control string and do not execute it. The modes of the do command are separate from the modes of the execute_string and substitute_arguments commands, although they provide similar functions. Notes on quote doubling: Each parameter designator to be expanded is found nested a certain level deep in quotes. If it is found not to be within quotes, then its quote level is zero; if found between a single pair of quotes, then its quote level is one; and so on. If an "&q" construct is found nested to quote-level L, then, as the argument is substituted into the expanded control string each quote character found in the argument is replaced by 2**L quote characters during insertion. This permits the quote character to survive the quote-stripping action to which the command processor subsequently subjects the expanded control string. If the "&q" construct is not between quotes or if the corresponding argument contains no quotes, then quote doubling has no effect. Notes on requoting: If an "&r" construct is found, the substituted argument is placed between an additional level of quotes before having its quotes doubled. For example, if &r1 is found nested to quote level L, 2**L quotes are inserted into the expanded control string, then the first argument is substituted with each of its quotes replaced by 2**(L+1) quotes, and finally 2**L more quotes are placed following it. If the selected argument is not given, nothing is placed in the expanded control string; so you can distinguish between unsupplied arguments and arguments that are supplied but are null. If the argument is present, the expansion of an "&r" construct is identical to the expansion of an "&q" construct surrounded by an extra level of quotes. :Info: execute_string: exs: 07/31/86 execute_string, exs Syntax as a command: exs {-control_args} {control_string {args}} Syntax as an active function: [exs {-control_args} control_string {args}] Function: substitutes arguments into a control string. The expanded control string is then passed to the command processor or the subsystem request processor for execution. As an active function or active request, evaluates the expanded control string as an active function. Arguments: control_string is a character string which may contain substitution constructs. See "List of substitutions" below. args are zero or more character string arguments. Any argument supplied but not referenced by an argument substitution designator is ignored. Control arguments as a command: Control arguments given without a control string affect the execution of subsequent execute_string invocations in the process. When given with a control string and optional arguments, the control arguments must precede the control string; they affect only that invocation of execute_string. See "Notes on modes" below for further details. -abort_line, -abl (Default) Applies only to subsystem request invocations of execute_string. If the request line is aborted during execution, the line containing the "exs" request is also aborted. -brief, -bf (Default) Does not print the expanded control string. -go (Default) Passes the expanded control string to the command processor or subsystem request processor. -inhibit_error, -ihe Establishes a handler for the any_other condition during the execution of the expanded control string. -long, -lg Prints the expanded control string on error_output before executing it. -no_inhibit_error, -nihe (Default) Does not catch any signals. -no_abort_line, -nabl Applies only to subsystem request invocations of execute_string. If the request line is aborted during execution, continue execution with the next request following the "exs" request on the same line. -nogo Does not pass the expanded control string to the request processor. Control arguments as an active function: -brief, -bf (Default) Does not print the expanded active string. -error_value CONTROL_STRING, -erv CONTROL_STRING CONTROL_STRING is a character string which may contain substitution constructs. If an error occurs, the expanded control string is returned as the result of the active function evaluation. In a subsystem active request, an error is anything which aborts the line. In an active function, an error is anything which raises the active_function_error condition. In inhibit_error mode, an error is any condition which -inhibit_error would handle as a command. See "Notes on modes" below. -inhibit_error, -ihe Establishes a handler for the any_other condition during the execution of the expanded control string. Valid only if -error_value is also given. -long, -lg Prints the expanded control string on error_output before it is evaluated. Also prints the expanded error value before it is returned. -no_inhibit_error, -nihe (Default) Does not catch any signals. -no_rescan, -nrsc (Default) Does not permit the command processor to rescan the result of the active function for whitespace, semicolons, parentheses or brackets. This is equivalent to ||[...] evaluation, but the result is not protected from reevaluation after execute_string returns the result unless ||[...] also encloses the execute_string invocation. -rescan, -rsc Permits the command processor to rescan the result of the active function evaluation. -rescan_tokens, -rsct Permits the command processor to only rescan the active function result for whitespace and quotes. This is similar to |[...] evaluation, in that it strips a level of quotes, but it concatenates the tokens back together without requoting, so that information may be lost. Use -no_rescan and place the |[...] around the execute_string invocation to retain this information. List of substitutions: The following expansion designators appearing in the control string are replaced by their expansion value, as described below. Any use of ampersand (&) other than those below is diagnosed as an error. &0, &1, ... &9 expands to the zeroth through ninth arguments. &0 is the control string, &1 is the first argument following the control string, and so on. If the corresponding argument is not present, the designator expands to a null string. &(0), &(1), ... expands to any argument, including arguments after the ninth. Parenthesis are required when the argument number is two or more digits. If the corresponding argument is not present, the designator expands to a null string. &q0, &q1, ... &q9, &q(0), &q(1), ... expands to the corresponding argument following the control string. Quotes within the argument are doubled, according to the quote depth of the surrounding context within the control string. See "Notes on quote doubling" below. &r0, &r1, ... &r9, &r(0), &r(1), ... expands to the corresponding argument following the control string, enclosed in an added layer of quotes with internal quotes with the argument doubled accordingly. See "Notes on requoting" below. This designator keeps the argument as a single unit after one layer of quote stripping by the command processor. &f1, &f2, ... &f9, &f(1), &f(2), ... expands to the Nth through last arguments following the control string, with arguments separated by one space. If N is greater than &n, expands to a null string. &qf1, &qf2, ... &qf9, &qf(1), &qf(2), ... expands to the Nth through last arguments following the control string, with quotes doubled within arguments, and arguments separated by one space. If N is greater than &n, expands to a null string. &rf1, &rf2, ... &rf9, &rf(1), &rf(2), ... expands to the Nth through last arguments following the control string, with each argument individually requoted and arguments separated by one space. If N is greater than &n, expands to a null string. &n expands to the number of arguments given following the control string. &f&n, &qf&n, &rf&n expands to the last argument following the control string, with quotes doubled (&qf&n) or with requoting (&rf&n). Note that &f0 or &f(0) is the same as &f1 to be consistent with &f&n when &n is zero. Similarly, &qf0 and &rf0 are respectively the same as &qf1 and &rf1. &control_string expands to the control string (without expansions), with quotes doubled. It is equivalent to &q0. &! expands to a unique-name. Each use of &! is replaced by a 15-character identifier. Every use within a single invocation will be replaced by the same string, but the string will be different for every invocation of execute_string. && expands to a single ampersand, to allow ampersands to be literally inserted into the expanded control string. Notes: The execute_string command is similar to the do command. The do command is an older interface that acts like execute_string as a command and like substitute_arguments as an active function. When the control string is executed, abbreviations will be expanded if the abbrev processor is enabled. Since the control string is usually enclosed in quotes, abbreviations in the control string will not be expanded until after the control string is expanded. For more information on abbreviations, see abbrev.info. Notes on modes: This command has four modes -- the long/brief mode, the nogo/go mode, the inhibit_error mode, and the abort_line mode. These modes are kept in internal static storage and are thus remembered from one invocation of execute_string to the next within a single process. The modes are set for the life of the process by invoking the execute_string command with control arguments but without a control string. The modes can be set for a single invocation of execute_string by giving the mode control arguments preceding a control string and its arguments. The abort_line mode applies only to subsystem request invocations of execute_string. The mode may be set at command level, but may not be set for a single command invocation of execute_string. Use the inhibit_error mode mainly in an absentee environment, in which any condition that normally enters a new command level terminates the process. In this mode any signal caught by execute_string only terminates execution of the expanded control string, not the process. However, a number of conditions are not handled by execute_string, but are passed on for their standard Multics treatment; they are quit, program_interrupt, command_error, command_query_error, command_question, and record_quota_overflow (see the Programmer's Reference Manual). The abort_line and go/nogo modes have no effect on active function and active request invocations of execute_string. The active function is always evaluated, and execution of the containing command line can't continue if there is no active function result. The inhibit_error mode is ignored for active function evaluation if no -error_value control argument is given. The modes of the execute_string command are separate from the modes of the do and substitute_arguments commands, although they provide similar functions. Notes on quote doubling: Each parameter designator to be expanded is found nested a certain level deep in quotes. If it is found not to be within quotes, then its quote level is zero; if found between a single pair of quotes, then its quote level is one; and so on. If an "&q" construct is found nested to quote-level L, then, as the argument is substituted into the expanded control string each quote character found in the argument is replaced by 2**L quote characters during insertion. This permits the quote character to survive the quote-stripping action to which the command processor subsequently subjects the expanded control string. If the "&q" construct is not between quotes or if the corresponding argument contains no quotes, then quote doubling has no effect. Notes on requoting: If an "&r" construct is found, the substituted argument is placed between an additional level of quotes before having its quotes doubled. For example, if &r1 is found nested to quote level L, 2**L quotes are inserted into the expanded control string, then the first argument is substituted with each of its quotes replaced by 2**(L+1) quotes, and finally 2**L more quotes are placed following it. If the selected argument is not given, nothing is placed in the expanded control string; so you can distinguish between unsupplied arguments and arguments that are supplied but are null. If the argument is present, the expansion of an "&r" construct is identical to the expansion of an "&q" construct surrounded by an extra level of quotes. :Info: substitute_arguments: substitute_args: sbag: 07/31/86 substitute_arguments, substitute_args, sbag Syntax as a command: sbag {-control_args} {control_string {args}} Syntax as an active function: [sbag control_string {args}] Function: substitutes arguments into a control string and prints the result on user_output. As an active function, the result is returned. Arguments: control_string is a character string which may contain substitution constructs. See "List of substitutions" below. args are zero or more character string arguments. Any argument supplied but not referenced by an argument substitution designator is ignored. Control arguments as a command: Control arguments given without a control string affect the execution of subsequent substitute_arguments invocations in the process. When given with a control string and optional arguments, the control arguments must precede the control string; they affect only that invocation of substitute_arguments. See "Notes on modes" below for further details. -brief, -bf (Default) Does not print the expanded control string. -long, -lg Prints the expanded control string on error_output before it is printed or returned. List of substitutions: The following expansion designators appearing in the control string are replaced by their expansion value, as described below. Any use of ampersand (&) other than those below is diagnosed as an error. &0, &1, ... &9 expands to the zeroth through ninth arguments. &0 is the control string, &1 is the first argument following the control string, and so on. If the corresponding argument is not present, the designator expands to a null string. &(0), &(1), ... expands to any argument, including arguments after the ninth. Parenthesis are required when the argument number is two or more digits. If the corresponding argument is not present, the designator expands to a null string. &q0, &q1, ... &q9, &q(0), &q(1), ... expands to the corresponding argument following the control string. Quotes within the argument are doubled, according to the quote depth of the surrounding context within the control string. See "Notes on quote doubling" below. &r0, &r1, ... &r9, &r(0), &r(1), ... expands to the corresponding argument following the control string, enclosed in an added layer of quotes with internal quotes with the argument doubled accordingly. See "Notes on requoting" below. This designator keeps the argument as a single unit after one layer of quote stripping by the command processor. &f1, &f2, ... &f9, &f(1), &f(2), ... expands to the Nth through last arguments following the control string, with arguments separated by one space. If N is greater than &n, expands to a null string. &qf1, &qf2, ... &qf9, &qf(1), &qf(2), ... expands to the Nth through last arguments following the control string, with quotes doubled within arguments, and arguments separated by one space. If N is greater than &n, expands to a null string. &rf1, &rf2, ... &rf9, &rf(1), &rf(2), ... expands to the Nth through last arguments following the control string, with each argument individually requoted and arguments separated by one space. If N is greater than &n, expands to a null string. &n expands to the number of arguments given following the control string. &f&n, &qf&n, &rf&n expands to the last argument following the control string, with quotes doubled (&qf&n) or with requoting (&rf&n). Note that &f0 or &f(0) is the same as &f1 to be consistent with &f&n when &n is zero. Similarly, &qf0 and &rf0 are respectively the same as &qf1 and &rf1. &control_string expands to the control string (without expansions), with quotes doubled. It is equivalent to &q0. &! expands to a unique-name. Each use of &! is replaced by a 15-character identifier. Every use within a single invocation will be replaced by the same string, but the string will be different for every invocation of execute_string. && expands to a single ampersand, to allow ampersands to be literally inserted into the expanded control string. Notes: The substitute_arguments active function is similar to the do active function. The do command is an older interface that acts like execute_string as a command and like substitute_arguments as an active function. Notes on modes: This command has a long/brief mode. This mode is kept in internal static storage and is thus remembered from one invocation of substitute_arguments to the next within a single process. The mode is set for the life of the process by invoking the substitute_arguments command with control arguments but without a control string. The mode can be set for a single command invocation of substitute_arguments by giving the mode control argument preceding a control string and its arguments. The modes of the substitute_arguments command are separate from the modes of the do and execute_string commands, although they provide similar functions. Notes on quote doubling: Each parameter designator to be expanded is found nested a certain level deep in quotes. If it is found not to be within quotes, then its quote level is zero; if found between a single pair of quotes, then its quote level is one; and so on. If an "&q" construct is found nested to quote-level L, then, as the argument is substituted into the expanded control string each quote character found in the argument is replaced by 2**L quote characters during insertion. This permits the quote character to survive the quote-stripping action to which the command processor subsequently subjects the expanded control string. If the "&q" construct is not between quotes or if the corresponding argument contains no quotes, then quote doubling has no effect. Notes on requoting: If an "&r" construct is found, the substituted argument is placed between an additional level of quotes before having its quotes doubled. For example, if &r1 is found nested to quote level L, 2**L quotes are inserted into the expanded control string, then the first argument is substituted with each of its quotes replaced by 2**(L+1) quotes, and finally 2**L more quotes are placed following it. If the selected argument is not given, nothing is placed in the expanded control string; so you can distinguish between unsupplied arguments and arguments that are supplied but are null. If the argument is present, the expansion of an "&r" construct is identical to the expansion of an "&q" construct surrounded by an extra level of quotes. ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved