INPUT



INPUT

     Assigns a value to a CI variable by reading its value from the
     $STDIN file, or from the system console.

SYNTAX


INPUT [NAME=]varname
[[;PROMPT=]prompt ] [[;WAIT=]seconds ]
[[;READCNT=]chars ] [[;DEFAULT=]default_str ]
[;CONSOLE ]

PARAMETERS


varname Any variable (that can be set with SETVAR) in which
the input will be stored. If varname does not
already exist, INPUT will create it.

prompt The prompt string that is to be displayed prior to
receiving input. If prompt is omitted, INPUT
displays nothing, but waits for an input value. If
the CONSOLE option is used the prompt is written to
the system console and non-highlighting escape
sequences are removed. Otherwise, the prompt is
written to $STDLIST. If delimiters, such as ","
";" " ", etc., are part of the prompt string, then
the entire prompt string must be enclosed within
quote marks (" or ').

seconds A positive value specifying the number of seconds
for a timed read. If a value is assigned to
seconds, INPUT will wait "seconds" for input and
then terminate the command. The default is zero
(0)--no time limit. The wait value cannot exceed
the positive value of the HPTIMEOUT variable.

chars The number of characters to read from $STDIN. If
chars is specified as a negative number, INPUT uses
the absolute integer value. The maximum allowed
(and the default) is the maximum size of a CI
variable, which is currently 1024 characters.
However, if the CONSOLE option is specified, chars
becomes the maximum length of a legal reply. An
operator may be able to type more than chars
characters, but an error will be reported by the
REPLY command if chars is exceeded. Currently,
CONSOLE replies are limited to 31 characters. If
chars is zero no read is done from $STDIN, and if
the CONSOLE option is used, chars will be set to 31.

default_str A string value to be used as a default for varname
if no response is provided by the user. No response
is indicated if is pressed with no other
input, or if the read has expired due to a timeout.
The default_str is not restricted by the 'chars'
value. If default_str is omitted and the user
provides no input response, varname will be created,
if it does not already exist, with a null string
value. On the other hand, if varname does exist,
its value will not be overwritten on null responses
unless default_str is supplied.

console When CONSOLE is specified the prompt is written to
the system console, and the value for varname is
read from the console. All of the INPUT command
features are available for console input. However,
due to some internal restrictions the maximum input
size is 31 characters, and the maximum prompt size
is approximately 80 characters. Absence of the
CONSOLE option increases the input value to the
maximum size of a CI variable (1024 characters), and
the prompt can be as large as the CI's internal
buffer (less the characters needed for the rest of
the command).

OPERATION

     This command allows the user to assign a value interactively to a
     variable.  It also allows the user to create an optional prompt
     message that will be displayed on the standard list device
     ($STDLIST), or the console, before the value is read.  If the
     prompt is omitted INPUT displays nothing, but issues a read against
     $STDIN or the system console.  INPUT stores the value read as a
     string in the variable named varname.

     The INPUT command provides a way to establish an interactive dialog
     with an executing UDC or command file.  The variable, varname, will
     always be created by INPUT if it does not yet exist.  Varname's
     value is typically the exact value entered as a response by the
     user; however, if the user enters no response (either by just
     pressing the enter key, or via the INPUT read expiring) varname's
     value is determined as follows:

- if a DEFAULT= value is provided that becomes the value for varname. - if no DEFAULT= is specified and varname already exists it is not changed. - if no DEFAULT= and varname does not exist it is created with a value of "" (empty string).

 To delete varname before ending a session, job, or program, use the
DELETEVAR command.

The INPUT command can be used with CI I/O redirection to read
from a disk file. I/O redirection may be specified, but has no
meaning, when the CONSOLE option is used.

The user may request a timed read by specifying the WAIT parameter.
The read will be cancelled after WAIT seconds. The INPUT command
also recognizes the HPTIMEOUT predefined variable. The length of
the timed read is seconds or HPTIMEOUT (in minutes), whichever is
smaller. If a timed read (using seconds or HPTIMEOUT) expires,
then the pending read terminates and CIWARN 9003 is reported. If
the CONSOLE option was selected and the INPUT read times out, the
entry in the Reply Information Table (RIT) is removed.

The user may optionally restrict the number of characters to be
read by specifying the READCNT parameter. For example, if
readcnt=1 is supplied, the read will terminate after the 1st
character is typed by the user. The behavior is slightly
different when the CONSOLE option is used. In this case, the
READCNT value is treated as the maximum number of characters
allowed in the reply.

This command is available in a session, job, or program or in
BREAK. Pressing [Break] aborts the execution of this command,
without creating or modifying varname. However, break is not
detectable when using the CONSOLE option, so it may be wise to
always use the WAIT parameter for console requests.

EXAMPLE(S)

     It is vital to remember that INPUT does not evaluate expressions,
     but merely stores them as a string.  The command 'INPUT bleep'
     accepts input (somevalue) from the user and stores it as a string.
To treat "somevalue" as an expression and evaluated the SETVAR
command must be invoked after executing the INPUT command.

INPUT bleep
SETVAR bleep !bleep

The first command reads whatever value the user responds with and
sets bleep to the string representation of that input.

The second command will assign bleep the (evaluated) value that was
supplied by the user.

INPUT BLEEP,>
>123[Return]
CALC typeof(bleep)
2, %$, %2 # this is a string variable
SETVAR BLEEP !BLEEP # convert bleep to an integer

INPUT BLEEP,>
>ABC[Return]
SETVAR BLEEP !BLEEP

ABC is not a number. And, since the user did not provide quotes
around it, ABC is not a string in the right-hand side of the
SETVAR command. If ABC is not a defined variable, it has no value
to extract. So, the attempt to evaluate the result of explicitly
dereferencing !BLEEP produces an error.

INPUT go,"Is the first job ready?";readcnt=1;default=Y;console

This example writes the prompt "Is the first job ready?" to the
system console, accepts a reply of one character, provides a
default response of "Y", and stores the result in the CI variable
name GO.

INPUT record <*msg

This example reads a single record from the file referred to by the
file equation *MSG into the CI variable named RECORD.


ADDITIONAL INFORMATION

Commands:   DELETEVAR, SETVAR, REPLY, RECALL, TELLOP, input()
For help on the input() function, enter "HELP INPUTFN"

Manuals : Using the 900 Series HP 3000: Advanced Skills Self-
Paced Training (32650-60039)