Purpose: | Get a string from the keyboard and save it in an environment or array variable |
Format: | INPUT [/= /C /D /E["default"] /K"keys" /Lmax[:min] /N /P /T /Wn /X] [prompt ] %%varname |
prompt | Optional text that is displayed as a prompt. |
varname | The variable that will hold the user's input. |
See also: SET, INKEY, KEYSTACK, MSGBOX, and QUERYBOX.
Usage:
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).
INPUT works within the command line window. If you prefer to us a dialog for user input, see the MSGBOX and QUERYBOX commands.
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-RT used to start the pipe.
If you don't enter any arguments, INPUT will display its command dialog.
Options:
/= | Display the INPUT command dialog to help you set the command line options. The /= option can be anywhere on the line; additional options will set the appropriate fields in the command dialog. |
/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. |
For example:
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-RT will beep and wait for another keystroke.
/N | Disables the use of input colors defined in the Colors configuration options, and forces INPUT to use the default display colors. |