August 21, 1993               GETKEY ver. 1.6
                                    by
                              Matthew G. Moody
                              206 Waterwood Dr.
                              Goose Creek, SC 29445
                              (803) 572-4868
                              CIS 72607,3461


  This is my seventh update to GETKEY.  The first version simply retrieved a 
key from the keyboard and returned a value to dos that ERRORLEVEL could 
detect.  My brother asked if MSDOS 6 already had a batch file command that 
would do this already.  So I looked into it and sure enough, there was.  
That command is CHOICE.  So I set about writing a probram to mimic it, 
mainly for the challenge.  The second version of GETKEY followed CHOICE 
exactly, with the exception of the time delay parameter.  The third 
version included that parameter.  The fourth revision accepted menu items
and set the display colors for the menu. 
  
  The fifth revision takes the tilde prefixed characters in the menu items
and forces them to be the valid keys to accept, in other words, the /c 
switch is ignored when the program encounters a tilde character (~) within
an /m switch.  Also, I changed the key prompt to output in highlight. To make
this more like DOS's CHOICE when you press a valid choice it is displayed at
the end of the prompt string.

  The sixth was a minor revision to solve the bug that occured when using the 
timed response switch.  It was displaying "null pointer assignment" after the 
program ended.  That was a tricky little bugger to find.  
Thanks to Glenn R. Sogge for his help in locating that sneaky rascal.

  This revision brings the capability to read in a text file with the command
switches listed in it so the user may create longer menus.
  
  GETKEY waits for the user to choose one of a set of choices.

The syntax for GETKEY is:

GETKEY [/|-C[:]choices] [/|-N] [/|-S] [/|-T[:]c,nn] [/|-D[:]b,f,h] ["text"]
       [/|-M"~menu 1"] ... [/|-Mx,y"menu ~n] [/|-Fmenufile.gks]
NOTE: You may use - or / to delimit parameters.

/C[:]choices     Specifies allowable keys. Default is YN
/N               Do not display choices and ? at end of prompt string.
/S               Treat choice keys as case sensitive.
/T[:]c,nn        Default choice to c after nn seconds
/D[:]b,f,h       Display attributes for background, foreground, and 
                 highlight.
/M[x,y]"menu ~1" Text string to display as a menu item at x,y coordinates.
/Fmenufile.gks   Menu file with arguments (It is assumed the file has the 
                 .gks extension.)
"text"           Prompt string to display

ERRORLEVEL is set to offset of key user presses in choices.

  Because GETKEY is not the same as choice any longer, this could be useful
to everyone.  If you have any ideas on how to improve it further please let me 
know via "The Penetentiary BBS", (706) 737-5631 (my brother runs that board so 
you can leave a private message with him or me.  If you found this on a BBS 
in the Charleston area, you can leave a note for me where you found this. Also 
you can leave a message to me on CompuServe.  My CompuServe address is shown 
above.

  Please let me know what you think of GETKEY this is the first program I have
written to be used by anyone other than myself.  Also, I am open to suggestions
for improvements, add-ons, or what-have-you.

  GETKEY goes beyond merely replacing ASK.COM.  With it, you aren't limited 
just to posing yes/no questions.  For example, using GETKEY, you could ask 
this question in your batch:

Select setup: Command line, DOS Shell, Windows [C,D,W]?
  
  The command for the above would be:
  GETKEY "Select setup: Command line, DOS Shell, Windows " /C:CDW

  The /C switch tells GETKEY what keys for which to wait.  In the case above, 
those would be C, D, and W, which are displayed as a prompt in GETKEY's 
output.  Because the C key comes first, it will generate an errorlevel of 1, D
will generate 2, and W will be 3.
  To test for these errorlevels in your batch files, you will need to stack
your IF ERRORLEVEL statements carefully.  The reason for this is because IF
ERRORLEVEL tests out positive when the value returned is equal to or greater 
than the value specified in the IF ERRORLEVEL test.  This can be tricky, as 
the following example shows:

          IF ERRORLEVEL 2 DOSSHELL

  Here, the DOSSHELL command is executed when an errorlevel of 2 or greater is
returned.  So, if the errorlevel is equal to 3 or 4 or 5, on up, the DOSSHELL 
command is executed.  That's probably not what you want.
  To ensure that the proper errorlevel value is found, you can use the follow-
ing batch-file statement:

    IF ERRORLEVEL X IF NOT ERRORLEVEL X+1 command

  This statement executes the command when an errorlevel value of X is 
returned -- no more, no less.


  Perhaps the handiest feature of the GETKEY command is its timeout function.
This lets your batch files proceed with automatic selections when the user is
too pokey to type them.  Here is an example using the timeout function:

    GETKEY /C:ABCD /T:C,60 "Your selection "

  If the user doesn't type anything for more than 60 seconds, the computer
selects option C.  GETKEY then generates an errorlevel value of 3, and the 
batch file continues. This works because of GETKEY's /T switch.  The /T switch
is followed by a colon, plus the key GETKEY will "press" automatically after
60 seconds of inactivity.  This is really handy.  By using GETKEY with its /T 
timeout in AUTOEXEC.BAT, you can have the computer start up without your 
input, for example after a power blackout or if you reset but don't want to 
sit, watch, and provide information while the computer starts up.

  An interesting side effect of the /T switch is that you can use GETKEY to 
insert deliberate pauses into your batch files.  For example, employing the
command in this format:

      GETKEY /T:Y,60 /N

uses the /T switch to insert a 60-second pause into a batch file.  You could 
use this line after a message display instead of the PAUSE command with its
boring "Press any key" message.  With GETKEY, the pause is brief, and the 
program continues "automatically."  The /N switch suppresses the prompt and
because no text was specified, you will have a blank line on the screen.

  To make your screen more colorful use GETKEY's /D switch.  For example, to
make a blue background with yellow foreground and white highlighted letters
use the following format:

      GETKEY /D:1,14,15 "Your selection "

  Valid color values are shown in the table below.

              ͻ
                  Background         Foreground/Highlight  
              Ķ
                 Black         0      Black          0     
                 Blue          1      Blue           1     
                 Green         2      Green          2     
                 Cyan          3      Cyan           3     
                 Red           4      Red            4     
                 Magenta       5      Magenta        5     
                 Brown         6      Brown          6     
                 Light Gray    7      Light Gray     7     
                                      Dark Gray      8     
                                      Light Blue     9     
                                      Light Green   10     
                                      Light Cyan    11     
                                      Light Red     12     
                                      Light Magenta 13     
                                      Yellow        14     
                                      White         15     
                                      Blink        128     
              ͼ

    Add 128 to foreground or highlight to create blink i.e. for blinking
yellow highlight use /d,,142.

  Now, you are probably asking, where do the highlighted letters come into 
play?  That's the biggest part that MicroSoft(R) left out! Simply by using 
GETKEY's menu switch /M, you can have the key character you want the user to
press for selecting the menu item.  You can have as many /M switches as you 
have command line room for, and with DOS, remember that is 255.
  The syntax for the menu switch is:

      GETKEY /M"~Windows" /M"~DOS Shell" /M"~Command line"

The '~' tells GETKEY the following character is to be a highlighted character.
The output would appear as below:

Command line
DOS Shell
Windows

[C,D,W] ?

because the program sorts the menu items before displaying them.  Because of 
this be sure to test your batch files without testing for ERRORLEVEL to see 
what order the menu will display.  (Menu order affects the order of valid 
keys!)  Also remember the tilde character falls after lower case letters in
the ASCII character set, so if you use the following command:

    
GETKEY /M"~Windows" /M"C~opy a file" /M"~Command line"

this would be your output:

Copy a file
Command line
Windows

[O,C,W] ?

not this:

Command line
Copy a file
Windows

[C,O,W] ?

Also, you can have more than one valid key per menu item:

    GETKEY -m"~1. ~Windows" -m"~2. C~opy a file" -m"~3. ~Command line" 

1. Windows
2. Copy a file
3. Command line

[1,W,2,O,3,C] ?

just be sure to use:

    IF ERRORLEVEL x IF NOT ERRORLEVEL x+2 GOTO command

  The other change in the /M switch is placing menus on screen locations:

GETKEY "Your selection " -m5,5"~1. ~Windows" -m5,6"~2. C~opy a file" -m5,7"~3. ~Command line" /s

(screen line #4 y coordinate) 
    1. Windows
    2. Copy a file
    3. Command line
    ^ (row #5 x coordinate)
Your selection [1,W,2,o,3,C] ? 
    
  Because the program sorts the menu items before displaying them, test your
batch file without "IF ERRORLEVEL x IF NOT ERRORLEVEL x GOTO command" lines
so you can see what order they will be displayed, also, be sure not to use 
the /n switch so you can see the order of the selection keys.  

  The /f switch looks for the file named and reads the arguments listed.  The
file format is simple one argument per line.  You cannot use the /f switch
in the file.

(Sample file listing.)
"Your selection " 
-m5,5"~1. ~Windows" 
-m5,6"~2. C~opy a file" 
-m5,7"~3. ~Command line" 
/s

  There are nine batch files demonstrating how you could use GETKEY in your 
batch files.  Good luck.
