Printer Version Table of Contents Project Home Page
.FUNCTION....: Getk (Get Keypress) Function
.CATEGORY....: functions
The GETK function waits for the user to press an acceptable key, then produces the key as its output. If the key pressed is a letter, then the letter is returned IN UPPER CASE. This feature is designed to support simple "pick a menu selection" processing in batch files.

The GETK function takes a /K "keymask" parameter that tells it which keys to accept. If the user presses an unacceptable key (i.e. one that is not in the keymask), the keypress is ignored.

If no /K parm is specified, the default keymask is:

ABCDEFGHIJKLMNOPQRSTUVWXYZx That is, the default keymask will accept letters and the ESCAPE key.



The keymask may contain numbers, uppercase letters, and any of the other printable characters on the keyboard.

There is no way to tell Fdate to accept "special" keypresses such as function keys, ALT or CONTROL keys, arrow keys, etc.

If the keymask contains an uppercase letter (e.g. "A"), and the user presses the corresponding unshifted letter (e.g. "a"), then the keypress will be accepted and the uppercase letter will be returned.

The keymask may contain the following lowercase letters, which have special meanings:

For example:

If a keymask of "/kXx" was specified, then if the user pressed the
(shifted or unshifted) "X" key, then uppercase "X" would be returned.

If he pressed the ESCAPE key, then lowercase "x" would be returned.


Starting with version 10, GETK takes a /W "seconds to wait" parameter that tells it how many seconds to wait before returning the first key in the /K "keymask" parameter. Valid values are in the range of 1..36000 (10 hours). Default value of /W is 36000 (10 hours).


When the GETK function returns a key, it sets the DOS errorlevel to a value corresponding to the position of that key in the keymask. For example, with keymask of "/kABx", if the user presses:

          "A": value returned will be "A", errorlevel will be 1
          "B": value returned will be "B", errorlevel will be 2
       ESCAPE: value returned will be "x", errorlevel will be 3
If the user presses CONTROL+BREAK, Fdate will abort and return errorlevel 255.

  @echo off
  echo Demonstration of Fdate's GETK (get keypress) function
  echo Press CONTROL+BREAK to end
  Fdate /fGetK /P"You pressed: " /Q"Press a key: "  /K"12ABxe "
  if errorlevel 1  if not errorlevel 2  echo errorlevel : 1
  if errorlevel 2  if not errorlevel 3  echo errorlevel : 2
  if errorlevel 3  if not errorlevel 4  echo errorlevel : 3
  if errorlevel 4  if not errorlevel 5  echo errorlevel : 4
  if errorlevel 5  if not errorlevel 6  echo errorlevel : 5
  if errorlevel 6  if not errorlevel 7  echo errorlevel : 6
  if errorlevel 7  if not errorlevel 8  echo errorlevel : 7
  if errorlevel 255 echo ERRORLEVEL 255
  if errorlevel 255 goto endit
  goto top

Note that the keymask may contain blanks if the keymask is enclosed in quotes (as in this example batch file). But remember that Fdate eliminates redundant spaces when obtaining its parameter input, so you should never include more than one blank in your keymask.

Modifying the Keymask

It is often necessary to make program modifications during the life of a batch file. If you are using the GETK function and testing the errorlevel rather than the environment, then the insertion or deletion of characters into the existing keymask will change the errorlevels returned by the following characters in the keymask. This will force you to re-write the errorlevel tests, which may be a big job if the keymask is long.

Here are some tips on how to avoid this work:

Displaying a User Prompt With GETK

The /Q (user prompt) parameter is especially handy when used in conjunction with the GETK function. If the /Q prompt-string parameter is specified (as in the example batch file, above), then the prompt string is displayed, but a NEWLINE is not written to the screen before waiting for the user's keypress.

For a program that provides more sophisticated "get key" functions for batch files, I recommend Bob Stephan's shareware program GET, which is described elsewhere in this documentation.