Simtel MSDOS 1992 September

home *** CD-ROM | disk | FTP | other *** search

/ Simtel MSDOS 1992 September / Simtel20_Sept92.cdr / msdos / batutl / batkit50.arc / BATKIT.DOC < prev next >

Wrap

Text File | 1988-08-23 | 33KB | 700 lines

BatKit Utilities for Menus in Batch Files by Ken Hipple [74076,2331] All Right Reserved [Including: GetKey, SaveDir, and Wait] Copyright 1988 by Mississippi Data Equipment Company, Inc. 625C Lakeland East Drive Jackson, MS 39208 (601) 932-6332 BatKit ver. 5.0 7/15/88 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 Response Editing COMMAND LINE PARAMETERS . . . . . . . . . . . . . . . . . . . . . 5 DISPLAYING TEXT . . . . . . . . . . . . . . . . . . . . . . . . . 8 # control character @ control character GETKEY 4.x AND GETSTRNG COMPATIBILITY . . . . . . . . . . . . . . . 11 WAIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 SAVEDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 USING THE DOS ENVIRONMENT . . . . . . . . . . . . . . . . . . . . . 14 REGISTERING BatKit . . . . . . . . . . . . . . . . . . . . . . . . 15 BatKit ver. 5.0 7/15/88 Page: 3 GETKEY OVERVIEW: GetKey is a utility program designed to be used in a batch file. Its main function is to make batch files interactive by allowing the user to enter a response to a prompt or question. Used with an appropriate text file and batch file it can be the basis of a menu system. Other uses include displaying text files and messages, playing tones, clearing screens larger than 80x25, and providing a 'hidden' escape method from a batch file. GetKey enables you to use a single batch (BAT) file and a single text file to completely control the operation of a system from startup to shutdown. GetKey has been tested with DOS versions from 2.1 to 3.3. It will run on most IBM PCs and compatibles. 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 - Limited screen mode switching - Tone generation capabilities - Optional response validation - Adjustable max. response length - Can trim spaces from response - Option to force uppercase - Defaults can be modified BatKit ver. 5.0 7/15/88 Page: 4 USING GETKEY: When GetKey is run it first displays any file or message specified, then waits for the user to enter a response. You can specify the maximum length allowed. After the response is entered it is validated if necessary. The ASCII value of the first letter of the response is then returned to the batch file in ERRORLEVEL. The response can also be placed into the environment if you want. The values returned by func- tion keys are their extended ASCII value 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 Usage: GetKey [?] [/A] [/B] [/C] [/D] [/E] [/F"filename[@s]"] [/G["char"]] [/H] [/I] [/K"chars" | /KF"filename[@s]"] [/Lnnn] [/M"msg"] [/N["char"]] [/O] [/P] [/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 para- meters 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, to GetKey &A0 is the same as 160. Arguments enclosed in quotes (") above MUST be enclosed in quotes on the command line. Response Editing: The following keys can be used during response entry for editing: Home - Returns 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 one space to the left. Right Arrow - Moves the cursor one space to the right. Ins - Toggles Insert/Overstrike mode. Insert mode is indicated by a large cursor. 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.0 7/15/88 Page: 5 COMMAND LINE PARAMETERS for GetKey: (The value in [] after some defini- tions is the "initial" default for that parameter. That is, the action for that parameter if the switch is not included in the command line. If the default is [off], the switch would change it to ON. Most of these initial defaults can be changed by using the /O switch to patch GETKEY.EXE. Toggles can also be forced ON or OFF using + or -.) /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] /C - Toggles the Clear screen setting. If no color setting has been done the original screen colors or attributes are used; otherwise the last color that was set is used. 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] /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 length of the maximum acceptable 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. (also use ?) /I - Toggles the 'Incompatible display adapter' setting. When ON it forces GetKey to use 80x25 screen. (Known to be needed for some AT&T adapters.) [off] /K - Makes the list of characters entered ("chars") be the only accep- table 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 respon- ses 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 BatKit ver. 5.0 7/15/88 Page: 6 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 the keys 1, 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/line feed. This is the format pro- duced by EDLIN or by doing 'COPY CON filename'. Most word pro- cessing packages have an option to produce this type file also. Be careful when using this or the /K option. It is very easy to get 'trapped'. For example, your response file doesn't 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] /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, /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 sett- ing's default, your batch file might stop working. /P - Prevents (disables) GetKey snow checking on CGA monitors. This will speed up screen displays, so if your CGA adapter doesn't produce 'snow', or you don't mind it, use this option or set it 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] /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] BatKit ver. 5.0 7/15/88 Page: 7 /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 continu- ing. If no response is entered before the wait period is up, an ERRORLEVEL of 0 is returned to the batch file. /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 during display delays, tone generation, and text displaying. Text displaying is much slower with checking ON. [off] /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 param- eter. For example, /C+ forces screen clearing ON and /C- forces it OFF. This syntax is safer if you plan on modifying the GetKey default settings using the /O parameter. The toggle syntax provides for a shorter command line entry for those users who plan on sticking with a given GetKey setup and retains compatibility with earlier versions of GetKey. A + or - can be used with /A, /B, /C, /D, /E, /G, /I, /N, /P, /R, /S, /T, /U, /V, /X, and /Z. BatKit ver. 5.0 7/15/88 Page: 8 DISPLAYING TEXT: Using GetKey there are two methods of displaying text. The /M option can be used for short messages or prompts. With this method you can only 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 in which case 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 only need to enter as many digits as you wish. You do not need to pad the argument to its full length with leading zeros but use caution if you don't. The reason is that if you don't use the full length GetKey will misinterpret what you mean if the control sequence is immediately in front of a word starting with A through F (when using hexadecimal) or 0 through 9. Example #&1Apple will be seen as the color combination #&1A followed by the word "pple" instead of the color combination #&1 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 is the background setting and the second is the fore- ground. 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" (GetKey must be able to find the colors file for this to work) at the DOS prompt. To display the # character itself use ## in your message or file. The @ control character is used for various functions. To display the @ character itself use @@. The @ control sequences are: @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 in the form MM/DD/YY, updated as needed. @DT - Displays the Time in the form HH:MM:SS, continuously updated. @DV(var) - Displays the environment Variable named 'var' (e.g. PATH). BatKit ver. 5.0 7/15/88 Page: 9 @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) @Ls - Labels a section as section s, where s is any character. Used with the /F"filename@s" syntax allows you 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). @Mx - Switches screen Modes. x may be 0 through 7 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 some caution since some of the modes won't display text. @O - Returns the screen colors and attributes to the Original start-up values (cursor color when GetKey was executed). @P - Makes GetKey Pause its displaying of text until the user presses a key. The key pressed is discarded. Useful when you want to display more than one screenful 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. @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. Both parameters are optional, however use care when following an @T with a color change (#) command. @T is the equiva- lent of @T2#&400. @Wnnnnn - Causes GetKey to delay (Wait) the displaying of text 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 10 seconds. 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. BatKit ver. 5.0 7/15/88 Page: 10 @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. The text file to display a screen can be created and edited with any ASCII text editor. Most of ours were done with WordPerfect because of it's convenient line drawing feature. However, adding the # param- eters to control colors, etc. can be tedious. We have a utility to add in screen preparation. It will convert a screen image file into a GETKEY text file automatically - MAKESCRN. 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.0 7/15/88 Page: 11 GETKEY 4.x AND GETSTRNG COMPATIBILITY: GetKey 5.0 is highly compatible with pre-5.0 versions of GetKey and GetStrng. 5.0 is a combination of these two programs. As shipped the defaults for 5.0 make it 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 (i.e. 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 don't 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. BatKit ver. 5.0 7/15/88 Page: 12 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 dis- played, and an ERRORLEVEL of 1 is returned. BatKit ver. 5.0 7/15/88 Page: 13 USING SAVEDIR: USAGE: SaveDir [?] [d:][dir] where d: = a valid drive dir = a valid directory ? = display help screens 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 at, 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%'. The advantage to using SaveDir is that you can change drive AND direc- tory with one command instead of the two that DOS requires. Error conditions will set ERRORLEVEL. 1 means there was not enough environment space to insert LDIR. 2 means there was not enough room for LDRV. 3 means the DOS being used is earlier than 2.0. 4 means an invalid directory was entered and 5 means an invalid drive was entered. BatKit ver. 5.0 7/15/88 Page: 14 USING THE DOS ENVIRONMENT: The environment is a section of memory reserved by DOS as a place for information that may change, such as the path. 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 principal 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 160 bytes of memory. Once it is full nothing more can be added unless something else is removed first. If you are using DOS 3.x this is easily overcome by adding a command to the CONFIG.SYS file. For DOS 3.1 use the command 'SHELL=C:\COMMAND.COM /E:paragraphs /P'. For DOS 3.2 and later use 'SHELL=C:\COMMAND.COM /E:bytes /P'. The difference between the two is that DOS 3.1 wants the amount of memory to be reserv- ed to be specified in 16 byte paragraphs and the other 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 with the drive and path to where you do have it (example: D:\DOS\COMMAND.COM). 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 would like 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 PCMAGNET (on CompuServe). A sample of screens captured with GETSCRN and converted with MAKESCRN is included in BATDEMO. BatKit ver. 5.0 7/15/88 Page: 15 REGISTERING BatKit: You may copy and distribute this program freely, as long as all parts of the package are included without modification. This is a shareware (not public domain) program; if you like it and use it on a regular basis please register it. Also, in each case of non-personal use it MUST be registered. Registered owners will receive support and notifi- cation of updates. To register BatKit please send $25 to: Mississippi Data Equipment Co. 625C Lakeland East Drive Jackson, MS 39208 (601) 932-6332 To receive a diskette of other assorted utilities (including GETSCRN and MAKESCRN, a WP 5.0 version of BATKIT.DOC, and the ASM source code for BatKit), send $29 instead of $25. BatKit is distributed without war- ranty, 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, to me on CompuServe (ID# 74076,2331), or to Conrad Smith on CompuServe (ID# 76701,107). Conrad is a sysop on the Javelin forum (GO JAVELIN) and will be able to respond on a more timely basis. He helped develop and test BatKit and suffered through daily changes and fixes, so he knows as much about how it works as I do. 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 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 with valid responses for BATDEMO.BAT BATDEMO.BAT A batch file illustrating uses of GETKEY, WAIT, and SAVEDIR. If you receive BatKit and any of these files are missing, please contact us.