1
2 02/26/86 command_query_
3
4 The command_query_ subroutine is the standard system procedure invoked
5 to ask the user a question and to obtain an answer. It formats the
6 question and then signals the condition command_question. System
7 conditions are described in the Programmer's Reference Manual. The
8 default handler for this condition simply returns control to the
9 command_query_ subroutine, which writes the question on a specified I/O
10 switch. It then reads from another I/O switch to obtain the answer.
11 Several options have been included in the commmand_query_ subroutine to
12 support the use of a more sophisticated handler for the
13 command_question condition.
14
15 Since this procedure can be called with a varying number of arguments,
16 it is not permissible to include a parameter attribute list in the
17 declaration.
18
19
20 Entry points in command_query_:
21 List is generated by the help command
22
23
24 :Entry: command_query_: 02/26/86 command_query_
25
26
27 Function: is the standard system procedure invoked to ask the user a
28 question and to obtain an answer. Formats the question and
29 then signals the condition command_question.
30
31
32 Syntax:
33 declare command_query_ entry options variable;
34 call command_query_ info_ptr answer caller control_string
35 arg1 ... argN;
36
37
38 Arguments:
39 info_ptr
40 is a pointer to the query_info structure described in "Info
41 Structure" below. Input
42 answer
43 is the response char* or char * varying read from the I/O
44 switch user_input. Output Leading and trailing blanks plus the
45 newline character have been removed.
46 caller
47 is the name char* of the calling procedure. Input It can be
48 either varying or nonvarying.
49 control_string
50 is an ioa_ subroutine control string char*. Input This
51 argument is optional. See "Notes" below.
52
53 argi
54 are ioa_ subroutine arguments to be substituted into control_string.
55 Input These arguments are optional. They can only be used if the
56 control_string argument is given first. See "Notes" below.
57
58
59 Info structure;
60 The following is the query_info structure found in the include file
61 query_info.incl.pl1:
62
63 dcl 1 query_info aligned,
64 2 version fixed bin,
65 2 switches aligned,
66 3 yes_or_no_sw bit1 unaligned,
67 3 suppress_name_sw bit1 unaligned,
68 3 cp_escape_control bit2 unaligned,
69 3 suppress_spacing bit1 unaligned,
70 3 literal_sw bit1 unaligned,
71 3 prompt_after explanation
72 bit 1 unaligned,
73 3 padding bit29 unaligned,
74
75
76 2 status_code fixed bin35,
77 2 query_code fixed bin35,
78 2 question_iocbp ptr,
79 2 answer_iocbp ptr,
80 2 repeat_time fixed bin71,
81 2 explanation_ptr ptr,
82 2 explanation_len fixed bin 21;
83
84
85
86 Structure elements:
87 version
88 is the version number of this structure. Input The version
89 number must be set by the caller and identifies the format of the
90 structure. The current version is a static variable named
91 query_info_version_6 in query_info.incl.pl1.
92 yes_or_no_sw
93 indicates whether an answer of a particular form is expected.
94 Input
95 "0"b accepts any answer.
96 "1"b accepts only a yes or no answer.
97
98
99 suppress_name_sw
100 controls whether the name of the calling procedure appears in the
101 question. Input
102 "0"b includes name and following colon.
103 "1"b omits name and colon.
104 cp_escape_control
105 controls whether the command_processor_ escape mechanism is
106 enabled for this call. Input
107 "00"b obeys the static default.
108 "01"b allows lines to begin with ".." but does not interpret
109 them as
110 command_processor_ escapes.
111 "10"b disallows escape, ignores default.
112 "11"b allows escape, ignores default.
113
114
115 suppress_spacing
116 controls the insertion of a newline before the question and two
117 spaces after it. Input
118 "0"b inserts extra space.
119 "1"b omits extra space.
120 literal_sw
121 is "1"b to suppress any special interpretation of characters for
122 example ".." and suppress stripping of leading whitespace.
123 prompt_after_explanation
124 is "1"b to repeat the original question after printing any
125 explanation indicated by a non-null explanation argument.
126 padding
127 is unused space. Input
128
129
130 status_code
131 is either the standard status code that prompted the question or
132 0. Input
133 query_code
134 is additional arbitrary qualifying information passed by the
135 caller of command_query_. Input It is intended for use by
136 specialized handlers for command_question.
137 question_iocbp
138 is an iocb pointer for the I/O switch over which the caller wants
139 the question to be written. Input A null pointer indicates
140 that the of the user_i/o switch is to be used by default.
141 answer_iocbp
142 is an iocb pointer for the I/O switch from which the caller wants
143 the answer to be read. Input A null pointer indicates that the
144 user_input switch is to be used by default.
145
146
147 repeat_time
148 is the number of seconds to wait for an answer before repeating
149 the question on the switch pointed to by question_iocbp. Input
150 A value less than 30 indicates that the question is not to be
151 repeated.
152 explanation_ptr
153 is a pointer to a string to be printed if the user answers "?".
154 Input
155 explanation_len
156 is the length of the explanation string. Input
157
158
159 Notes: The question prepared by the command_query_ subroutine has the
160 format:
161 caller: message
162 where the message is constructed by the ioa_ subroutine from the
163 control_string and argN arguments. If the control_string and argN
164 arguments are not given, the message portion of the question is
165 omitted.
166
167 If the user answers with a single question mark ?, the
168 explanation_ptr field is examined. If it is non-null and
169 explanation_len is greater than 0, the explanation string pointed to is
170 printed and the user is expected to answer again. Otherwise, the
171 string "Answer: " is printed and the user is expected to answer again.
172
173
174 In an absentee process with the yes_or_no_sw on, an answer other than
175 than yes, no or "?" causes the absentee process to signal
176 command_query_error.
177
178 Case insensitive "yes", "y", "no", and "n" are acceptable responses
179 to a yes or no question.
180
181 If the answer to a question begins with "..", and the cp_escape feature
182 is enabled for the question, the rest of the answer following the ".."
183 is passed to the command processor. Control then returns to
184 command_query_, which prompts with "Answer: " after the command has
185 been executed. The cp_escape feature is normally enabled in the
186 standard Multics environment; a subsystem, however, can elect to turn
187 it off, either globally or for a particular question. The prompt of
188 "Answer: " is used rather than repeating the question because the
189 question may be quite long and take significant time to print. If it
190 is necessary to see the question again, answering "..repeat_query"
191 repeats it.
192
193
194 :Entry: set_cp_escape_enable: 03/05/85 command_query_$set_cp_escape_enable
195
196
197 Function: This entry sets the static default switch that allows or
198 disallows the command processor escape feature. It also returns the
199 previous value for the switch. Since escapes are disabled initially,
200 it is necessary to call this entry to enable the feature. This entry
201 is called by process_overseer_, which sets it so that the escape is
202 permitted in a normal Multics environment.
203
204
205 Syntax:
206 declare command_query_$set_cp_escape_enable entry bit1 aligned
207 bit1 aligned;
208 call command_query_$set_cp_escape_enable new_value old_value;
209
210
211 Arguments:
212 new_value
213 is the new value for the default. Input
214 "0"b feature is disabled by default.
215 "1"b feature is enabled by default.
216
217 old_value
218 is the old value of the default. Output If it has never been set,
219 it is "0"b.
220
221
222 :Entry: yes_no: 02/26/86 command_query_$yes_no
223
224
225 Function: This entry asks the user for a yes or no answer.
226
227
228 Syntax:
229 dcl command_query_$yes_no entry options variable;
230 call command_query_$yes_no yes_sw query_code caller explanation
231 question arg1 ... argN;
232
233
234 Arguments:
235 yes_sw
236 is a bit 1 return value, ON for "yes" or "y" and OFF for "no" or
237 "n", case insensitive. Output Other answers are not accepted
238 from the user.
239 query_code
240 is a standard status code. Input If it is nonzero, the question
241 is preceded by the corresponding error message.
242 caller
243 is the character string name of the calling program. Input
244 explanation
245 is an explanation of the question, printed when the user answers
246 "?". Input The explanation is an ioa_ control string, in which
247 parameters are replaced by the values of the argN arguments. For a
248 description of control strings, see the ioa_ subroutine.
249
250
251 question
252 is the question, also in the form of an ioa_ control string.
253 Input Parameters are replaced by the same argN arguments as for
254 the explanation.
255 argN
256 are character string arguments to the ioa_ control strings specified
257 by explanation and question. Input
258
259
260 Notes: The same arguments are substituted in both explanation and
261 question control strings. Each control string can use ^s to skip
262 particular arguments.
263