BatKit Utilities for Batch Files by Ken Hipple [72241,65 or 74076,2331] All Rights Reserved [Including: GetKey, SaveDir, Wait, GetScrn, and MakeScrn] Copyright 1988-95, 1996 by Ken Hipple 311 Summer Oak Trail Madison, MS 39110 BatKit ver. 5.7 8/13/96 Page: 2 T A B L E O F C O N T E N T S GETKEY...................................................3 OVERVIEW............................................3 USING GETKEY........................................4 Usage..........................................4 Response Editing...............................4 COMMAND LINE........................................5 DISPLAYING TEXT.....................................11 # control character............................11 @ control character............................11 GETKEY 4.x AND GETSTRNG COMPATIBILITY...............17 WAIT.....................................................18 SAVEDIR..................................................19 GETSCRN..................................................20 USING THE DOS ENVIRONMENT................................21 REGISTERING BatKit.......................................23 DISTRIBUTION NOTICE......................................24 CHANGES SINCE RELEASE 5.0................................25 BatKit ver. 5.7 8/13/96 Page: 3 GETKEY OVERVIEW: GetKey is a utility program designed for use in batch files. Its main function is to make batch files interactive by allowing the user to enter a response to a prompt or question. A menu system can be created by using GetKey, some text files, and some batch files. Other uses include displaying text files or messages, and playing tones. With GetKey you can use a single batch (BAT) file and a single text file to control the operation of a system from startup to shutdown. GetKey has been tested with MS-DOS versions 2.1 through 6.2. Features of GetKey include: - Returns an ERRORLEVEL for all - Option to wait for RETURN key keys including function keys before accepting a response - Option to insert response - Can wait a given time for a into the environment response and then continue - Fast text display & screen - Can display a file, message or handling both - Optional response echoing - Can display a section of a file - Optional bad response message - Flexible color handling - Option to delete bad responses - Time and date display options - Optional beep on bad response - Does display delays and pauses - Built-in help screens - 'Smart' clear screen function - Clear type-ahead buffer option - Screen mode switching - Background tone playing - Optional response validation - Adjustable max. response length - Can trim spaces from response - Option to force uppercase - Defaults can be modified - Screen blanking - Response logging - Share environment variables between DOS sessions under Windows 3.x BatKit ver. 5.7 8/13/96 Page: 4 USING GETKEY: When executed, GetKey displays any file or message specified and then waits for the user to enter a response. You can specify the maximum acceptable response length. Responses can be validated if you desire. The ASCII value of the first letter of the response is returned to the batch file in ERRORLEVEL. The response can also be placed into the environment. Function keys return their extended ASCII values plus 128. These values are: F1-F10 SHIFT F1-F10 CTRL F1-F10 ALT F1-F10 Value Returned: 187-196 212-221 222-231 232-241 F11: 133 135 137 139 F12: 134 136 138 140 (Note: F11 and F12 will not work on some systems) Usage: GetKey ? /A /B /BL[nn]["msg"] /C /D /DF"rsp" /E /F"file[@s]" /G["chr"] /H /I /K"chrs"|/KF"file[@s]" /Lnnn /LG"file" /M"msg" /N["chr"] /O /P /PI /R /S /T /U /V["var"] /Wnnnn /X /Z Items in [] are optional. The character | means or (for example, you can use /K or /KF but not both together). Most parameters can have a + or - appended to them (ex. /B- or /G+"*"). See below for which parameters can use this. Note that any place GetKey expects a number you may enter it in decimal or hexadecimal. To use hexadecimal add a & in front of the number. For example, &A0 is the same as 160. Response Editing: The following edit keys can be used during response entry: Home - Moves the cursor to the first character of the response. End - Moves the cursor to the right end of the response. Left Arrow - Moves the cursor left one space. Right Arrow - Moves the cursor right one space. Ins - Toggles Insert/Overstrike mode. A large cursor indicates Insert mode is active. Del - Deletes the character under the cursor. Backspace - Deletes the character to the left of the cursor. Esc - Deletes the entire response. BatKit ver. 5.7 8/13/96 Page: 5 COMMAND LINE SWITCHES for GetKey: The descriptions below show the default setting for a parameter in brackets ([]). Use a parameter's command line switch to override its default setting. Most of these defaults can be changed by using the /O switch to patch GETKEY.EXE. Many of the parameters are either on or off. Using the parameter's switch will toggle the parameter from its default setting to the opposite setting. You can force these parameters ON or OFF by using + or - after the parameter's switch (i.e. /A+ or /G-). GetKey returns an ERRORLEVEL of 128 if a command line error is encountered. All command line parameters can be specified in the environment by using the environment variable GETKEY. For example, if you enter 'SET GETKEY=/m"This is a test: "' at the DOS prompt then every time you run GetKey the specified message will be displayed. If a parameter is also specified on the command line then that setting will override the setting in the environment. Where a parameter shows quotes being used you can use a colon (:) instead. In some of these places any character may be used. In these cases the character you use in place of the first quote be will become the delimiter. /A - Makes the RETURN key be one of the Acceptable responses for GetKey (see /K and /KF). If not used with the /K|/KF parameter it makes the RETURN key be the only acceptable response. [Off] /B - Toggles the setting for the error Beep produced by an invalid response to GetKey (see /K|/KF) and Ctrl-G beeps. [On] /BL - Toggles screen blanking. If no argument is given blanking will occur after the default time [10]. /BLnn (or /BL=nn) will cause blanking to occur after nn minutes. If nn is 0 blanking will occur after approximately 30 seconds. The default screen saver message is "Press a key to restore screen". You can change this by using /BL'msg' or /Blnn'msg'. msg can use @ display code control sequences. [On] /C - Toggles the Clear screen setting. The screen is cleared using either the original screen colors or the last colors set by GetKey. GetKey determines the original screen colors by looking at the attributes at the cursor position that was current when GetKey was called. This means that the color the cursor is when you invoke GetKey is the color it thinks the screen is. [Off] /D - Toggles the 'Delete (erase) unacceptable response' setting (see /K|/KF). [Off] /DF - The value "rsp" is entered as a default response. BatKit ver. 5.7 8/13/96 Page: 6 /E - Toggles the setting for displaying an Error message when the user enters an unacceptable response (see /K|/KF). [Off] /F - Causes GetKey to display the File "filename". Using the syntax "filename@s" causes GetKey to display only section s of the file. See 'Displaying Text' below for more information. /G - Toggles the setting for a Guide line. When ON, it displays a guide line showing the maximum acceptable length of the response. Use /G"char" to change the character used for the line. The initial default is an underline [_], but this can be changed using the /O option. [Off] /H - Causes the built-in Help screens to be displayed. (same as ?) /I - Toggles the 'Incompatible display adapter' setting. When ON it forces GetKey to use an 80x25 screen. (Known to be needed for some AT&T adapters.) [Off] /K - Makes the list of characters entered ("chars") be the only acceptable Keys for GetKey. GetKey will not continue processing until the user presses one of these keys. Use this option when you are looking for one character responses. For multi-character responses use /KF. When this option is used with responses of length greater than 1 only the first character of the response is checked. For example, if one of the characters in "chars" is a 1 than any response starting with a 1 will be accepted. To make a function key or a character not on the keyboard an acceptable character, enter the appropriate value using the ALT-Numeric Key Pad method. For example, to make F1 an acceptable key, hold down the ALT key, press 1, then 8, and then 7 using the numeric key pad and then release the ALT key. (See /U for case sensitivity) /KF - Makes the responses in the file "filename" the only acceptable responses. Response files can be broken into sections the same as display files using the "filename@s" syntax. Response files must be ASCII text files with each response delimited by a carriage return or a carriage return and line feed. This is the format produced by EDLIN, EDIT or by doing 'COPY CON filename'. Most word processing packages have an option to produce this type of file also. Be careful when using this or the /K option. It is very easy to get 'trapped'. For example, your response file does not have any single character responses in it and you start GetKey without overriding its default maximum response length setting of 1. (See /U for case sensitivity) /L - Sets the maximum allowable Length of the response. nnn can be any value from 0 to 255. A value of 0 means that the user cannot enter any characters. This would make GetKey act similar to the PAUSE command in a batch file. [1] BatKit ver. 5.7 8/13/96 Page: 7 /LG - Toggles GetKey response LoGging. User responses are logged with a time and date stamp to a file. The default log file is C:\GETKEY.LOG. Use "filename" to log to a different file. Example: GETKEY /LG"mylog.dat" /LGC- The normal format for the log file is comma delimited. For example: "05/08/96","12:55:26","Z","F" LGC changes this to a space delimited format: 05/08/96 12:55:26 Z F The field layout is always Date, Time, ID, Response. [On] /LGD- Overrides the default date formatting used in response log files. Use /LGD"" to prevent the date from being logged. The date formatting codes are: M - Logs month as a two digit number A - Logs month using a three letter abbreviation L - Logs month using the full name D - Logs day as a two digit number Y - Logs year as a two digit number C - Logs year as a four digit number Two digit items are logged with leading zeros if the associated code is entered in upper case. If a code is entered in lower case then leading zeros are not logged. Letters or characters entered between date format codes are used as separator characters. A comma is a special case. If a ',' is used as a separator character then ', ' is actually logged. Here is how the date July 4, 1995 would be logged using various date formatting layouts: /LGD'MDY' 07-04-95 /LGD'mdy' 7-4-95 /LGD'm/d/y' 7/4/95 /LGD'L,d c' July, 4 1995 /LGD'A,d c' Jul, 4 1995 /LGD'D-A-C' 04-Jul-1995 /LGD'd-A' 4-Jul /LGD'L C' July 1995 /LGI- Sets an ID string to be logged to the response log file. This can be used to identify responses logged from multiple places. Environment variables can be used if desired. Examples: GetKey /LG/LGI"Question 1" GetKey /LG/LGI"%0" (makes the batch file name the ID) GetKey /LG/LGI"%user%" BatKit ver. 5.7 8/13/96 Page: 8 (makes the env. Variable USER the ID) /LGM- When /W is used with response logging GetKey normally does not log a message if it times out. Use /LGM if you want time outs to be logged. [Off] /LGT- Overrides the default time formatting used in response log files. Use /LGT"" to prevent the time from being logged. The time formatting codes are: H - Logs the hour as a 2 digit number using 24 hour time T - Logs the hour as a 2 digit number using 12 hour time A - Logs the hour as a 2 digit number using 12 hour time with AM or PM added at the end M - Logs the minute as a 2 digit number S - Logs the second as a 2 digit number When codes are entered as upper case leading zeros are logged. If they are entered as lower case then leading zeros are not logged. Letters or characters entered between time format codes are used as separator characters. Here is how the time 15:45:09 would be logged using various time formatting layouts: /LGT'HMS' 15:45:09 /LGT'hms' 15:45:9 /LGT'H.M.S' 15.45.09 /LGT'HM' 15:45 /LGT'TMS' 03:45:09 /LGT'aM' 3:45 PM /M - GetKey displays the Message "msg" on the screen before waiting for the user's response. /N - Toggles GetKey response echoing. Normally, when the user presses a key, that key is displayed (if it is a displayable character). Use /N"char" to change the default 'fill-in' character. For example, if you are using GetKey to enter passwords you might like to use the command /N"*". [On] /O - Change Option's defaults. GetKey's default settings are shown on the first help screen as highlighted fields. You can change these defaults by using the /O option. Items that can be changed are: /B, /BL, /BLnn, /C, /D, /E, /G, /G"char", /I, /L, /N, /N"char", /P, /R, /S, /T, /U, /V, /V"var", /X, and /Z. Be careful about changing defaults once you are using GetKey in several places. If an existing batch file toggles a setting, and you change that setting's default, your batch file might stop working. You must be in the directory where GETKEY.EXE is located when you use this switch. /P - Prevents (disables) GetKey snow checking on CGA monitors. This will speed up screen displays, so if your CGA adapter does not produce 'snow', or you don't mind it, use this option or set it BatKit ver. 5.7 8/13/96 Page: 9 using /O. Actually, this switch toggles the default snow checking setting. If you have a video adapter that GetKey thinks is not a CGA then GetKey automatically turns snow checking off. If this produces 'snow' on your screen you may need to use /P. [Off] /PI - Allow PIping. Use when you want to 'pipe' a response into GetKey. Do not use with /R turned on unless the text to be piped ends with a carriage return. Example: GetKey /PI < RESPOND.TXT GetKey receives input of any text in RESPOND.TXT as if it had been entered from the keyboard. /R - Toggles the 'RETURN key Required' setting. When ON, GetKey will not act on a response until RETURN is pressed. When OFF a response is accepted as soon as the maximum number of characters have been entered. [Off] /S - GetKey can be configured to add a Carriage Return-Line Feed sequence after an accepted response. This option toggles the default setting. [Off] /T - Toggles the 'Trim leading and trailing spaces' function. [On] /U - Toggles the 'force response to UPPERcase' setting. This switch also affects how response checking operates. When Uppercase is ON, response checking is NOT case sensitive. This means that if "Ab" is an acceptable response, a user could enter: "AB", "ab", "Ab", or "aB", and GetKey would accept it. When Uppercase is OFF response checking IS case sensitive. In this case the ONLY acceptable response would be: "Ab". [On] /V - Toggles the 'insert response into the environment' setting. Sets the Variable name to be used to "var". If "var" is not used GetKey uses the default value [GK]. [Off] /W - Tells GetKey to Wait for a given number of seconds before continuing. If no response is entered before the wait period is up, an ERRORLEVEL of 0 is returned to the batch file otherwise ERRORLEVEL is set as it normally would be. /W0 is a special situation. When it is used, GetKey does not wait for a key to be entered. Unless there is a character in the buffer, an ERRORLEVEL of 0 is returned. /X - Toggles GetKey CTRL-BREAK checking. Text displaying is slower with checking ON. When ON a user can break out of GetKey by using CTRL-BREAK. [Off] /Y - When GetKey is run from some DOS shell programs (Such as TREE86 or HOT) it can not find the environment (see /V) using its normal method. This switch can be used to correct this problem in some cases. For example, if you are using TREE86 try using /Y"TREE86" if you are having a problem getting the /V option working. With DOS version 4.0 and later you will probably need to SET the BatKit ver. 5.7 8/13/96 Page: 10 environment variable you will be using before you start the program specified. /YM - If GetKey is being run from a DOS 'shell' (such as some program's 'Go to DOS' feature) then normally GetKey will only affect the environment (see /V) of the program it is running under. This switch tells GetKey to also make any changes to the main (or root) environment. /YW - THIS OPTION DOES NOT WORK UNDER WINDOWS 95. If GetKey is being run in a DOS session under Windows then normally the /V switch only affects the environment for the current DOS session. This switch tells GetKey to also make changes to the main Windows environment. Any DOS sessions started under Windows after this will contain the changes. This provides a somewhat crude method of communicating between DOS sessions. If you plan on using this feature you will probably want to pre-load the environment before starting Windows. This is to make sure there is environment space available. For example, the last two lines of your AUTOEXEC.BAT might look like this: SET GK=This is here to reserve space in the environment WIN This feature will only work under DOS versions 4.0 and later. /Z - Toggles the 'clear (Zap) the type-ahead buffer' function in GetKey. [Off] +|- - The above options that toggle a setting can also be used to force the setting ON or OFF by adding a + (ON) or - (OFF) to the parameter. For example, /C+ forces screen clearing ON and /C- forces it OFF. This syntax is safer if you plan to modify the GetKey default settings using the /O parameter. The toggle syntax provides for a shorter command line entry for users who plan to stick with a given GetKey setup and it retains compatibility with earlier versions of GetKey. A + or - can be used with /A, /B, /C, /D, /E, /G, /I, /LG, /LGC, /LGM, /N, /P, /R, /S, /T, /U, /V, /X, and /Z. BatKit ver. 5.7 8/13/96 Page: 11 DISPLAYING TEXT: GetKey has two methods of displaying text. The /M option can be used for short messages or prompts. With this method you can display as much text as you have room for on the command line. The /F method allows you to display a file so the amount of text you can display is limited only by your disk space. Both methods can be used together. If they are the file is displayed first. With both methods you can perform special functions through the use of # and @ control character sequences. Note that all letters that are used in a control sequence MUST be UPPER case. In the case where the control sequence requires a numeric argument you can enter the argument in decimal or hexadecimal form. To use hexadecimal preface the number with & (ex. &1A). You do not need to pad the argument to its full length with leading zeros. Use caution if you don't because GetKey will use the wrong value if the control sequence is immediately in front of a word starting with 0 through 9 or, if using hexadecimal, A through F. For example, #&1Apple will be seen as the color combination #&1A followed by the word "pple" instead of the color combination #&01 followed by the word Apple. Forcing control sequence letters to be entered as upper case lessens the possibility of this but does not prevent it. The # control character is used specifically for screen color or attribute control. Hexadecimal is convenient to use for colors because the first digit will represent the background setting and the second the foreground. For example, #&10 sets the colors to a foreground color of 0 (black) and the background color to 1 (blue). The syntax is #&hh where &hh is a hexadecimal number. To see all of the 256 possible color/attribute combinations enter GetKey/f"colors" at the DOS prompt. GetKey must be able to find the colors file for this to work. To display the # character use ## in your message or file. The @ control character is used for various functions. To display the @ character use @@. The @ control sequences are: @/d...d - Execute the / command line parameters found between the delimiting characters d. Any command line parameter may be used however the /C, /I, and /? will not have any effect. The /F parameter can cause unexpected results in some cases but in most it will appear to be ignored. Using the /M parameter will display the message one time. If you use @JH this means that when re-displaying the screen after a help message the /M message will not appear. Example: @/~/k"abc"/z/e~ BatKit ver. 5.7 8/13/96 Page: 12 @Bnnnr[#ccc]d...d - Bounce bars. Create bounce bar number nnn which will return response r. The bar will be displayed as the reverse of the existing colors unless a color is specified with #ccc. The character d is the delimiter marking off the text (indicated above as ...) to be included in the bar. d must be a character that is not used in the included text. Example: @B2S#&10\S. Spreadsheets\ This creates the second bounce bar that will return a response of S. The text included in the bar will be 'S. Spreadsheets'. The color used to display the bar will be &10. @BZ - Bounce bar Zap. Clears previously entered bounce bars. Bounce bars are also cleared when a new section is displayed. @C - Clears the screen. This is the same as the /C command line parameter except that it may be used anywhere in the file or message. @CR+ - Turns the CuRsor ON. @CR- - Turns the CuRsor OFF. @DD - Displays the Date using the current country layout (MM-DD- YY for the USA), updated as needed. The display layout can be changed. The date formatting codes are: M - Displays month as a two digit number A - Displays month using a three letter abbreviation L - Displays month using the full name D - Displays day as a two digit number Y - Displays year as a two digit number C - Displays year as a four digit number Two digit items are displayed with leading zeros if the associated code is entered in upper case. If a code is entered in lower case then leading zeros are not displayed. Letters or characters entered between date format codes are used as separator characters. A comma is a special case. If a ',' is used as a separator character then ', ' is actually displayed. Here is how the date July 4, 1995 would display using various date formatting layouts: @DD 07-04-95 (for the US) @DD'MDY' 07-04-95 @DD'mdy' 7-4-95 @DD'm/d/y' 7/4/95 @DD'L,d c' July, 4 1995 @DD'A,d c' Jul, 4 1995 BatKit ver. 5.7 8/13/96 Page: 13 @DD'D-A-C' 04-Jul-1995 @DD'd-A' 4-Jul @DD'L C' July 1995 @DD+ - Turn Display Date function on. Only needed if you've used @DD-. @DD- - Turn Display Date function off. This is only useful if you display text on top of an area where the date is being displayed. The date may show through in this situation unless you use @DD-. @DT - Displays the Time using the current country layout (HH:MM:SS for most places), updated continuously. The display layout can be changed. The time formatting codes are: H - Displays the hour as a 2 digit number using 24 hour time T - Displays the hour as a 2 digit number using 12 hour time A - Displays the hour as a 2 digit number using 12 hour time with AM or PM added at the end M - Displays the minute as a 2 digit number S - Displays the second as a 2 digit number When codes are entered as upper case leading zeros are displayed. If they are entered as lower case then leading zeros are not displayed. Letters or characters entered between time format codes are used as separator characters. Here is how the time 15:45:09 would display using various time formatting layouts: @DT 15:45:09 @DT'HMS' 15:45:09 @DT'hms' 15:45:9 @DT'H.M.S' 15.45.09 @DT'HM' 15:45 @DT'TMS' 03:45:09 @DT'aM' 3:45 PM @DT+ - Turn Display Time function on. Only needed if you've used @DT-. @DT- - Turn Display Time function off. This is only useful if you display text on top of an area where the time is being displayed. The time will show through in this situation unless you use @DT-. @DV(var) - Displays the environment Variable named 'var' (for example, PATH). GetKey will begin displaying the variable at the location where it finds @DV and will stop when the contents of the variable have been completely displayed or at the first non-space character. BatKit ver. 5.7 8/13/96 Page: 14 Example: /M"Path=@DV(path) Date=@DT" The first 10 characters of the PATH will be displayed. @Fnnn - Flashes the screen nnn times. If nnn is not given the default value of 1 is used. @H - Homes the cursor (to upper left corner) without clearing the screen. This parameter can be used to "overlay" screens. (See @X and @Y for other cursor positioning commands) @JH"k1s1[k2s2][k3s3][...]" - Jump to Help. If key kn is pressed then section sn is displayed. GetKey will then wait for a key to be pressed. When one is the section that set up the help keys will be re-displayed. Note that any keys used as help keys can not be included in the response entered by the user. Example: @JH"1A2B" If a 1 is pressed the help screen labeled A is displayed. If a 2 is pressed the help screen labeled B is displayed. @JIs - Jump Immediately to section s and begin displaying the text in that section. @JK"k1s1[k2s2][k3s3][...]" - Jump on Key kn to section sn and begin displaying the text in that section. Example: @JK"1A2B" Wait for a key to be pressed. If the key is a 1 jump to section A. If a 2 is pressed jump to section B. Ignore anything else. @JOs"k1s1[k2s2][k3s3][...]" - Jump on key kn to section sn Otherwise if the key pressed is not in the list then jump to section s. Example: @JOC"1A2B" Wait for a key to be pressed. If the key is a 1 jump to section A. If a 2 is pressed jump to section B. If anything else is pressed jump to section C. @JPs - Jump to section s after Pausing for a key to be pressed. @JWnnns - Jump to section s after a wait delay of nnn clock ticks. There are 18.2 clock ticks per second. @Ls - Labels a section as section s, where s is any character. When used with the /F"filename@s" syntax this allows you BatKit ver. 5.7 8/13/96 Page: 15 to display sections of a file instead of the whole file. GetKey will display all of the file from the start of the given section to the end of the file or the start of the next section. Sections are found very quickly - even those near the end of large files. If a file with sections is displayed using the syntax /F"filename", then the first section is displayed. File sectioning can also be used in the same way for response files. (See /KF). @Mxx - Switches screen Modes. xx may be a number or the letter O. Use the O to return the screen to the mode it was in when GetKey was invoked. Use the command with caution since some of the modes will not display text. Values of xx above 7 should only be used when you know what the results will be. If you try a mode over 7 and your monitor does not support that mode then there is a remote possibility of monitor damage. @MRxx - Set the left MaRgin to xx spaces. Use this command when you want all lines displayed to be indented by xx spaces. @O - Returns the screen colors and attributes to the Original start-up values (the cursor color when GetKey was executed). @P - Makes GetKey Pause text displaying until the user presses a key. The key pressed is discarded. Useful when you want to display more than one screen of text. @R - Set cursor position for Response. Normally, GetKey waits for input wherever the display file (or message) ends. To force the user response to be entered at some other position on the screen, imbed @R at that point in the display file. @Snnn - 'Shifts' the screen's colors. The number entered is added to the current color at each screen position. If nnn is not given the default value of 1 is used. @Tnnn#nnnnn - Generates a Tone. The nnn parameter is the duration. The #nnnnn parameter is the frequency. The higher the number entered for the frequency, the lower the frequency will be. Both parameters are optional, however use care when following an @T with a color change (#) command. @T is the equivalent of @T2#&400. To play a 'rest' use a frequency of 0 (i.e. @T#0). Tones are played in the background. This means text displaying and key entry can be occurring while tones are being played. @TF - Tone Flush. Clears all tones from the tone buffer. @TRnnn[Ttt] - Tone Repeat. Repeat the last tone or the last tt tones nnn times. Up to 128 tones can be repeated. BatKit ver. 5.7 8/13/96 Page: 16 Example: @TR5T10 - repeat the last 10 tones 5 times @Vs["var"] - When a response is entered put the section label s in the environment Variable var. If var is not given GKSECT is used. @Wnnnnn - Causes GetKey to delay (Wait) text displaying for the period nnnnn. The waiting period used is not machine dependent. In other words @W10 will delay the display the same length of time no matter what machine it is being run on. @W18 provides a delay of approximately 1 second. If nnnnn is not given the default value of 18 is used. The maximum value for nnnnn is 65535. @Xddd - Positions the cursor to column ddd or &hh (where the leftmost column is 000). Note that -ddd or +ddd positions the cursor ddd positions to the left or right of the current position (relative positioning). @Yddd - Positions the cursor to row ddd or &hh (where the top row is 000). Note that -ddd or +ddd positions the cursor ddd rows above or below the current position (relative positioning). Text files to be displayed can be created and edited with any ASCII text editor. Most of ours were done with WordPerfect 5.1 because of its convenient line drawing feature. However, adding the # parameters to control color, etc. can be tedious. Included is a utility to aid in screen preparation. MakeScrn will convert a screen image file into a GetKey text file automatically. The screen image must be in the format used by the PC Magazine PAINT program, which can be used for creating screens from scratch. If you have another way of painting screens in color (or want to capture existing screens), you can use our GetScrn program to capture screens to an image file. BatKit ver. 5.7 8/13/96 Page: 17 GETKEY 4.x AND GETSTRNG COMPATIBILITY: GetKey 5.x is highly compatible with pre-5.x versions of GetKey and GetStrng. 5.x is a combination of these two programs. As shipped, the defaults for 5.2 and above make the newer versions work similar to older versions of GetKey. The following is a list of incompatibilities and differences that you need to watch for: - Default number entry is now decimal instead of hexadecimal. It seems a lot of people consider decimal the most natural base to use. A strange way of thinking but I bow to the majority in this case. To adapt existing files just take out the & sign where you have it and put it in where you don't. For example, an existing #&10 should be changed to #10 and an existing #10 should be changed to #&10). If you don't care for that idea use /4 as one of your command line arguments. This changes the default back to hexadecimal. - If you do not force responses to upper-case then lower-case letters will return their lower-case value. As shipped, GetKey defaults to forced uppercase responses. - The /W parameter now lets you enter the waiting period in seconds rather than a code character that was, in some cases, obscure. - The default environment variable (as shipped) is GK. GetStrng users take note. - You can now display things in the bottom right corner of the screen without having the screen scroll. - To allow a SPACE(s) to be entered as a response you will have to turn trimming (/T) off. This only concerns responses consisting of just spaces. Embedded spaces are never removed. - The following keys are now editing keys and will not return a value: Home, End, Left Arrow, Right Arrow, Ins, Del, Esc, and Backspace. If bounce bars are being used then add Up Arrow, Down Arrow, and Spacebar to this list. BatKit ver. 5.7 8/13/96 Page: 18 USING WAIT: USAGE: WAIT [?] [/M] [/C] [/U] [/B] [time] where: ? - displays help screen /M - turns off the waiting until message /C - turns ON the clock display /U - wait until the time given /B - makes delay non-interruptible (CTRL-BREAK is also disabled) time - 6 digits in HHMMSS format. Can be entered in any way desired. Examples: 01:02:03 010203 01 hours 02 minutes 03 seconds Wait provides a way to cause a delay in the processing of a batch file. The delay can be from 1 second to 23 hours 59 minutes and 59 seconds. It may be for an amount of time or until a given time. It can be interruptible or non-interruptible. If it is interruptible, then pressing any key will exit Wait. If no time is entered Wait defaults to approximately 1 second. If an entry error is made, a message is displayed, and an ERRORLEVEL of 1 is returned. BatKit ver. 5.7 8/13/96 Page: 19 USING SAVEDIR: USAGE: SaveDir [?] [d:][dir] [/H] [/L] [/N] where d: = a valid drive dir = a valid directory ? = display help screens /H = display help screens /L = change to the drive and directory saved in LDIR /N = don't save the current drive and directory in LDIR SaveDir places the current drive and directory path into the environment using the variable names LDRV and LDIR. Using the syntax 'SaveDir d:dir' will make SaveDir change to that drive & directory after it has saved the info about the current directory. After SaveDir is run, the command CD %LDIR% can be used by a batch file to return to the directory current when SaveDir was run, and %LDRV% can be used to change to the drive that was current. The following is an outline of a batch file that will save the information about where it is currently, change to a new drive and directory, execute some commands, and then return where it started: SaveDir d:dir . . whatever commands you want . %LDRV% CD %LDIR% Note that the last two lines could be replaced with 'SaveDir %LDIR%'. Another advantage to using SaveDir is that you can change drive AND directory with one command instead of the two that DOS requires. Issuing consecutive 'SaveDir /L' commands will toggle you between two directories. Error conditions will set ERRORLEVEL as follows: 1 = not enough environment space to insert LDIR 2 = not enough environment space to insert LDRV 3 = the DOS being used is earlier than 2.0 4 = an invalid directory was entered 5 = an invalid drive was entered 6 = bad command line parameter entered 7 = LDIR was not found in the environment BatKit ver. 5.7 8/13/96 Page: 20 USING GETSCRN: USAGE: GETSCRN [U] [I] [x] where: U- unloads GetScrn from memory I- forces GetScrn to use a screen size of 80X25. Use this option if GetScrn is not able to determine your screen size. x- any character or number other than U or I. Sets the hotkey to Alt-x. The active hotkey is displayed when GetScrn is started. GetScrn is a text screen capture utility. When the hotkey is pressed GetScrn captures a snapshot of the current screen and saves it to a file. The file name will be SCREENnn.TXT where nn is a number from 00 to 99. GetScrn captures the text and display attributes of the screen. The screen snapshots produced by GetScrn can be used by utilities such as MakeScrn and PC Magazine's PAINT program. BatKit ver. 5.7 8/13/96 Page: 21 USING THE DOS ENVIRONMENT: The environment is a section (or sections) of memory reserved by DOS. Information that may change, such as the path, is stored in it. The information in the environment is stored in the form varname=text where varname is the name of the environment variable and text is the information associated with it. In a batch file you can use varname to access the information. When a batch file encounters the syntax %varname% it replaces it with the information associated with varname. The principle and operation are the same as the %1 through %9 command line arguments that batch files use. If you want to see what you have in your environment enter SET at the DOS prompt. To add something to the environment enter SET varname=text. One problem with using the environment is that it defaults to a small size. Once it is full nothing more can be added unless something else is removed first. If you are using DOS 3.x or later this is easily overcome by adding a command to the CONFIG.SYS file. For DOS 3.1 use the command 'SHELL=C:\COMMAND.COM C:\ /E:paragraphs /P'. For DOS 3.2 and later use 'SHELL=C:\COMMAND.COM C:\ /E:bytes /P'. (Note: These are general examples and may need to be adjusted for your system). The difference between the two is that DOS 3.1 wants the amount of memory to be reserved to be specified in 16 byte paragraphs and the later versions want it specified in bytes. If you have COMMAND.COM located somewhere other than the root directory of drive C: then replace C:\COMMAND.COM and C:\ with the drive and path to where you do have it (example: D:\DOS\COMMAND.COM and D:\DOS). The /P is needed to make AUTOEXEC.BAT execute if it is present. If you are using a DOS version before 3.x it is more difficult to expand the environment. You will need to find one of the programs that modifies COMMAND.COM. You can probably find one on the BBS where you found BatKit or on CompuServe in the IBMNEW or IBMSW forums. GETSCRN and MAKESCRN: If you want to capture screens from other programs for use with GetKey, you can use these utilities. GetScrn will capture any text screen to a file in the PC Magazine PAINT format. This file can then be edited with PAINT and converted to a GetKey screen file by MakeScrn. Although the GetKey screen file can be created or edited by any text editor, it is easier to create or edit screens with boxes, etc. using PAINT, which can be downloaded from PC Magazine's Tips/Utilities Forum (GO ZNT:TIPS) on ZiffNet. A sample of screens captured with GetScrn and converted with MakeScrn is included in BATDEMO. GetScrn and MakeScrn are now included with BatKit. GetScrn is a TSR. Instructions are displayed when it is run. Instructions for MakeScrn are displayed when it is run with one exception. MakeScrn will generate the code for several of the @ display functions. To do this place a @ in the file to be converted at the spot you wish to have one of the @ functions. When MakeScrn converts the file it will stop at each @ in the file and prompt you for which BatKit ver. 5.7 8/13/96 Page: 22 function you want. Note that MakeScrn does not support all of the @ functions. BatKit ver. 5.7 8/13/96 Page: 23 REGISTERING BatKit: You may copy and distribute this program freely, as long as all parts of the package are included without modification. BatKit is a shareware product. If you find it useful after trying it please register it. Registered owners are entitled to receive support and notification of updates. To register BatKit please send $15 to: Ken Hipple 311 Summer Oak Trail Madison, MS 39110 Individuals who are CompuServe members may register on-line. Go to the Shareware Registration area (CIS:SWREG) and follow the instructions. The SWREG ID # for BatKit is 1312. Site License: Site licenses are available for GetKey at the following prices. GetKey site licenses cover use of the other BatKit utilities. 10 license pack $ 95 25 license pack 200 50 license pack 300 Unlimited usage 500 BatKit is distributed without warranty, implied or otherwise. If you have any problems with BatKit or if you have any comments or suggestions please send them to the above address or to me on ZD Net or CompuServe (ID# 72241,65 or 74076,2331). If you distribute BatKit you must include the following files as part of the package: GETKEY.EXE The GetKey program SAVEDIR.COM The SaveDir program WAIT.COM The Wait program GETSCRN.COM The GetScrn program MAKESCRN.EXE The MakeScrn program BATKIT.DOC The BatKit documentation file DEMO.GKF A text file that demonstrates GetKey's features. Used by BATDEMO.BAT or type: GETKEY /f"DEMO.GKF". COLOTONE.GKF A text file that displays all possible tone and color/attribute combinations. COLOTONE.BAT A batch file that uses COLOTONE.GKF COLORS A text file that displays all colors (Use GetKey /F"Colors") MSDEMO.GKF A text file used by BATDEMO.BAT to illustrate screen captures by GetScrn and MakeScrn. MENU.GKF A text file containing menus for BATDEMO.BAT GETKEY.RSP A text file that contains valid responses for BATDEMO.BAT. BatKit ver. 5.7 8/13/96 Page: 24 BATDEMO.BAT A batch file illustrating uses of GetKey, Wait, and SaveDir. DEMO-DOC.BAT A fully documented version of BATDEMO.BAT. ASMENU.GKF A sample menu screen text file README.1ST Getting started and last minute info VENDOR.TXT Information for shareware vendors REGISTER.TXT Registration information FILE_ID.DIZ Description file for BBSs TRAP.GKF Sample music file TRAPINV.GKF Sample music file SAINTS.GKF Sample music file If you receive BatKit and any of these files is missing, please contact the author at the above address or by email. Many thanks go to Conrad Smith for his help in testing, his suggestions, and his help in creating the demo and distribution package. DISTRIBUTION NOTICE VENDORS: ASP approved vendors are allowed to distribute BatKit. Other vendors should contact the author at the above address before beginning to distribute BatKit. BBS operators: BatKit may be uploaded and distributed by any BBS that does not charge a fee for a download. Connect time charges and monthly or yearly flat-rate charges are acceptable. (The above references to BatKit cover the complete BatKit package and the individual files found in the BatKit package.) BatKit ver. 5.7 8/13/96 Page: 25 CHANGES SINCE RELEASE 5.0 Version Change 5.1a Added screen blanking Changed the /W command line parameter so that wait is forced on rather than being toggled Increased accuracy of /W 5.1b Added screen blanking to help and options screens 5.1c Changed file read procedure so that there is no limit to the file size and contents 5.1d Corrected options setting not working after 5.1c change Fixed options setting toggling snow checking on CGA machines Improved snow checking Fixed bad parameter problem when /KF used Fixed problem of numeric arguments being converted wrong if they happened to be split between 2 file reads 5.1e Section labels inside a file were case sensitive. Corrected. BREAK checking changed so it is either off or on. Before it was off only during actual display activity Changed highlight color on options screen 5.1g Fixed display problem when snow-checking on 5.1h Fixed problem with echo_char routine Fixed cosmetic problems on options setting screen Fixed 'hanging' problem during screen blanking on monochrome Fixed 'packed file corrupt' error after options setting 5.1i Fixed 'hanging' problem when @W came after an @P 5.1j Fixed /I not working 5.1k Added /Y"program" so /V could be used with programs like TREE86 & /YM so /V would affect the root environment Fixed parsing problem with /BL argument Added @Fnnn control code to 'flash' screen 5.1l Added default values to @F (1), @S (1), and @W (18). @CR followed by @M caused disappearing cursor - fixed 5.2 Added the following display options: @B, @BZ, @JC, @JH, @JI, @JK, @JO, @JP, @JW, @TF, @TR, @/, and @V Tones are now played in the background. Fixed 'section not found' problem with large files. 5.2a Added GETKEY environment variable for option setting. Fixed GetKey so it would stop thinking that a totally empty environment was actually full. Fixed problem of @/ not always parsing commands correctly and added @/ to the help screens. BatKit ver. 5.7 8/13/96 Page: 26 When using /O the screen blank time and response length values on the help screen were being set to the wrong value when a value larger than the max allowed was entered. Fixed. 5.2b Fixed section labels not being found Fixed problem with @T0 5.2c Snow-checking & bounce-bars together would sometimes cause a crash Added @JH to help screen @/ caused problems with /k -- corrected Changed @M to accept values above 7. 5.2d Forced echo on in options setting screen 5.2e Removed non-existent @JC command from help screen 5.3 Added @DD-, @DD+, @DT-, and @DT+ to allow date and time displays to be turned on and off Added @MR to allow a left margin to be set 5.4 Added 'allow piping' feature (/PI) Fixed problem when using /g with /l0 Fixed 'find master environment' feature Fixed @S parsing problem @V had never been implemented 5.5 Added /YW feature Minor changes to the help screen 5.6 Added /DF to allow a default response to be entered. Changed time and date displaying so fewer interrupt calls would be made. GetKey was using too much CPU power when run in the background & would slow down some things like ArcServe backup. Time & Date displaying was getting done after every keyboard poll. Changed to use INT 1Ch routine. Turned off cursor while screen saver active Added ability to change how date and time are displayed Changed date display to default to country specific layout Added option to /BL to change screen blanking message 5.7 Added response logging features (/LG, /LGC, /LGD, /LGI, /LGM, /LGT) Changed help screen formatting Added /LGC and /LGM to options setting screen