|Purpose:||Get a string from the keyboard and save it in an environment or array variable|
|Format:||INPUT [/C /D /E["default"] /K"keys" /Ln /N /P /Wn /X] [prompt ] %%varname|
|prompt||Optional text that is displayed as a prompt.|
|varname||The variable that will hold the user's input.|
INPUT optionally displays a prompt, then waits for your entry and stores it in an environment or array variable. INPUT is normally used in batch files and aliases to get multi-character input (for single keystroke input, see INKEY).
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.
INPUT returns when you press carriage return. 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.
INPUT supports regular expressions for the mask (/K"xxx"). You must prefix the regular expression with :: - for example:
input /k"::^[0-9]$" Enter a number: %%number
Numeric input may be entered in either decimal format (a sequence of 0-9 digits) or in hexadecimal format ("0x" followed by a sequence of 0-F hex digits).
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.
You can pipe text to INPUT, but it will set the variable in the "child" process used to handle the right hand side of the pipe. This variable will not be available in the original copy of TCC used to start the pipe.
|/E||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. If there is no existing value and you provide an optional default value, INPUT will display the default value for editing.|
|/K"keys"||Specifies the permissible keystrokes. The list of valid keystrokes should be enclosed in double quotes. For alphabetic keys the validity test is not case sensitive.|
input /k"[0-9]-()" Enter your phone number: %%var
You can specify extended keys by enclosing their names in square brackets (within the quotes), See Keys and Key Names for a complete listing of the key names you can use within the square brackets, and a description of the key name format.
If an invalid keystroke is entered, TCC will beep and wait for another keystroke.
|/Ln||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||Disables the use of input colors defined in the Colors configuration options, and forces INPUT to use the default display colors.|
|/W||Time-out period, in seconds, to wait for a response. If no keystroke is entered by the end of the time-out 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 time-out 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.|