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