1 03/06/84  exec_com, ec
  2 
  3 Syntax:  ec path {optional_args}
  4 
  5 
  6 Syntax as an active function:  [ec ec_path {optional_args}]
  7 
  8 
  9 Function:  executes a sequence of command lines contained in a segment.
 10 
 11 
 12 Arguments:
 13 path
 14    is the pathname of the segment containing commands to be executed
 15    and control statements to be interpreted; the ec suffix is optional.
 16 optional_args
 17    are character strings to be substituted for &i in the exec_com
 18    segment.
 19 
 20 
 21 List of character substitutions:
 22 &i (i is a positive integer)
 23    is replaced by the corresponding optional argument.
 24 &0
 25    is replaced by the expanded, suffixed path.
 26 &qi, &ri
 27    are replaced after quoting or requoting the ith argument as does the
 28    do command (see the do command info file).
 29 &fi
 30    is replaced by the ith through last arguments separated by spaces.
 31 &n
 32    is replaced by the number of optional arguments of the exec_com.
 33 
 34 
 35 &f&n
 36    is replaced by the last argument to exec_com.  &f0 is defined to be
 37    the same as &f1, so that &f&n is replaced by nothing when &n is
 38    zero.
 39 
 40    These can be combined--  &qfi  &rfi  &q&n  &r&n  &qf&n  &rf&n
 41 
 42 &ec_name
 43    is replaced by the entryname portion of path without the ec suffix.
 44 &ec_dir
 45    is replaced by the pathname of the directory containing the
 46    exec_com segment.  This can be used to simulate the referencing_dir
 47    search rule.
 48 
 49 
 50 &is_active_function, &is_af
 51    is replaced by the string "true" if exec_com was invoked as an
 52    active function, "false" otherwise.
 53 &is_absin
 54    is replaced by "true" if the exec_com segment is being executed
 55    as an absentee job, via enter_abs_request; "false" if it is executed
 56    by the exec_com command.
 57 &is_attached
 58    is replaced by "true" if user_input is attached via &attach,
 59    "false" otherwise.
 60 
 61 
 62 List of control statements:
 63 &label NAME
 64    identifies location by NAME.
 65 &goto NAME
 66    transfers control to &label NAME.
 67 &attach
 68    attaches user_input to the exec_com segment.
 69 &detach
 70    detaches user_input (restores its former attachment).
 71 
 72 
 73 &print STRING
 74    prints STRING on user_output as the format_line command would.
 75    Valid constructs (n and m are integers):
 76          ^/ or ^n/ are replaced by 1 or n newline characters.
 77          ^| or ^n| are replaced by 1 or n new page characters.
 78          ^- or ^n- are replaced by 1 or n tab characters.
 79          ^x or ^nx are replaced by 1 or n spaces.
 80          ^^ or ^n^ are replaced by 1 or n ^ (caret) characters.
 81          ^nt or ^n.mt position to column n, skipping at least 1
 82                       or m spaces.
 83          ^n(...^) repeat the delimited string n times.
 84 &quit
 85    returns exec_com to caller (e.g., command level).
 86 
 87 
 88 &return STRING
 89    returns exec_com to caller, but if invoked as an active function,
 90    STRING is the result, and if invoked as a command, STRING is printed
 91    (not by ioa_) with a trailing newline.
 92 &if IF_EXPRESSION
 93    executes &then clause if IF_EXPRESSION evaluates to "true" executes
 94    optional &else clause if IF_EXPRESSION evaluates to "false"
 95    otherwise error.  IF_EXPRESSION can be an active function
 96    invocation, (e.g., &if [exists file &r1] &then &else &quit)
 97    or it can be a character string with parameter substitution.  The
 98    &if statements can be nested to any depth.
 99 
100 
101 &then THEN_CLAUSE
102    can include a command line, input line, null statement, and any
103    control statement except &then and &label.
104 &else ELSE_CLAUSE
105    can include a command line, input line, null statement, and any
106    control statement except &then and &label.  This statement is
107    optional, but, if present, it must immediately follow the preceding
108    &then or &else clause on the same or next line.
109 &version 1
110    if present, it must be the first line of the exec_com segment.  This
111    statement serves to identify the version of the exec_com language
112    that should be used to interpret the exec_com segment.
113 
114 
115 List of tracing statements:
116 &command_line STATE
117    controls the trace printing of lines that exec_com executes as
118    commands.
119 &control_line STATE
120    controls the trace printing of lines that contain exec_com control
121    statements.
122 &comment_line STATE
123    controls the trace printing of exec_com comment lines (lines that
124    begin with an ampersand but not a recognized keyword).
125 &input_line STATE
126    controls the trace printing of lines that exec_com supplies as
127    input to commands in &attach mode.
128 
129 
130 &ready STATE
131    when on, causes the ready procedure to print a message when it is
132    called by the exec_com command.
133 &ready_proc STATE
134    when on, causes the exec_com command to call the ready procedure
135    after executing each line it reads from the exec_com segment.
136 
137    STATE can be "on" or "off"; "true" and "false", respectively, are
138    synonyms.  For tracing control statements, STATE can also be the
139    keyword "stream" followed by an optional I/O stream name.  If the
140    name is ommited, the default (user_output) is assumed.  This has no
141    effect on the on/off state of the tracing mode.
142 
143 
144 Notes on tracing defaults:
145 The default for &control_line, &comment_line, and &ready is "off".
146 The default for &command_line, &input_line, and &ready_proc is "on"
147 when exec_com is invoked as a command, "off" when invoked as an active
148 function.
149 
150 
151 Notes: Keywords are only recognized at the beginnings of lines except
152 for &then, &else, and their clauses.  Lines beginning with
153 unimplemented keywords are treated as comments; however, lines
154 beginning with AMPERSAND SPACE should be used for comments to allow
155 for the implementation of new keywords.  Unimplemented keywords
156 (anything beginning with ampersand) occurring elsewhere are left
157 unexpanded.
158 
159 &0 is not the same as &ec_dir>&ec_name.ec.  &0 is derived from the
160 path argument to the exec_com command; it can contain links.  &ec_dir
161 is the pathname of the directory that contains the exec_com segment,
162 as derived from the storage system when &ec_dir is expanded.  &ec_dir
163 is not necessarily replaced by the same character string each time it
164 is expanded; however, it is always replaced by a correct pathname even
165 if some directory in it is renamed.