FULLSCREEN CONTENTS Project Home Page
.FUNCTION....: Getk (Get Keypress) Function
.ALIAS.......: getk_function
.CATEGORY....: functions 
.DISCUSSION..:
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.

SPECIFYING THE KEYMASK
===================================

NOTE THAT THE VALUES SPECIFIED ON THE /K PARM ARE CASE-SENSITIVE.

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:


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


 SPECIFYING HOW MANY SECONDS TO WAIT FOR A KEYPRESS
 ========================================================

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



 GETK RESULTS ALSO IN ERRORLEVEL
 ===========================================

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.

.EXAMPLE:
  @echo off
  cls
  echo Demonstration of Fdate's GETK (get keypress) function
  echo Press CONTROL+BREAK to end
  :top
  echo.
  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
  :endit
     ==================================================================

     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:

  *  When ADDING a character to the keymask, always add it at the END
     of the keymask.

  *  When DELETING a character from the keymask, do not actually
     delete it.  Instead, replace it by a lowercase "z".


 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.