August 15, 1993 GETKEY ver. 1.5.1 by Matthew G. Moody 206 Waterwood Dr. Goose Creek, SC 29445 (803) 572-4868 CIS 72607,3461 This is my sixth 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. This minor revision solves the bug 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. 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] 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. "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] ? There are eight batch files demonstrating how you could use GETKEY in your batch files. Good luck.