<< Click to Display Table of Contents >>

Navigation:  TCC > Commands >


Purpose:Get a single keystroke from the user and store it in an environment or array variable


Format:INKEY [/= /C /D /K"keys" /P /M /Wn /X]  [prompt] %%varname


promptOptional text that is displayed as a prompt.
varnameThe variable that will hold the user's keystroke.
waitTime to wait for a keystroke, in seconds



Clear buffer




Digits only




valid keystrokes


no carriage return


Mouse buttons


See also: INPUT.




INKEY optionally displays a prompt, then it waits for a specified time (or indefinitely) for a keystroke, and places the keystroke into an environment or array variable. It is normally used in batch files and aliases to get a menu choice or other single-key input. Along with the INPUT command, INKEY allows great flexibility in reading input from within a batch file or alias.


If prompt is included in an INKEY command, it is displayed while INKEY waits for input.


The following batch file fragment prompts for a character and stores it in the variable NUM:


inkey /D Enter a number from 1 to 9:  %%num


INKEY reads standard input for the keystroke, so it will accept keystrokes from a redirected file or from KEYSTACK. You can supply a list of valid keystrokes with the /K option.


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).


A standard keystroke is stored directly in the environment variable. An extended keystroke (for example, a function key or a and cursor key) is stored as a string, consisting of a leading @, followed by its scan code as a decimal number, e.g., the F1 key is stored as @59. The Enter key is stored as an extended keystroke @28. See ASCII, Key Codes, and ANSI X3.64 Commands for scan codes.


When the /M option enables recognition of mouse buttons, (and /W is not specified), the variable is set to a single character with one of the codes below:











You can get the screen position of the last mouse click with the _xmouse and _ymouse internal variables.


To test for a non-printing value returned by INKEY use the @ASCII function to get the numeric value of the key, or convert the expected value of the code to a code using @CHAR. For example, to test for Esc, which has an ASCII value of 27 or a left mouse button:


inkey Enter a key:  %%key

if "%@ascii[%key]" == "27" echo Esc pressed

if %key EQ %@char[240] echo Left mouse button clicked


If you press Ctrl-C or Ctrl-Break while INKEY is waiting for a key, 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 with the ON BREAK command.


If you don't enter any arguments, INKEY will display its command dialog.


INKEY works within the command line window. If you prefer to use a dialog for user input, see the MSGBOX and QUERYBOX commands.




/=Display the INKEY 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.


/CClears the keyboard buffer before INKEY accepts keystrokes. If you use this option, INKEY will ignore any keystrokes which you type, either accidentally or intentionally, before it is ready to accept input. You can use the /C option by itself if you want to clear the keyboard buffer without setting a variable.


/DOnly accept numbers from 0 to 9.


/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. You can specify extended keys by enclosing their names in square brackets (within the quotes), for example:


inkey /k"ab[Ctrl-F9]" Enter A, B, Ctrl-F9 %%var


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 echo the keystroke if possible, beep, move the cursor back one character, and wait for another keystroke.


/MAccept mouse button clicks. This is enabled only if Windows' Quick Edit is disabled (alt-space -> Properties -> Options).


/PPrevents INKEY from echoing the character.


/WTime-out period, in seconds, to wait for a response. If no keystroke is entered by the end of the time-out period, INKEY 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. You can specify /W0 to return immediately if there are no keys waiting in the keyboard buffer. If /W is specified, mouse buttons are ignored.


For example, the following batch file fragment waits up to 10 seconds for a character, then tests to see if a "Y" was entered:


set netmon=N

inkey /K"YN" /w10 Network monitor (Y/N)?  %%netmon

iff "%netmon" == "Y" then

 rem Commands to load the monitor program



/XPrevents INKEY from displaying a carriage return and line feed after the user's entry.