Dynamic Music Station

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

/ Dynamic Music Station / MUSIC_SOUND.iso / zip / misc / ben300.exe / BEN.HLP < prev next >

Wrap

Text File | 1992-07-15 | 24.0 KB | 683 lines

BEN, the Batch ENhancer, is an utility that specializes in enhancing batch files. It can incorporate colors, sounds, menus, pop-up boxes and a host of other spectacular features into any batch file that you ever write. BEN's functions are so easy to use that even a beginner batch-maker can build attractive batch files in no time at all. Experts will also appreciate BEN's powerful features, such as the directory display controls and the menuing function. To see an example of what BEN can do for you, run the included BENDEMO.BAT. Remember to keep in mind that BENDEMO.BAT is only a batch file! Advantages of BEN over other batch file enhancement programs: - Large number of powerful functions (38 in total) all contained into one EXE file. - All of these functions are very easy to use. - Comes with BENEdit, a text editor that is tailored for BEN. With BENEdit, you can edit all your batch files and access all the features of BEN quickly and easily. - Optimized for speed. - Perfect for complementing any menuing system (eg. Magik Menu). - Can be used for programming any batch utilities (eg. INSTALL.BAT). - Compatible with DOS and Windows. - Compatible with the network environment. You can now use BEN to program all the network batch files! ─────────────────────────────────────────────────────────────────────────── Format: [d:][pathname] BEN function [params] [functions [params]...] Some of BEN's functions doesn't require any parameter. An example of this is the BEEP function. You can use it by entering this command into your batch file: BEN BEEP Other functions of BEN require one or more parameters. For example, you can clear the screen with the color blue by entering this command into your batch file: BEN CLS BLUE BEN functions can be "stacked" one after another in a command line. For example, you can group the BEEP function and the CLS function together, one after another. In this case, BEN will first create a beep, then it will clear the screen with the color blue: BEN BEEP CLS BLUE When you stack functions together, you may use the "/" separators if you want. This is not mandatory, but it helps to increase the readability of your batch file. For example: BEN BEEP / CLS BLUE ─────────────────────────────────────────────────────────────────────────── ASK options BEEP BOX x1 y1 x2 y2 foreground background borderstyle CLEANUP CLS background COLOR foreground background CURSOR ON/OFF/FULL/HALF DELAY milliseconds DIRDISP directory DIRDISPA directory filemask sortorder returnstring ECHO message [message...] EGAVGA ON/OFF EXTRACT source part FLUSH GETCD GETKEY GETKEYU GETLINE GETLINEU GETVIDEO GROWFILLEDBOX x1 y1 x2 y2 foreground background borderstyle LIST filename title LOCATE x y MENU title choice1 [choice2 choice3...] MESSAGE line1 [line2 line3...] PAUSE PLAY playstring SAVEPATH SCROLL x1 y1 x2 y2 direction SHADFILLEDBOX x1 y1 x2 y2 foreground background borderstyle SHELL SOUND frequency duration T filename TITLEDBOX x1 y1 x2 y2 foreground background borderstyle title TRANSPARENTBOX x1 y1 x2 y2 foreground background WRITE foreground background message WRITEC foreground background message WRITEV x y foreground background message ─────────────────────────────────────────────────────────────────────────── BOX FUNCTIONS ───────────── BOX x1 y1 x2 y2 foreground background borderstyle Draws an empty box with an upper-left corner of (x1,y1) and a lower- right corner of (x2,y2). Borderstyle can be one of the following: 0 - no border 1 - single line box (─) 2 - double line box (═) 3 - double sides, single top and bottom 4 - single sides, double top and bottom 5 - single left and upper, double lower and right 6 - menu box style 7+ - the border is drawn using the ASCII character represented by the style value. The available "colors" are BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY, DARKGRAY, LIGHTBLUE, LIGHTGREEN, LIGHTCYAN, LIGHTRED, LIGHT MAGENTA, YELLOW, and WHITE. Examples: BEN BOX 1 1 80 25 WHITE BLUE 1 BEN BOX 10 10 20 20 YELLOW BLACK 3 FILLEDBOX x1 y1 x2 y2 foreground background borderstyle Same as BOX, but the box is filled instead of empty. Examples: BEN FILLEDBOX 1 1 80 25 WHITE BLUE 1 BEN FILLEDBOX 10 10 20 20 YELLOW BLACK 3 GROWFILLEDBOX x1 y1 x2 y2 foreground background borderstyle Same as FILLEDBOX, but the box "grows" out onto the screen, creating a spectacular effect. Examples: BEN GROWFILLEDBOX 1 1 80 25 WHITE BLUE 1 BEN GROWFILLEDBOX 10 10 20 20 YELLOW BLACK 3 SHADFILLEDBOX x1 y1 x2 y2 foreground background borderstyle Same as FILLEDBOX, but the box has a shadow. Examples: BEN SHADFILLEDBOX 1 1 80 25 WHITE BLUE 1 BEN SHADFILLEDBOX 10 10 20 20 YELLOW BLACK 3 TITLEDBOX x1 y1 x2 y2 foreground background borderstyle title Same as FILLEDBOX, but the box has a title. Please note that tildes (~) in the title are interpreted as spaces. Examples: BEN TITLEDBOX 1 1 80 25 WHITE BLUE 1 This~is~a~great~box! BEN TITLEDBOX 10 10 20 20 YELLOW BLACK 3 Another~box! TRANSPARENTBOX x1 y1 x2 y2 foreground background Paints the area specified by (x1,y1) - (x2,y2) with the specified foreground and background colors. Text that are originally on the screen are not erased; they are just painted with a new color. Please note that the borderstyle parameter is not required. Examples: BEN TRANSPARENTBOX 1 1 80 25 WHITE BLUE BEN TRANSPARENTBOX 10 10 20 20 YELLOW BLACK INPUT FUNCTIONS ─────────────── ASK options Waits for the user to press a key that is contained in the 'options' string. The option that the user selects is passed to the batch file as an errorlevel. For instance, if the options string is ABCDE and the user presses the letter C on the keyboard, an errorlevel of 3 is returned (C is the third character of the string). Example: BEN ECHO Please press A, B, or C. BEN ASK ABC IF ERRORLEVEL 3 IF NOT ERRORLEVEL 4 ECHO You pressed "C"! IF ERRORLEVEL 2 IF NOT ERRORLEVEL 3 ECHO You pressed "B"! IF ERRORLEVEL 1 IF NOT ERRORLEVEL 2 ECHO You pressed "A"! GETKEY Waits for the user to enter a key. This key is returned via the environment variable %BEN% (or %BEN2%, %BEN3%, etc. Please refer to the section called "BEN and Environment Variables" at the end of this help file for further details.) Example: BEN GETKEY BEN ECHO You've pressed the %BEN% key! GETKEYU Same as GETKEYU, but the key is converted into uppercase before it is returned. Example: BEN GETKEYU BEN ECHO You've pressed the %BEN% key! (Uppercased) GETLINE Waits for the user to enter a string. This string is returned via the environment variable %BEN% (or %BEN2%, %BEN3%, etc. Please refer to the section called "BEN and Environment Variables" at the end of this help file for further details.) Example: BEN ECHO What's your name? BEN GETLINE BEN ECHO So your name is %BEN%! GETLINEU Same as GETLINE, but the string is converted into uppercase before it is returned. Example: BEN ECHO What's your name? BEN GETLINEU BEN ECHO So your name is %BEN% in uppercase! MENU title choice1 [choice2 choice3...] Displays a menu on the screen. The choice that is selected by the user is passed back to the batch file as an errorlevel. For instance, if the user chooses choice #3, an errorlevel of 3 is returned. On the other hand, if the user opts to choose nothing, then an errorlevel of 0 is returned. Please note that tildes (~) are interpreted as spaces, and no other function can be stacked after the MENU function is used. Also, use a minus sign (-) to tell BEN to display a blank line. Examples: BEN MENU My~Game~Menu Sim~City Wing~Commander BEN MENU Network~Utilities PCONSOLE SYSCON - Log~Out MESSAGE FUNCTIONS ───────────────── ECHO message [message...] Works like the DOS ECHO function. Everything after the word ECHO is displayed using the current writing color. Thus, no other functions can be stacked after ECHO is used. If you wish to display a blank line, use the command "BEN ECHO ~". If you wish to display more than one space between two words, use the tilde (~) as a separator instead. For example, if you want to display the words "Hello World, this is the computer speaking.", use the command "BEN ECHO Hello~~~World, this is the computer speaking." Examples: BEN ECHO Hello World! BEN ECHO This is a test! BEN ECHO ~ BEN ECHO Hello~~~World, this is the computer speaking. LIST filename title Acts as a file browser for the file specified by "filename". Tildes (~) in the title are interpreted as spaces. Examples: BEN LIST C:\AUTOEXEC.BAT This~is~your~AUTOEXEC! BEN LIST BEN.TXT You~are~reading~BEN.TXT! MESSAGE line1 [line2 line3...] Pops up a message box onto the screen. Tildes (~) are interpreted as spaces. Example: BEN MESSAGE Hello~World! This~is~a~test! WRITE foreground background message Writes a string onto the screen using the specified foreground and background colors. Tildes (~) in the message are interpreted as spaces, and a semi-colon (;) at the end of the message tells BEN not to wrap to the next line. Examples: BEN WRITE LIGHTRED BLUE Hello~World! BEN WRITE LIGHTGREEN BLACK This~is~a~test!; WRITEC foreground background message Same as WRITE, but the message is centered between the two sides of the monitor. Examples: BEN WRITEC YELLOW CYAN Hello~World! BEN WRITEC LIGHTGREEN BLACK This~is~a~test!; WRITEV x y foreground background message Same as WRITE, but the message is written as a vertical column that starts from the position (x,y). Examples: BEN WRITEV 1 1 YELLOW BLUE An~important~message BEN WRITEV 40 10 LIGHTCYAN BLACK Hello! BEN WRITEV 80 1 7 1 Great!!! MUSIC FUNCTIONS ─────────────── BEEP Creates a beep sound. Example: BEN BEEP PLAY playstring Plays music using the computer's speaker. The playstring is exactly the same in format as the BASIC PLAY statement. Please refer to BEN.TXT for a complete discussion. Examples: BEN PLAY O5CDEFGFEDCP1CC BEN PLAY ]EEEC SOUND frequency duration Uses the computer's speaker to produce a tone with the specified frequency for the specified duration. Frequency is measured in hertz and duration is measured in milliseconds. Examples: BEN SOUND 1000 1000 BEN SOUND 2000 100 SCREEN FUNCTIONS ──────────────── CLS background Clears the screen with the specified color. Examples: BEN CLS BLUE BEN CLS GREEN COLOR foreground background Changes the current writing color. ANSI.SYS must be loaded for this function to operate. Examples: BEN COLOR YELLOW BLUE BEN COLOR WHITE RED CURSOR ON/OFF/FULL/HALF Changes the cursor shape. Use ON for a normal cursor, OFF for no cursor, FULL for a block cursor and HALF for a half-block cursor. Examples: BEN CURSOR OFF BEN CURSOR FULL EGAVGA ON/OFF Switches the EGA 43 / VGA 50 line mode on or off. If the EGA 43 / VGA 50 line mode is switched on successfully, an errorlevel of 2 is passed back to the batch file. Otherwise, an errorlevel of 1 is returned. Example: BEN EGAVGA ON IF ERRORLEVEL 2 IF NOT ERRORLEVEL 3 ECHO Success! IF ERRORLEVEL 1 IF NOT ERRORLEVEL 2 ECHO Failure! BEN PAUSE EGAVGA OFF GETVIDEO Finds out what kind of video system is installed and returns the result via %BEN% (or %BEN2%, %BEN3%, etc. Please refer to the section called "BEN and Environment Variables" at the end of this help file for further details.) The possible values that can be returned are as follows: MONO: The computer has a monochrome system. CGA: The computer has a CGA system. EGA: The computer has an EGA system. MCGA: The computer has a MCGA system. VGA: The computer has a VGA system. Example: BEN GETVIDEO IF "%BEN%"=="VGA" BEN ECHO You've got a VGA card! LOCATE x y Moves the screen cursor to the position (x,y). Examples: BEN LOCATE 1 1 BEN LOCATE 10 15 SCROLL x1 y1 x2 y2 direction Scrolls the text enclosed in the (x1,y1)-(x2,y2) box. 'Direction' can be one of the following: UP, DOWN, LEFT, RIGHT. Examples: BEN SCROLL 1 1 80 25 UP BEN SCROLL 10 10 20 20 LEFT MISCELLANEOUS FUNCTIONS ─────────────────────── CLEANUP This function should be called at the end of batch files. It does four things: 1. Changes the writing color to normal DOS color (same as calling BEN COLOR LIGHTGRAY BLACK). 2. Changes the cursor to a normal shape (same as calling BEN CURSOR ON). 3. Erases all the environment variables that have been created by BEN (IE. %BEN%, %BEN2%, %BEN3%, etc.) 4. Restores the PATH if the SAVEPATH function had been called previously. (Please refer to the discussion on the SAVEPATH function.) Example: BEN CLEANUP DELAY milliseconds Pauses the computer for the specified number of milliseconds. (1000 milliseconds = 1 second) Examples: BEN DELAY 1000 BEN DELAY 5000 DIRDISP directory Displays a file selection box and allows the user to select a file. The name of the selected file is stored into %BEN% (or %BEN2%, %BEN3%, etc. Please refer to the section called "BEN and Environment Variables" at the end of this help file for further details.) If the user presses ESC and opts not to choose any file, then %BEN% is set to contain nothing. Example: BEN DIRDISP C:\ IF "%BEN%"=="" GOTO CHOSE_NOTHING BEN ECHO You've chosen %BEN%! GOTO END :CHOSE_NOTHING BEN ECHO You didn't choose any file! :END DIRDISPA directory filemask sortorder This is the advanced version of DIRDISP. In addition to the starting directory, you can specify the file mask and the sorting order. 'Filemask' specifies the types of file you want to display. For example, if you want to display only EXE files, you can use a filemask of "*.EXE". If you want to display both EXE and COM files, you can use a filemask of "*.EXE~*.COM" [different types of files are separated with tildes (~).] 'Sortorder' specifies the order which DIRDISPA uses to display the files. It can be one of the following: NAME - Files sorted on names in ascending order. EXTENSION - Files sorted on extensions in ascending order. TIME - Files sorted on time from the earliest to the latest. SIZE - Files sorted on size from the smallest to the largest. X - Files are unsorted. Example: BEN DIRDISPA C:\ *.BAT~*.SYS~*.EXE EXTENSION BEN ECHO You've picked the file %BEN%! EXTRACT source part This is a function that extracts a certain part of a fully qualified filename (eg. the result from DIRDISP or GETCD) and stores it into %BEN% (or %BEN2%, %BEN3%, etc. Please refer to the section called "BEN and Environment Variables" at the end of this help file for further details.) 'Source' specifies the source string from which you want to extract information. Usually, you should place an environment variable here. 'Part' specifies the part of the selected filename you want BEN to return to you. It can be one of the following: DRIVE - Returns only the drive part of the source (eg. C:) PATH - Returns only the path part of the source (eg. \) NAME - Returns only the name part of the source (eg. AUTOEXEC) EXTENSION - Returns only the extension part of the source (eg. BAT) FILENAME - Returns both the name and the extension part of the source (eg. AUTOEXEC.BAT) Example: BEN DIRDISP C:\ BEN EXTRACT %BEN% EXTENSION BEN ECHO You've selected a file with an extension of %BEN%! FLUSH Clears the keyboard buffer. Example: BEN FLUSH GETCD Finds out what the current directory is and stores it into %BEN% (or %BEN2%, %BEN3%, etc. Please refer to the section called "BEN and Environment Variables" at the end of this help file for further details.) Example: BEN GETCD BEN ECHO Hey man, you're in the %BEN% directory right now! PAUSE Pauses the computer until the user presses a key. Example: BEN PAUSE SAVEPATH Saves the PATH environment variable into a file called SAVEPATH.DAT and erases the PATH environment variable. Using this function can free up environment space so that BEN functions that make use of the environment (eg. GETLINE) can function better. Remember to use the CLEANUP function to restore the PATH upon the completion of the batch file. Caution: Make sure that you don't change directory after using SAVEPATH. If you do, you must change back to the directory where SAVEPATH stores SAVEPATH.DAT before you run CLEANUP. Example: @ECHO OFF BEN SAVEPATH BEN ECHO Your PATH has been saved! BEN CLEANUP BEN ECHO Your PATH is restored! SHELL "Jumps to DOS". After this function is used, the user can work in DOS as long as he/she want. He/she can let the batch file regain control by typing EXIT. Example: BEN SHELL T filename Runs all the instructions in the data file. This lets BEN perform its jobs at a quicker speed. Please refer to BEN.TXT for a complete discussion. Examples: BEN T MYFILE.DAT BEN T C:\BATCH\INSTRUCT ─────────────────────────────────────────────────────────────────────────── BEN and environment variables ───────────────────────────── Several of BEN's functions (IE. GETKEY, GETKEYU, GETLINE, GETLINEU, DIRDISP, DIRDISPA, EXTRACT, GETCD and GETVIDEO) return their results using environment variables. After you use any one of these functions, you can access the data that BEN returns by calling the variable %BEN%. Just put %BEN% in your batch file where you want the data to appear. For example, if you want to get the user's name and re-display it, you can do the following: BEN WRITE White Black Please~enter~your~name:~; GETLINE BEN WRITE White Black Your~name~is~%BEN%! If you stack several functions that return data via environment variables, the first result would be stored into %BEN%, the second result into %BEN2%, the third into %BEN3%, and so on. For example, if you want to ask the user to enter two favorite colors and re-display them, you can do the following: BEN WRITE White Black Enter~your~two~favorite~colors: BEN GETLINE GETLINE BEN WRITE White Black So~they~are:~%BEN%~and~%BEN2%! Note: At the end of your batch file, you should make a call to BEN's CLEANUP function to erase all the variables that BEN have created (IE %BEN%, %BEN2%, %BEN3%, etc.) ─────────────────────────────────────────────────────────────────────────── Shareware Registration ────────────────────── BEN is NOT free software. BEN is NOT public domain software. BEN is shareware: you are expected to pay a registration fee to the author of this program if you find it useful. You are allowed to use BEN for free within a trial period of 60 days. After 60 days, if you continue to use BEN, you must register. There are three editions of BEN available for registration: A> Personal Edition - $39 With registration, you get the following: - Complete BEN package on a disk: - BEN.EXE with your specified registration name encoded into the code. - BENMOUSE.EXE (a bonus version of BEN that has the ability to make use of mouses) with your specified registration name encoded into the code. - BENEDIT.EXE with your specified registration name encoded into the code. - All other BEN-related files. - Next version of the complete BEN package on a disk free of charge. - One printed manual that covers all aspects of BEN. - Free technical support. B> Programmer's Edition - $99 With registration, you get the following: - Complete BEN package on a disk: - BEN.EXE with your specified registration name encoded into the code. - BENMOUSE.EXE (a bonus version of BEN that has the ability to make use of mouses) with your specified registration name encoded into the code. - BENEDIT.EXE with your specified registration name encoded into the code. - All other BEN-related files. - Next version of the complete BEN package on a disk free of charge. - One printed manual that covers all aspects of BEN. - A distribution license. With this license, you are permitted to use BEN to create batch utilities that you can distribute, royalty-free. - Free technical support. C> Business Edition - $199 With registration, you get the following: - Complete BEN package on a disk: - BEN.EXE with your specified registration name encoded into the code. - BENMOUSE.EXE (a bonus version of BEN that has the ability to make use of mouses) with your specified registration name encoded into the code. - BENEDIT.EXE with your specified registration name encoded into the code. - All other BEN-related files. - All future versions of the complete BEN package on a disk free of charge. - Five sets of printed manuals that covers all aspects of BEN. - A site license for unlimited number of users on a LAN. - A distribution license. With this license, you are permitted to use BEN to create batch utilities that you can distribute, royalty-free. - Free technical support. To order, please send $39, $99 or $199 (depending on which edition you want) + $5 Postage/Handling to the following address: Simon Lee 7905 Bayview Ave. Unit 1019 Thornhill Ontario Canada L3T 7N3 Notes: - Do specify the registration name (eg. Mr. Bill Smith, ABC Company). - Do specify the size of the disk you want (IE. 5.25" or 3.5") - Pay in cash or cheque. - Make all cheques payable to Simon Lee. - Pay in Canadian currency if ordered from Canada. Pay in US currency if ordered from US or other countries. * You can simplify the registration process by selecting the "Register" option under the system menu in BENEdit.