02/26/90  ask_


The ask_ subroutine provides a flexible terminal input facility for
whole lines, strings delimited by blanks, or fixed-point and
floating-point numbers.  Special attention is given to prompting the
terminal user.

The main entry point returns the next string of characters delimited by
blanks or tabs from the line typed by the user.  If the line buffer is
empty, the ask_ subroutine formats and types out a prompting message
and reads a line from the user_input I/O switch.


Entry points in ask_:
   (List is generated by the help command)


:Entry:  ask_:  02/26/85  ask_


Function:
provides a flexible terminal input facility for
whole lines, strings delimited by blanks, or fixed-point and
floating-point numbers.


Syntax:
declare ask_ entry options (variable);
call ask_ (ctl, ans, ioa_args);


Arguments:
ctl
   is an ioa_ control string (char(*)) in the same format as that used
   by the ioa_ subroutine.  (Input)
ans
   is the return value (char(*)).  (Output)
ioa_args
   are any number of arguments to be converted according to ctl.
   (Input)


:Entry:  ask_c:  02/26/85 ask_$ask_c


Function:  This entry point tests to determine if there is anything
left on the line.  If so, it returns the next symbol, as in the
ask_$ask_ entry point, and sets a flag to 1.  Otherwise, it sets the
flag to 0 and returns.


Syntax:
declare ask_$ask_c entry (char(*), fixed bin);
call ask_$ask_c (ans, flag);


Arguments:
ans
   is the next symbol, if any.  (Output)
flag
   is the symbol flag.  (Output).  Its value can be:
      1   if the symbol is returned.
      0   if there is no symbol.


:Entry:  ask_cint:  02/26/85 ask_$ask_cint


Function:  This entry point is a conditional entry for integers.  If an
integer is available on the line, it is returned and the flag is set to
1.  If the line is empty, the flag is set to 0.  If there is a symbol
on the line, but it is not a number, it is left on the line and the
flag is set to -1.


Syntax:
declare ask_$ask_cint entry (fixed bin, fixed bin);
call ask_$ask_cint (int, flag);


Arguments:
int
   is the returned value, if any.  (Output)
flag
   is the int flag.  (Output).  Its value can be:
      1   if int is returned.
      0   if the line is empty.
     -1   if there is no number.


:Entry:  ask_cflo:  02/26/85 ask_$ask_cflo


Function:  This entry point works like the ask_$ask_cint entry point
but returns a floating value, if an integer is available.


Syntax:
declare ask_$ask_cflo entry (float bin, fixed bin);
call ask_$ask_cflo (flo, flag);


Arguments:
flo
   the returned value, if any.  (Output)
flag
   is the flow flag.  (Output).  Its value can be:
      0    if the line is empty.
      1    if the value is returned.
     -1    if it is not a number.


:Entry:  ask_cline:  02/26/85 ask_$ask_cline


Function:  This entry point returns any part of the line that remains.
A flag is set if the rest of the line is empty.


Syntax:
declare ask_$ask_cline entry (char(*), fixed bin);
call ask_$ask_cline (line, flag);


Arguments:
line
   is the returned line, if any.  (Output)
flag
   is the line flag.  (Output).  Its value can be:
      1   if the line is returned.
      0   if the line is empty.


:Entry:  ask_clr:  02/26/85 ask_$ask_clr


Function:  This entry point clears the internal line buffer.  Because
the buffer is internal static, the input of one program can
accidentally be passed to another unless the second begins with a call
to this entry point.  If a value typed by the user is incorrect and if
the program wishes to ask for the line to be retyped, the ask_$ask_clr
entry point can also be called.


Syntax:
declare ask_$ask_clr entry;
call ask_$ask_clr;


:Entry:  ask_cnf:  02/26/85 ask_$ask_cnf


Function:  This entry point works like the ask_$ask_cint entry point
except that it returns a value of "on" or "off" if a character string
of either "on" or "off" is available.


Syntax:
declare ask_$ask_cnf entry (char(*), fixed bin);
call ask_$ask_cnf (ans, flag);


Arguments:
ans
   is a value of "on" or "off" if such a value is present.  (Output)
flag
   is the yn flag.  (Output).  Its value can be:
      1  if a "on" or "off" value is returned.
      0  if the line is empty.
     -1  if the next value on the line is not "on" or "off"


:Entry:  ask_cyn:  02/26/85 ask_$ask_cyn


Function: This entry point works like the ask_$ask_cint entry point
except that it returns a value of yes (or y) or no (or n) if a
character string of either "yes" or "no" is available.


Syntax:
declare ask_$ask_cyn (char(*), fixed bin);
call ask_$ask_cyn (ans, flag);


Arguments:
ans
   is a value of yes (or y) or no (or n) if such a value is present.
   (Output)
flag
   is the yn flag.  (Output).  Its value can be:
      1  if a yes (or y) or no (or n) value is returned.
      0  if the line is empty.
     -1  if the next value on the line is not yes (or y) or no (or n).


:Entry:  ask_int:  02/26/85 ask_$ask_int


Function:  This entry point works the same as the ask_$ask_ entry point
except that the next item on the line must be a number.  An integer
value is returned.  Numbers can be fixed point or floating point,
positive or negative.  A leading dollar sign or a comma is ignored.  If
the value typed is not a number, the program types:
   "string" nonnumeric.  Please retype:
and waits for the user to retype the line.


Syntax:
declare ask_$ask_int entry options (variable);
call ask_$ask_int (ctl, int, ioa_args);


Arguments:
ctl
   is an ioa_ control string (char(*)) in the same format as that used
   by the ioa_ subroutine.  (Input).  If a period is typed, zero is
   returned.
int
   is the return value (fixed bin).  (Output)
ioa_args
   are any number of arguments to be converted according to ctl.
   (Input)


:Entry:  ask_flo:  02/26/85 ask_$ask_flo


Function:  This entry point works like the ask_$ask_int entry point
except that it returns a floating value.


Syntax:
declare ask_$ask_flo entry options (variable);
call ask_$ask_flo (ctl, flo, ioa_args);


Arguments:
ctl
   is an ioa_ control string (char(*)) in the same format as that used
   by the ioa_ subroutine.  (Input).  If a period is typed, zero is
   returned.
flo
   is the return value (float bin).  (Output)
ioa_args
   are any number of arguments to be converted according to ctl.
   (Input)


:Entry:  ask_line:  02/26/85 ask_$ask_line


Function:  This entry returns the remainder of the line typed by the
user.  Leading blanks are removed.  If there is nothing left on the
line, the program prompts and reads a new line.


Syntax:
declare ask_$ask_line entry options (variable);
call ask_$ask_line (ctl, line, ioa_args);


Arguments:
ctl
   is an ioa_ control string (char(*)) in the same format as that used
   by the ioa_ subroutine.  (Input)
line
   is the return value (char(*)).  (Output)
ioa_args
   are any number of arguments to be converted according to ctl.
   (Input)


:Entry:  ask_n:  02/26/85 ask_$ask_n


Function:  This entry point scans the line and returns the next symbol
without changing the line pointer.  A call to the ask_ entry point
later returns the same value.


Syntax:
declare ask_$ask_n entry (char(*), fixed bin);
call ask_$ask_n (ans, flag);


Arguments:
ans
   is the returned symbol, if any.  (Output)
flag
   is the ans flag.  (Output).  Its value can be:
      0  if the line is empty.
      1  if the symbol is returned.


:Entry:  ask_nf:  02/26/85 ask_$ask_nf


Function:  This entry point works like ask_$ask_yn except that it
returns a value of "on" or "off".


Syntax:
declare ask_$ask_nf entry options (variable);
call ask_$ask_nf (ctl, line, ioa_args);


Arguments:
ctl
   is an ioa_ control string (char(*)) in the same format as that used
   by the ioa_ subroutine.  (Input)
line
   is the return value (char(*)).  (Output)
ioa_args
   are any number of arguments to be converted according to ctl.
   (Input)


:Entry:  ask_nflo:  02/26/85 ask_$ask_nflo


Function:  This entry point scans the line for floating point numbers.


Syntax:
declare ask_$ask_nflo entry (float bin, fixed bin);
call ask_$ask_nflo (flo, flag);


Arguments:
flo
   is the returned value, if any. If a period is typed, zero is
   returned. (Output)
flag
   is the flow flag.  (Output).  Its value can be:
      0    if the line is empty.
      1    if the value is returned.
     -1    if it is not a number.


:Entry:  ask_nint:  02/26/85 ask_$ask_nint


Function:  This entry point scans the line for integers.  The second
argument is returned as -1 if there is a symbol on the line but it is
not a number, 1 if successful, and 0 if the line is empty.


Syntax:
declare ask_$ask_nint entry (fixed bin, fixed bin);
call ask_$ask_nint (int, flag);


Arguments:
int
   is the returned value, if any. If a period is typed, zero is
   returned. (Output)
flag
   is the int flag.  (Output).  Its value can be:
      1   if int is returned.
      0   if the line is empty.
     -1   if there is no number.


:Entry:  ask_nline:  02/26/85 ask_$ask_nline


Function:  This entry point initiates a scan of the rest of the line.


Syntax:
declare ask_$ask_nline entry (char(*), fixed bin);
call ask_$ask_nline (line, flag);


Arguments:
line
   is the returned line, if any.  (Output)
flag
   is the line flag.  (Output).  Its value can be:
      1   if the line is returned.
      0   if the line is empty.


:Entry:  ask_nnf:  02/26/85 ask_$ask_nnf


Function:  This entry point returns the next symbol, if it is an "on"
or "off" value, without changing the line pointer.


Syntax:
declare ask_$ask_nnf entry (char(*), fixed bin);
call ask_$ask_nnf (ans, flag);


Arguments:
ans
   is a value of "on" or "off" if such a value is present.  (Output)
flag
   is the yn flag.  (Output).  Its value can be:
      1  if a "on" or "off" value is returned.
      0  if the line is empty.
     -1  if the next value on the line is not "on" or "off."


:Entry:  ask_nyn:  02/26/85 ask_$ask_nyn


Function:  This entry point returns the next symbol, if it is a yes (or
y) or no (n) value, without changing the line pointer.  The arguments
are the same as those used with the ask_$ask_cint entry point.


Syntax:
declare ask_$ask_nyn entry (char(*), fixed bin);
call ask_$ask_nyn (ans, flag);


Arguments:
ans
   is a value of yes (or y) or no (or n) if such a value is present.
   (Output)
flag
   is the yn flag.  (Output).  Its value can be:
      1  if a yes (or y) or no (or n) value is returned.
      0  if the line is empty.
     -1  if the next value on the line is not yes (or y) or no (or n)


:Entry:  ask_prompt:  02/26/85 ask_$ask_prompt


Function:  This entry point deletes the current contents of the
internal line buffer and prompts for a new line.  The line is read in
and the entry returns.


Syntax:
declare ask_$ask_prompt entry options (variable);
call ask_$ask_prompt (ctl, ioa_args);


Arguments:
ctl
   is a control string (char(*)) similar to that typed by the ioa_
   subroutine.  (Input)
ioa_args
   are any number of arguments to be converted according to ctl.
   (Input)


:Entry:  ask_setline:  02/26/85 ask_$ask_setline


Function:  This entry point sets the internal static buffer for the
ask_ subroutine to the given input line so that the line can be
scanned.


Syntax:
declare ask_$ask_setline entry (char(*));
call ask_$ask_setline (line);


Arguments:
line
   is the line to be placed in the ask_ buffer.  (Input).  Trailing
   blanks are removed from line.  A carriage return is optional at the
   end of line.


:Entry:  ask_yn:  02/26/85 ask_$ask_yn


Function:  This entry point works like the ask_$ask_int entry point
except that it returns a value of yes (or y) or no (or n).  Its
arguments are the same as those used with the ask_$ask_int entry point.


Syntax:
declare ask_$ask_yn entry options (variable);
call ask_$ask_yn (ctl, ans, ioa_args);


Arguments:
ctl
   is an ioa_ control string (char(*)) in the same format as that used
   by the ioa_ subroutine.  (Input)
ans
   is a value of yes (or y) or no (or n) if such a value was present.
   (Input)
ioa_args
   are any number of arguments to be converted according to ctl.
   (Input)
