4DOS Help Topic: INPUT


Purpose: Get a string from the keyboard and save it in an environment
variable.

Format: INPUT %%varname

prompt: Optional text that is displayed as a prompt.
varname: The variable that will hold the user's input.

/C(lear buffer) /N(o colors)
/D(igits only) /P(assword)
/E(dit) /W(ait)
/L(ength) /X (no carriage return)

See also: INKEY and KEYSTACK.

Usage

INPUT optionally displays a prompt. Then it waits for a specified time or
indefinitely for your entry. It places any characters you type into an
environment variable. INPUT is normally used in batch files and aliases to
get multi-key input. Along with the INKEY command, INPUT allows great
flexibility in reading user input from within a batch file or alias.

If prompt text is included in an INPUT command, it is displayed while INPUT
waits for input. Standard command-line editing keys may be used to edit the
input string as it is entered. If you use the /P password option, INPUT
will echo asterisks instead of the keys you type.

All characters entered up to, but not including, the carriage return are
stored in the variable.

The following batch file fragment prompts for a string and stores it in the
variable FNAME:

input Enter the file name: %%fname

INPUT reads standard input, so it will accept text from a redirected file or
from the KEYSTACK.

If you press Ctrl-C or Ctrl-Break while INPUT is waiting for input,
execution of an alias will be terminated, and execution of a batch file will
be suspended while you are asked whether to cancel the batch job. A batch
file can handle Ctrl-C and Ctrl-Break itself with the ON BREAK command.

In 4DOS you can pipe text to INPUT from another command, which will stash
the first line of the command's output in the specified variable. However,
this trick will not work in 4NT or Take Command, which implement pipes
differently. The @EXECSTR function provides a more portable way to get the
first line of a command's output.

Options

/C: (Clear buffer) Clears the keyboard buffer before INPUT accepts
keystrokes. If you use this option, INPUT will ignore any
keystrokes which you type, either accidentally or intentionally,
before INPUT is ready.

/D: (Digits only) Prevents INPUT from accepting any keystroks except
digits from 0 to 9.

/E: (Edit) Allows you to edit an existing value. If there is no
existing value for varname, INPUT proceeds as if /E had not been
used, and allows you to enter a new value.

/Ln: (Length) Sets the maximum number of characters which INPUT will
accept to "n". If you attempt to enter more than this number of
characters, INPUT will beep and prevent further input (you will
still be able to edit the characters typed before the limit was
reached).

/N: (No colors) Disables the use of input colors defined in the
InputColors directive in 4DOS.INI, and forces INPUT to use the
default display colors.

/P: (Password) Tells INPUT to echo asterisks, instead of the
characters you type.

/W: (Wait) Timeout period, in seconds, to wait for a response. If no
keystroke is entered by the end of the timeout period, INPUT
returns with the variable unchanged. This allows you to continue
the batch file if the user does not respond in a given period of
time. If you enter a key before the timeout period, INPUT will
wait indefinitely for the remainder of the line. You can specify
/W0 to return immediately if there are no keys waiting in the
keyboard buffer.

/X: (No carriage return) Prevents INPUT from adding a carriage
return and line feed after the user's entry.