Media Share 9/MEDIASHARE_09.ISO/batch/ben311.zip/BEN.HLP

Text File | 1993-05-15 | 37KB | 1,030 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 (42 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 menu systems.

-    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]...]

Entering the command "BEN" alone in DOS gives you an online help of BEN's
functions. Make sure that the file BEN.HLP is in the same directory as
BEN.EXE. Otherwise, the online help wouldn't work.

To access a BEN function, you must enter the command "BEN" followed by the
name of the function. Some 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 mask
Flush
GetCD
GetKey
GetKeyL
GetKeyU
GetLine
GetLineL
GetLineU
GetVideo
GrowFilledBox x1 y1 x2 y2 foreground background borderstyle
List filename title
Locate x y
Menu title choice1 [choice2 choice3...]
MenuF filename
MenuLCD 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

     This function draws an empty box on the screen 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 "foreground" and "background" colors can be specified
     with special words that BEN recognize. These words are:
     Black, Blue, Green, Cyan, Red, Magenta, Brown, LightGray,
     DarkGray, LightBlue, LightGreen, LightCyan, LightRed, Light
     Magenta, Yellow, and White.

     You can also specify the colors with a number if you want.
     For example, instead of using the word "Black", you can use
     the number 0. Instead of using the word "Blue", you can use
     the number 1. And so on.

     Examples: BEN Box 1 1 80 25 White Blue 1
               BEN Box 10 10 20 20 Yellow Black 3
               BEN Box 4 4 8 8 9 2 65

     In the first example, BEN draws a white on blue box with a
     single-line border, an upper-left corner of (1,1) and a
     lower-right corner of (80,25).

     In the second example, BEN draws a yellow on black box with
     double-lined borders on the sides and single-lined borders
     on the top and the bottom. The box has an upper-left corner
     of (10,10) and a lower-right corner of (20,20).

     In the third example, BEN draws a light-blue on green box
     with a border that is drawn by the ASCII character 65 ("A").
     The box has an upper-left corner of (4,4) and a lower-right
     corner of (8,8).

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
               BEN FilledBox 4 4 8 8 9 9 2 65

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
               BEN GrowFilledBox 4 4 8 8 9 2 65

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
               BEN ShadFilledBox 4 4 8 8 9 2 65

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 Great~box!
               BEN TitledBox 10 10 20 20 Yellow Black 3 Another!
               BEN TitledBox 4 4 8 8 9 2 65 Best~box~here!

TransparentBox x1 y1 x2 y2 foreground background

     Paints the region 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
               BEN TransparentBox 4 4 8 8 9 2


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 more details on
     errorlevels, please refer to your DOS manual.)

     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:  @Echo Off
               BEN Echo A. Format your hard drive.
               BEN Echo B. Diskcopy a disk.
               BEN Echo C. Run Windows.
               BEN Echo D. Run DOSShell.
               BEN Echo E. Play Sim City.
               BEN Echo ~
               BEN Echo Please make your selection.
               BEN Ask ABCDE

               If Errorlevel 5 If Not Errorlevel 6 Goto SimCity
               If Errorlevel 4 If Not Errorlevel 5 DOSShell
               If Errorlevel 3 If Not Errorlevel 4 C:\WIN\WIN
               If Errorlevel 2 If Not Errorlevel 3 DiskCopy A: A:
               If Errorlevel 1 If Not Errorlevel 2 Format C:
               Goto End

               :SimCity
               C:
               CD\SimCity
               SimCity

               :End

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 section 2.3: "BEN and Environment Variables"
     at for further details.)

     Example:  BEN GetKey
               BEN Echo You've pressed the %BEN% key!

GetKeyL

     Same as GetKey, but the key is converted into lowercase
     before it is returned.

     Example:  BEN GetKeyL
               BEN Echo You've pressed the %BEN% key!

GetKeyU

     Same as GetKey, but the key is converted into uppercase
     before it is returned.

     Example:  BEN GetKeyU
               BEN Echo You've pressed the %BEN% key!

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 section 2.3: "BEN and
     Environment Variables" for further details.)

     Example:  BEN Echo What's your name?
               BEN GetLine
               BEN Echo So your name is %BEN%!

GetLineL

     Same as GetLine, but the string is converted into lowercase
     before it is returned.

     Example:  BEN Echo What's your name?
               BEN GetLineL
               BEN Echo So your name is %BEN% in lowercase!

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.

     Example:  @Echo Off
               BEN Menu Please~make~a~selection:
                    Format~your~hard~drive Diskcopy~a~disk
                    Run~Windows Run~DOSShell Play~Simcity - Quit
               If Errorlevel 6 Goto End
               If Errorlevel 5 Goto SimCity
               If Errorlevel 4 Goto DOSShell
               If Errorlevel 3 Goto Windows
               If Errorlevel 2 Goto DiskCopy
               If Errorlevel 1 Goto Format
               BEN Echo You didn't make a selection!
               Goto End

               :Format
               Format C:
               Goto End

               :DiskCopy
               DiskCopy A: A:
               Goto End

               :Windows
               C:\WIN\WIN
               Goto End

               :DOSShell
               DOSShell
               Goto End

               :SimCity
               C:
               CD\SimCity
               SimCity

               :End

     Note:     This example is same in functionality as the
               example that illustrates the Ask function.

MenuF filename

     This function displays a menu created with MDESIGN, the menu
     designer. Please refer to section 4.2 for more details.

MenuLCD title choice1 [choice2 choice3...]

     Same as Menu, except that the menu is displayed in black and
     white for added clarity on LCD screens.

     Example:  BEN MenuLCD Please~make~a~selection:
               Format~your~hard~drive Diskcopy~a~disk Run~Windows
               Run~DOSShell Play~Simcity - Quit

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!

     This example will pop up a message box on the screen as
     shown below:

                        ┌─[_]───────────┐
                        │               │
                        │Hello World!   │
                        │This is a test!│
                        │               │
                        │     OK  ▄     │
                        │    ▀▀▀▀▀▀     │
                        └───────────────┘

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.

     The "foreground" and "background" colors can be specified
     with special words that BEN recognize. These words are:
     Black, Blue, Green, Cyan, Red, Magenta, Brown, LightGray,
     DarkGray, LightBlue, LightGreen, LightCyan, LightRed, Light
     Magenta, Yellow, and White.

     You can also specify the colors with a number if you want.
     For example, instead of using the word "Black", you can use
     the number 0. Instead of using the word "Blue", you can use
     the number 1. And so on.

     Examples: BEN Write LightRed Blue Hello~World!
               BEN Write LightGreen Black This~is~a~test!;
               BEN Write 7 1 Another~test!

     In the first example, BEN displays the string "Hello World!"
     with a color of light red on blue.

     In the second example, BEN displays the string "This is a
     test!" with a color of light green on black. Since there is
     a semi-colon (;) at the end of the line, BEN doesn't move
     the cursor to the beginning of the next line. Instead, BEN
     keeps the cursor after the exclamation mark.

     In the third example, BEN displays the string "Another
     test!" with a color of light gray on blue.

WriteC foreground background message

     Same as Write, but the message is centered between the two
     sides of the monitor.

     Examples: BEN WriteC LightRed Blue Hello~World!
               BEN WriteC LightGreen Black This~is~a~test!;
               BEN WriteC 7 1 Another~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!!!

     In the first example, BEN displays a yellow on blue vertical
     column of string starting from (1,1). The string reads "An
     important message".

     In the second example, BEN displays a light cyan on black
     vertical column of string starting from (40,10). The string
     reads "Hello!".

     In the third example, BEN displays a light gray on blue
     vertical column of string starting from (80,1). The string
     reads "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. Here
     is a list of the music commands supported:

     ML:  legato (8/8 note length)
     MN:  normal music (7/8 note length)
     Ln:  length of notes (n=1-64; note length=1/n, eg. n=2 for
          1/2 note)
     Nn:  Note number (n=0-84; 0 is a rest)
     On:  Octave (n=0-6, default 4)
     Pn:  Pause (n=1-64; pause length=1/n, eg. n=4 for 1/4 note)
     Tn:  Tempo (n=32-255, default 120; quarter notes per minute)
     [:   Move down an octave (min 0)
     ]:   Move up an octave (max 6)

     You can also use the actual letters of the notes (C, D, E,
     F, G, A, and B). These correspond to "do, re, mi, fa, so,
     la, ti". To play a scale, you should use "CDEFGAB]C".

     The notes may be followed by dots, by note lengths, and by
     sharp or flat symbols (a '+' or '#' for a sharp, a '-' for a
     flat). For example, 'D-.' is a dotted D flat. The dot means
     that the note will play for half again its usual length.
     Dots can be repeated.

     You can also use "<" for "[" and ">" for "]" in BEN data
     files that are read by BEN's T function. Don't use these in
     the command line however, because DOS will interpret them as
     redirection signs. If you use them, strange errors may
     occur.

     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.

     The colors can be specified with special words that BEN
     recognize. These words are: Black, Blue, Green, Cyan, Red,
     Magenta, Brown, LightGray, DarkGray, LightBlue, LightGreen,
     LightCyan, LightRed, Light Magenta, Yellow, and White.

     You can also specify the color with a number if you want.
     For example, instead of using the word "Black", you can use
     the number 0. Instead of using the word "Blue", you can use
     the number 1. And so on.

     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.

     The "foreground" and "background" colors can be specified
     with special words that BEN recognize. These words are:
     Black, Blue, Green, Cyan, Red, Magenta, Brown, LightGray,
     DarkGray, LightBlue, LightGreen, LightCyan, LightRed, Light
     Magenta, Yellow, and White.

     You can also specify the colors with a number if you want.
     For example, instead of using the word "Black", you can use
     the number 0. Instead of using the word "Blue", you can use
     the number 1. And so on.

     Examples: BEN Color Yellow Blue
               BEN Color White Red
               BEN Color 7 1

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:  @Echo Off
               BEN EGAVGA On
               If Errorlevel 2 Goto SUCCESS
               BEN Echo Sorry. Your computer cannot display in
               BEN Echo the EGA 43 or the VGA 50 line mode.
               Goto End

               :SUCCESS
               BEN Cls Blue Color White Blue Locate 30 30
               BEN Echo See how big your screen is!
               BEN Locate 30 33
               Pause
               BEN EGAVGA Off

               :End
               BEN CleanUp

GetVideo

     Finds out what kind of video system is installed and returns
     the result via %BEN% (or %BEN2%, %BEN3%, etc. Please refer
     to section 2.3: "BEN and Environment Variables" 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:  @Echo Off
               BEN GetVideo
               IF "%BEN%"=="Mono" GOLF /Mono
               IF "%BEN%"=="CGA" GOLF /CGA
               IF "%BEN%"=="EGA" GOLF /EGA
               IF "%BEN%"=="MCGA" GOLF /MCGA
               IF "%BEN%"=="VGA" GOLF /VGA

     This example shows a batch file that passes different
     parameters to the GOLF program (a game?) depending on what
     video system the computer has.

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 section 2.3: "BEN
     and Environment Variables" 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 returnstring

     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.

     You can also specify only the first letter of the sortorder
     you want. For example, instead of "BEN DirDispA C:\ *.*
     NAME", you can use "BEN DirDispA C:\ *.* N". This is not
     suggested, however, because it decreases the legibility of
     your batch file.

     Example:  BEN DirDispA C:\ *.BAT~*.SYS~*.EXE EXTENSION
               BEN Echo You've picked the file %BEN%!

Extract source mask

     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 section 2.3: "BEN and Environment Variables" for
     further details.)

     'Source' specifies the source string from which you want to
     extract information. Usually, you should place an
     environment variable here.

     'Mask' specifies the part of the selected filename you want
     BEN to return to you. It can contain one or more letters
     which define what BEN should put into %BEN%:

     D    -    Returns only the drive part of the source (eg. C:)
     P    -    Returns only the path part of the source without
               the trailing backslash (eg. \TELECOM)
     \    -    Adds a trailing backslash to the path
     N    -    Returns only the name part of the source
               (eg. AUTOEXEC)
     .    -    Adds a dot to the name
     E    -    Returns only the extension part of the source (eg.
               BAT)

     Example:  BEN DirDisp C:\TELECOM
               SET SELECT=%BEN%
               BEN Extract %SELECT% D
               BEN Echo You've selected a file that is located in
                    drive %BEN%
               BEN Extract %SELECT% P
               BEN Echo This file has a path (without trailing
                    backslash) of %BEN%
               BEN Extract %SELECT% P\
               BEN Echo This file has a path (with trailing
                    backslash) of %BEN%
               BEN Extract %SELECT% N
               BEN Echo This file's name is %BEN%
               BEN Extract %SELECT% E
               BEN Echo And its extension is %BEN%
               BEN Extract %SELECT% N.E
               BEN Echo Its filename (name+extension) is %BEN%
               BEN Extract %SELECT% P\N.E
               BEN Echo Its path, name and extension is %BEN%
               BEN Extract %SELECT% DP\N.E
               BEN Echo This file's full name is %BEN%!
               BEN Echo ~
               BEN GetCD
               BEN Extract %BEN% DRIVE
               BEN Echo You're currently in %BEN% drive.

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 section 2.3:
     "BEN and Environment Variables" for further details.)

     Example:  BEN GetCD
               BEN Echo Hey man, you're in the %BEN% directory!

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 (this file is stored in the current directory)
     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.

     The data file is just a normal text file (ASCII format). It
     can be created with any text editor, such as BENEDIT or the
     EDLIN or the EDIT programs included with DOS. The format of
     the text file is as follows:

     FUNCTIONS
     FUNCTIONS
     FUNCTIONS
     .
     .
     .
     FUNCTIONS
     <End of File>

     The FUNCTIONS are exactly the same functions as those that
     are ran from the command line. For example:

     BEN T DATA.DAT

     where DATA.DAT contains:

     Box 1 1 80 25 Yellow Green 3
     Pause
     Cursor Off
     Cls Blue
     <End of File>

     is exactly the same as doing this:

     BEN Box 1 1 80 25 Yellow Green 3
     BEN Pause
     BEN Cursor Off
     BEN Cls Blue
     ;This is a comment line.
     ;Comment lines start with a ';'.

     Usually, you should only use the T function when you have a
     large quantity of functions that you wish to be processed by
     BEN.

     Examples: BEN T MYFILE.DAT
               BEN T C:\BATCH\INSTRUCT

───────────────────────────────────────────────────────────────────────────
BEN and environment variables
─────────────────────────────
Several of BEN's functions (IE. GetKey, GetKeyL, GetKeyU, GetLine,
GetLineL, 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.

          -    MDESIGN.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.

          -    MDESIGN.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.

          -    MDESIGN.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.