1 02/26/90  ask_
  2 
  3 
  4 The ask_ subroutine provides a flexible terminal input facility for
  5 whole lines, strings delimited by blanks, or fixed-point and
  6 floating-point numbers.  Special attention is given to prompting the
  7 terminal user.
  8 
  9 The main entry point returns the next string of characters delimited by
 10 blanks or tabs from the line typed by the user.  If the line buffer is
 11 empty, the ask_ subroutine formats and types out a prompting message
 12 and reads a line from the user_input I/O switch.
 13 
 14 
 15 Entry points in ask_:
 16    (List is generated by the help command)
 17 
 18 
 19 :Entry:  ask_:  02/26/85  ask_
 20 
 21 
 22 Function:
 23 provides a flexible terminal input facility for
 24 whole lines, strings delimited by blanks, or fixed-point and
 25 floating-point numbers.
 26 
 27 
 28 Syntax:
 29 declare ask_ entry options (variable);
 30 call ask_ (ctl, ans, ioa_args);
 31 
 32 
 33 Arguments:
 34 ctl
 35    is an ioa_ control string (char(*)) in the same format as that used
 36    by the ioa_ subroutine.  (Input)
 37 ans
 38    is the return value (char(*)).  (Output)
 39 ioa_args
 40    are any number of arguments to be converted according to ctl.
 41    (Input)
 42 
 43 
 44 :Entry:  ask_c:  02/26/85 ask_$ask_c
 45 
 46 
 47 Function:  This entry point tests to determine if there is anything
 48 left on the line.  If so, it returns the next symbol, as in the
 49 ask_$ask_ entry point, and sets a flag to 1.  Otherwise, it sets the
 50 flag to 0 and returns.
 51 
 52 
 53 Syntax:
 54 declare ask_$ask_c entry (char(*), fixed bin);
 55 call ask_$ask_c (ans, flag);
 56 
 57 
 58 Arguments:
 59 ans
 60    is the next symbol, if any.  (Output)
 61 flag
 62    is the symbol flag.  (Output).  Its value can be:
 63       1   if the symbol is returned.
 64       0   if there is no symbol.
 65 
 66 
 67 :Entry:  ask_cint:  02/26/85 ask_$ask_cint
 68 
 69 
 70 Function:  This entry point is a conditional entry for integers.  If an
 71 integer is available on the line, it is returned and the flag is set to
 72 1.  If the line is empty, the flag is set to 0.  If there is a symbol
 73 on the line, but it is not a number, it is left on the line and the
 74 flag is set to -1.
 75 
 76 
 77 Syntax:
 78 declare ask_$ask_cint entry (fixed bin, fixed bin);
 79 call ask_$ask_cint (int, flag);
 80 
 81 
 82 Arguments:
 83 int
 84    is the returned value, if any.  (Output)
 85 flag
 86    is the int flag.  (Output).  Its value can be:
 87       1   if int is returned.
 88       0   if the line is empty.
 89      -1   if there is no number.
 90 
 91 
 92 :Entry:  ask_cflo:  02/26/85 ask_$ask_cflo
 93 
 94 
 95 Function:  This entry point works like the ask_$ask_cint entry point
 96 but returns a floating value, if an integer is available.
 97 
 98 
 99 Syntax:
100 declare ask_$ask_cflo entry (float bin, fixed bin);
101 call ask_$ask_cflo (flo, flag);
102 
103 
104 Arguments:
105 flo
106    the returned value, if any.  (Output)
107 flag
108    is the flow flag.  (Output).  Its value can be:
109       0    if the line is empty.
110       1    if the value is returned.
111      -1    if it is not a number.
112 
113 
114 :Entry:  ask_cline:  02/26/85 ask_$ask_cline
115 
116 
117 Function:  This entry point returns any part of the line that remains.
118 A flag is set if the rest of the line is empty.
119 
120 
121 Syntax:
122 declare ask_$ask_cline entry (char(*), fixed bin);
123 call ask_$ask_cline (line, flag);
124 
125 
126 Arguments:
127 line
128    is the returned line, if any.  (Output)
129 flag
130    is the line flag.  (Output).  Its value can be:
131       1   if the line is returned.
132       0   if the line is empty.
133 
134 
135 :Entry:  ask_clr:  02/26/85 ask_$ask_clr
136 
137 
138 Function:  This entry point clears the internal line buffer.  Because
139 the buffer is internal static, the input of one program can
140 accidentally be passed to another unless the second begins with a call
141 to this entry point.  If a value typed by the user is incorrect and if
142 the program wishes to ask for the line to be retyped, the ask_$ask_clr
143 entry point can also be called.
144 
145 
146 Syntax:
147 declare ask_$ask_clr entry;
148 call ask_$ask_clr;
149 
150 
151 :Entry:  ask_cnf:  02/26/85 ask_$ask_cnf
152 
153 
154 Function:  This entry point works like the ask_$ask_cint entry point
155 except that it returns a value of "on" or "off" if a character string
156 of either "on" or "off" is available.
157 
158 
159 Syntax:
160 declare ask_$ask_cnf entry (char(*), fixed bin);
161 call ask_$ask_cnf (ans, flag);
162 
163 
164 Arguments:
165 ans
166    is a value of "on" or "off" if such a value is present.  (Output)
167 flag
168    is the yn flag.  (Output).  Its value can be:
169       1  if a "on" or "off" value is returned.
170       0  if the line is empty.
171      -1  if the next value on the line is not "on" or "off"
172 
173 
174 :Entry:  ask_cyn:  02/26/85 ask_$ask_cyn
175 
176 
177 Function: This entry point works like the ask_$ask_cint entry point
178 except that it returns a value of yes (or y) or no (or n) if a
179 character string of either "yes" or "no" is available.
180 
181 
182 Syntax:
183 declare ask_$ask_cyn (char(*), fixed bin);
184 call ask_$ask_cyn (ans, flag);
185 
186 
187 Arguments:
188 ans
189    is a value of yes (or y) or no (or n) if such a value is present.
190    (Output)
191 flag
192    is the yn flag.  (Output).  Its value can be:
193       1  if a yes (or y) or no (or n) value is returned.
194       0  if the line is empty.
195      -1  if the next value on the line is not yes (or y) or no (or n).
196 
197 
198 :Entry:  ask_int:  02/26/85 ask_$ask_int
199 
200 
201 Function:  This entry point works the same as the ask_$ask_ entry point
202 except that the next item on the line must be a number.  An integer
203 value is returned.  Numbers can be fixed point or floating point,
204 positive or negative.  A leading dollar sign or a comma is ignored.  If
205 the value typed is not a number, the program types:
206    "string" nonnumeric.  Please retype:
207 and waits for the user to retype the line.
208 
209 
210 Syntax:
211 declare ask_$ask_int entry options (variable);
212 call ask_$ask_int (ctl, int, ioa_args);
213 
214 
215 Arguments:
216 ctl
217    is an ioa_ control string (char(*)) in the same format as that used
218    by the ioa_ subroutine.  (Input).  If a period is typed, zero is
219    returned.
220 int
221    is the return value (fixed bin).  (Output)
222 ioa_args
223    are any number of arguments to be converted according to ctl.
224    (Input)
225 
226 
227 :Entry:  ask_flo:  02/26/85 ask_$ask_flo
228 
229 
230 Function:  This entry point works like the ask_$ask_int entry point
231 except that it returns a floating value.
232 
233 
234 Syntax:
235 declare ask_$ask_flo entry options (variable);
236 call ask_$ask_flo (ctl, flo, ioa_args);
237 
238 
239 Arguments:
240 ctl
241    is an ioa_ control string (char(*)) in the same format as that used
242    by the ioa_ subroutine.  (Input).  If a period is typed, zero is
243    returned.
244 flo
245    is the return value (float bin).  (Output)
246 ioa_args
247    are any number of arguments to be converted according to ctl.
248    (Input)
249 
250 
251 :Entry:  ask_line:  02/26/85 ask_$ask_line
252 
253 
254 Function:  This entry returns the remainder of the line typed by the
255 user.  Leading blanks are removed.  If there is nothing left on the
256 line, the program prompts and reads a new line.
257 
258 
259 Syntax:
260 declare ask_$ask_line entry options (variable);
261 call ask_$ask_line (ctl, line, ioa_args);
262 
263 
264 Arguments:
265 ctl
266    is an ioa_ control string (char(*)) in the same format as that used
267    by the ioa_ subroutine.  (Input)
268 line
269    is the return value (char(*)).  (Output)
270 ioa_args
271    are any number of arguments to be converted according to ctl.
272    (Input)
273 
274 
275 :Entry:  ask_n:  02/26/85 ask_$ask_n
276 
277 
278 Function:  This entry point scans the line and returns the next symbol
279 without changing the line pointer.  A call to the ask_ entry point
280 later returns the same value.
281 
282 
283 Syntax:
284 declare ask_$ask_n entry (char(*), fixed bin);
285 call ask_$ask_n (ans, flag);
286 
287 
288 Arguments:
289 ans
290    is the returned symbol, if any.  (Output)
291 flag
292    is the ans flag.  (Output).  Its value can be:
293       0  if the line is empty.
294       1  if the symbol is returned.
295 
296 
297 :Entry:  ask_nf:  02/26/85 ask_$ask_nf
298 
299 
300 Function:  This entry point works like ask_$ask_yn except that it
301 returns a value of "on" or "off".
302 
303 
304 Syntax:
305 declare ask_$ask_nf entry options (variable);
306 call ask_$ask_nf (ctl, line, ioa_args);
307 
308 
309 Arguments:
310 ctl
311    is an ioa_ control string (char(*)) in the same format as that used
312    by the ioa_ subroutine.  (Input)
313 line
314    is the return value (char(*)).  (Output)
315 ioa_args
316    are any number of arguments to be converted according to ctl.
317    (Input)
318 
319 
320 :Entry:  ask_nflo:  02/26/85 ask_$ask_nflo
321 
322 
323 Function:  This entry point scans the line for floating point numbers.
324 
325 
326 Syntax:
327 declare ask_$ask_nflo entry (float bin, fixed bin);
328 call ask_$ask_nflo (flo, flag);
329 
330 
331 Arguments:
332 flo
333    is the returned value, if any. If a period is typed, zero is
334    returned. (Output)
335 flag
336    is the flow flag.  (Output).  Its value can be:
337       0    if the line is empty.
338       1    if the value is returned.
339      -1    if it is not a number.
340 
341 
342 :Entry:  ask_nint:  02/26/85 ask_$ask_nint
343 
344 
345 Function:  This entry point scans the line for integers.  The second
346 argument is returned as -1 if there is a symbol on the line but it is
347 not a number, 1 if successful, and 0 if the line is empty.
348 
349 
350 Syntax:
351 declare ask_$ask_nint entry (fixed bin, fixed bin);
352 call ask_$ask_nint (int, flag);
353 
354 
355 Arguments:
356 int
357    is the returned value, if any. If a period is typed, zero is
358    returned. (Output)
359 flag
360    is the int flag.  (Output).  Its value can be:
361       1   if int is returned.
362       0   if the line is empty.
363      -1   if there is no number.
364 
365 
366 :Entry:  ask_nline:  02/26/85 ask_$ask_nline
367 
368 
369 Function:  This entry point initiates a scan of the rest of the line.
370 
371 
372 Syntax:
373 declare ask_$ask_nline entry (char(*), fixed bin);
374 call ask_$ask_nline (line, flag);
375 
376 
377 Arguments:
378 line
379    is the returned line, if any.  (Output)
380 flag
381    is the line flag.  (Output).  Its value can be:
382       1   if the line is returned.
383       0   if the line is empty.
384 
385 
386 :Entry:  ask_nnf:  02/26/85 ask_$ask_nnf
387 
388 
389 Function:  This entry point returns the next symbol, if it is an "on"
390 or "off" value, without changing the line pointer.
391 
392 
393 Syntax:
394 declare ask_$ask_nnf entry (char(*), fixed bin);
395 call ask_$ask_nnf (ans, flag);
396 
397 
398 Arguments:
399 ans
400    is a value of "on" or "off" if such a value is present.  (Output)
401 flag
402    is the yn flag.  (Output).  Its value can be:
403       1  if a "on" or "off" value is returned.
404       0  if the line is empty.
405      -1  if the next value on the line is not "on" or "off."
406 
407 
408 :Entry:  ask_nyn:  02/26/85 ask_$ask_nyn
409 
410 
411 Function:  This entry point returns the next symbol, if it is a yes (or
412 y) or no (n) value, without changing the line pointer.  The arguments
413 are the same as those used with the ask_$ask_cint entry point.
414 
415 
416 Syntax:
417 declare ask_$ask_nyn entry (char(*), fixed bin);
418 call ask_$ask_nyn (ans, flag);
419 
420 
421 Arguments:
422 ans
423    is a value of yes (or y) or no (or n) if such a value is present.
424    (Output)
425 flag
426    is the yn flag.  (Output).  Its value can be:
427       1  if a yes (or y) or no (or n) value is returned.
428       0  if the line is empty.
429      -1  if the next value on the line is not yes (or y) or no (or n)
430 
431 
432 :Entry:  ask_prompt:  02/26/85 ask_$ask_prompt
433 
434 
435 Function:  This entry point deletes the current contents of the
436 internal line buffer and prompts for a new line.  The line is read in
437 and the entry returns.
438 
439 
440 Syntax:
441 declare ask_$ask_prompt entry options (variable);
442 call ask_$ask_prompt (ctl, ioa_args);
443 
444 
445 Arguments:
446 ctl
447    is a control string (char(*)) similar to that typed by the ioa_
448    subroutine.  (Input)
449 ioa_args
450    are any number of arguments to be converted according to ctl.
451    (Input)
452 
453 
454 :Entry:  ask_setline:  02/26/85 ask_$ask_setline
455 
456 
457 Function:  This entry point sets the internal static buffer for the
458 ask_ subroutine to the given input line so that the line can be
459 scanned.
460 
461 
462 Syntax:
463 declare ask_$ask_setline entry (char(*));
464 call ask_$ask_setline (line);
465 
466 
467 Arguments:
468 line
469    is the line to be placed in the ask_ buffer.  (Input).  Trailing
470    blanks are removed from line.  A carriage return is optional at the
471    end of line.
472 
473 
474 :Entry:  ask_yn:  02/26/85 ask_$ask_yn
475 
476 
477 Function:  This entry point works like the ask_$ask_int entry point
478 except that it returns a value of yes (or y) or no (or n).  Its
479 arguments are the same as those used with the ask_$ask_int entry point.
480 
481 
482 Syntax:
483 declare ask_$ask_yn entry options (variable);
484 call ask_$ask_yn (ctl, ans, ioa_args);
485 
486 
487 Arguments:
488 ctl
489    is an ioa_ control string (char(*)) in the same format as that used
490    by the ioa_ subroutine.  (Input)
491 ans
492    is a value of yes (or y) or no (or n) if such a value was present.
493    (Input)
494 ioa_args
495    are any number of arguments to be converted according to ctl.
496    (Input)