home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-386-Vol-2of3.iso / b / benv302.zip / BEN.HLP < prev    next >
Text File  |  1992-09-23  |  29KB  |  776 lines

  1. BEN, the Batch ENhancer, is an utility that specializes in enhancing batch
  2. files. It can incorporate colors, sounds, menus, pop-up boxes and a host of
  3. other spectacular features into any batch file that you ever write. BEN's
  4. functions are so easy to use that even a beginner batch-maker can build
  5. attractive batch files in no time at all. Experts will also appreciate
  6. BEN's powerful features, such as the directory display controls and the
  7. menuing function.
  8.  
  9. To see an example of what BEN can do for you, run the included BENDEMO.BAT.
  10. Remember to keep in mind that BENDEMO.BAT is only a batch file!
  11.  
  12. Advantages of BEN over other batch file enhancement programs:
  13.  
  14. -    Large number of powerful functions (41 in total) all contained into
  15.      one EXE file.
  16.      
  17. -    All of these functions are very easy to use.
  18.      
  19. -    Comes with BENEdit, a text editor that is tailored for BEN. With
  20.      BENEdit, you can edit all your batch files and access all the features
  21.      of BEN quickly and easily.
  22.      
  23. -    Optimized for speed.
  24.      
  25. -    Perfect for complementing any menuing system (eg. Magik Menu).
  26.      
  27. -    Can be used for programming any batch utilities (eg. INSTALL.BAT).
  28.      
  29. -    Compatible with DOS and Windows.
  30.      
  31. -    Compatible with the network environment. You can now use BEN to
  32.      program all the network batch files!
  33.      
  34. ───────────────────────────────────────────────────────────────────────────
  35. Format:   [d:][pathname] BEN function [params] [functions [params]...]
  36.  
  37. Entering the command "BEN" alone in DOS gives you an online help of BEN's
  38. functions. Make sure that the file BEN.HLP is in the same directory as
  39. BEN.EXE. Otherwise, the online help wouldn't work.
  40.  
  41. To access a BEN function, you must enter the command "BEN" followed by the
  42. name of the function. Some functions doesn't require any parameter. An
  43. example of this is the BEEP function. You can use it by entering this
  44. command into your batch file:
  45.  
  46. BEN BEEP
  47.  
  48. Other functions of BEN require one or more parameters. For example, you can
  49. clear the screen with the color blue by entering this command into your
  50. batch file:
  51.  
  52. BEN CLS BLUE
  53.  
  54. BEN functions can be "stacked" one after another in a command line. For
  55. example, you can group the BEEP function and the CLS function together, one
  56. after another. In this case, BEN will first create a beep, then it will
  57. clear the screen with the color blue:
  58.  
  59. BEN BEEP CLS BLUE
  60.  
  61. When you stack functions together, you may use the "/" separators if you
  62. want. This is not mandatory, but it helps to increase the readability of
  63. your batch file. For example:
  64.  
  65. BEN BEEP / CLS BLUE
  66.  
  67. ───────────────────────────────────────────────────────────────────────────
  68. ASK options
  69. BEEP
  70. BOX x1 y1 x2 y2 foreground background borderstyle
  71. CLEANUP
  72. CLS background
  73. COLOR foreground background
  74. CURSOR ON/OFF/FULL/HALF
  75. DELAY milliseconds
  76. DIRDISP directory
  77. DIRDISPA directory filemask sortorder returnstring
  78. ECHO message [message...]
  79. EGAVGA ON/OFF
  80. EXTRACT source mask
  81. FLUSH
  82. GETCD
  83. GETKEY
  84. GETKEYL
  85. GETKEYU
  86. GETLINE
  87. GETLINEL
  88. GETLINEU
  89. GETVIDEO
  90. GROWFILLEDBOX x1 y1 x2 y2 foreground background borderstyle
  91. LIST filename title
  92. LOCATE x y
  93. MENU title choice1 [choice2 choice3...]
  94. MENULCD title choice1 [choice2 choice3...]
  95. MESSAGE line1 [line2 line3...]
  96. PAUSE
  97. PLAY playstring
  98. SAVEPATH
  99. SCROLL x1 y1 x2 y2 direction
  100. SHADFILLEDBOX x1 y1 x2 y2 foreground background borderstyle
  101. SHELL
  102. SOUND frequency duration
  103. T filename
  104. TITLEDBOX x1 y1 x2 y2 foreground background borderstyle title
  105. TRANSPARENTBOX x1 y1 x2 y2 foreground background
  106. WRITE foreground background message
  107. WRITEC foreground background message
  108. WRITEV x y foreground background message
  109.  
  110. ───────────────────────────────────────────────────────────────────────────
  111. BOX FUNCTIONS
  112. ─────────────
  113. BOX x1 y1 x2 y2 foreground background borderstyle
  114.  
  115.      This function draws an empty box on the screen with an upper-left
  116.      corner of (x1,y1) and a lower-right corner of (x2,y2). Borderstyle can
  117.      be one of the following:
  118.  
  119.      0    -    no border
  120.      1    -    single line box (─)
  121.      2    -    double line box (═)
  122.      3    -    double sides, single top and bottom
  123.      4    -    single sides, double top and bottom
  124.      5    -    single left and upper, double lower and right
  125.      6    -    menu box style
  126.      7+   -    the border is drawn using the ASCII character represented by
  127.                the style value.
  128.  
  129.      The "foreground" and "background" colors can be specified with special
  130.      words that BEN recognize. These words are: BLACK, BLUE, GREEN, CYAN,
  131.      RED, MAGENTA, BROWN, LIGHTGRAY, DARKGRAY, LIGHTBLUE, LIGHTGREEN,
  132.      LIGHTCYAN, LIGHTRED, LIGHT MAGENTA, YELLOW, and WHITE.
  133.  
  134.      You can also specify the colors with a number if you want. For
  135.      example, instead of using the word "BLACK", you can use the number 0.
  136.      Instead of using the word "BLUE", you can use the number 1. And so on.
  137.  
  138.      Examples: BEN BOX 1 1 80 25 WHITE BLUE 1
  139.                BEN BOX 10 10 20 20 YELLOW BLACK 3
  140.                BEN BOX 4 4 8 8 9 2 65
  141.  
  142. FILLEDBOX x1 y1 x2 y2 foreground background borderstyle
  143.  
  144.      Same as BOX, but the box is filled instead of empty.
  145.  
  146.      Examples: BEN FILLEDBOX 1 1 80 25 WHITE BLUE 1
  147.                BEN FILLEDBOX 10 10 20 20 YELLOW BLACK 3
  148.                BEN FILLEDBOX 4 4 8 8 9 9 2 65
  149.  
  150. GROWFILLEDBOX x1 y1 x2 y2 foreground background borderstyle
  151.  
  152.      Same as FILLEDBOX, but the box "grows" out onto the screen, creating a
  153.      spectacular effect.
  154.  
  155.      Examples: BEN GROWFILLEDBOX 1 1 80 25 WHITE BLUE 1
  156.                BEN GROWFILLEDBOX 10 10 20 20 YELLOW BLACK 3
  157.                BEN GROWFILLEDBOX 4 4 8 8 9 2 65
  158.  
  159. SHADFILLEDBOX x1 y1 x2 y2 foreground background borderstyle
  160.  
  161.      Same as FILLEDBOX, but the box has a shadow.
  162.  
  163.      Examples: BEN SHADFILLEDBOX 1 1 80 25 WHITE BLUE 1
  164.                BEN SHADFILLEDBOX 10 10 20 20 YELLOW BLACK 3
  165.                BEN SHADFILLEDBOX 4 4 8 8 9 2 65
  166.  
  167. TITLEDBOX x1 y1 x2 y2 foreground background borderstyle title
  168.  
  169.      Same as FILLEDBOX, but the box has a title. Please note that tildes
  170.      (~) in the title are interpreted as spaces.
  171.  
  172.      Examples: BEN TITLEDBOX 1 1 80 25 WHITE BLUE 1 Great~box!
  173.                BEN TITLEDBOX 10 10 20 20 YELLOW BLACK 3 Another!
  174.                BEN TITLEDBOX 4 4 8 8 9 2 65 Best~box~here!
  175.  
  176. TRANSPARENTBOX x1 y1 x2 y2 foreground background
  177.  
  178.      Paints the region specified by (x1,y1) - (x2,y2) with the specified
  179.      foreground and background colors. Text that are originally on the
  180.      screen are not erased; they are just painted with a new color. Please
  181.      note that the borderstyle parameter is not required.
  182.  
  183.      Examples: BEN TRANSPARENTBOX 1 1 80 25 WHITE BLUE
  184.                BEN TRANSPARENTBOX 10 10 20 20 YELLOW BLACK
  185.                BEN TRANSPARENTBOX 4 4 8 8 9 2
  186.  
  187. INPUT FUNCTIONS
  188. ───────────────
  189. ASK options
  190.  
  191.      Waits for the user to press a key that is contained in the 'options'
  192.      string. The option that the user selects is passed to the batch file
  193.      as an errorlevel. (For more details on errorlevels, please refer to
  194.      your DOS manual.)
  195.  
  196.      For instance, if the options string is ABCDE and the user presses the
  197.      letter C on the keyboard, an errorlevel of 3 is returned (C is the
  198.      third character of the string).
  199.  
  200.      Example:  BEN ECHO Please press A, B, or C.
  201.                BEN ASK ABC
  202.                IF ERRORLEVEL 3 IF NOT ERRORLEVEL 4 ECHO You pressed "C"!
  203.                IF ERRORLEVEL 2 IF NOT ERRORLEVEL 3 ECHO You pressed "B"!
  204.                IF ERRORLEVEL 1 IF NOT ERRORLEVEL 2 ECHO You pressed "A"!
  205.                
  206. GETKEY
  207.  
  208.      Waits for the user to enter a key. This key is returned via the
  209.      environment variable %BEN% (or %BEN2%, %BEN3%, etc. Please refer to
  210.      section 2.3: "BEN and Environment Variables" at for further details.)
  211.  
  212.      Example:  BEN GETKEY
  213.                BEN ECHO You've pressed the %BEN% key!
  214.  
  215. GETKEYL
  216.  
  217.      Same as GETKEY, but the key is converted into lowercase before it is
  218.      returned.
  219.  
  220.      Example:  BEN GETKEYL
  221.                BEN ECHO You've pressed the %BEN% key!
  222.  
  223. GETKEYU
  224.  
  225.      Same as GETKEY, but the key is converted into uppercase before it is
  226.      returned.
  227.  
  228.      Example:  BEN GETKEYU
  229.                BEN ECHO You've pressed the %BEN% key!
  230.  
  231. GETLINE
  232.  
  233.      Waits for the user to enter a string. This string is returned via the
  234.      environment variable %BEN% (or %BEN2%, %BEN3%, etc. Please refer to
  235.      section 2.3: "BEN and Environment Variables" for further details.)
  236.  
  237.      Example:  BEN ECHO What's your name?
  238.                BEN GETLINE
  239.                BEN ECHO So your name is %BEN%!
  240.  
  241. GETLINEL
  242.  
  243.      Same as GETLINE, but the string is converted into lowercase before it
  244.      is returned.
  245.  
  246.      Example:  BEN ECHO What's your name?
  247.                BEN GETLINEL
  248.                BEN ECHO So your name is %BEN% in lowercase!
  249.  
  250. GETLINEU
  251.  
  252.      Same as GETLINE, but the string is converted into uppercase before it
  253.      is returned.
  254.  
  255.      Example:  BEN ECHO What's your name?
  256.                BEN GETLINEU
  257.                BEN ECHO So your name is %BEN% in uppercase!
  258.  
  259. MENU title choice1 [choice2 choice3...]
  260.  
  261.      Displays a menu on the screen. The choice that is selected by the user
  262.      is passed back to the batch file as an errorlevel. For instance, if
  263.      the user chooses choice #3, an errorlevel of 3 is returned. On the
  264.      other hand, if the user opts to choose nothing, then an errorlevel of
  265.      0 is returned.
  266.  
  267.      Please note that tildes (~) are interpreted as spaces, and no other
  268.      function can be stacked after the MENU function is used. Also, use a
  269.      minus sign (-) to tell BEN to display a blank line.
  270.  
  271.      Examples: BEN MENU My~Game~Menu Sim~City Wing~Commander
  272.                BEN MENU Network~Utilities PCONSOLE SYSCON - Log~Out
  273.                
  274. MENULCD title choice1 [choice2 choice3...]
  275.  
  276.      Same as MENU, except that the menu is displayed in black and white for
  277.      added clarity on LCD screens.
  278.  
  279.      Example:  BEN MENULCD Please~make~a~selection: Format~your~hard~drive
  280.                Diskcopy~a~disk Run~Windows Run~DOSShell Play~Simcity - Quit
  281.  
  282. MESSAGE FUNCTIONS
  283. ─────────────────
  284. ECHO message [message...]
  285.  
  286.      Works like the DOS ECHO function. Everything after the word ECHO is
  287.      displayed using the current writing color. Thus, no other functions
  288.      can be stacked after ECHO is used.
  289.  
  290.      If you wish to display a blank line, use the command "BEN ECHO ~". If
  291.      you wish to display more than one space between two words, use the
  292.      tilde (~) as a separator instead. For example, if you want to display
  293.      the words "Hello   World, this is the computer speaking.", use the
  294.      command "BEN ECHO Hello~~~World, this is the computer speaking."
  295.  
  296.      Examples: BEN ECHO Hello World!
  297.                BEN ECHO This is a test!
  298.                BEN ECHO ~
  299.                BEN ECHO Hello~~~World, this is the computer speaking.
  300.  
  301. LIST filename title
  302.  
  303.      Acts as a file browser for the file specified by "filename". Tildes
  304.      (~) in the title are interpreted as spaces.
  305.  
  306.      Examples: BEN LIST C:\AUTOEXEC.BAT This~is~your~AUTOEXEC!
  307.                BEN LIST BEN.TXT You~are~reading~BEN.TXT!
  308.  
  309. MESSAGE line1 [line2 line3...]
  310.  
  311.      Pops up a message box onto the screen. Tildes (~) are interpreted as
  312.      spaces.
  313.  
  314.      Example:  BEN MESSAGE Hello~World! This~is~a~test!
  315.  
  316.      This example will pop up a message box on the screen as shown below:
  317.  
  318.                         ┌─[_]───────────┐
  319.                         │               │
  320.                         │Hello World!   │
  321.                         │This is a test!│
  322.                         │               │
  323.                         │     OK  ▄     │
  324.                         │    ▀▀▀▀▀▀     │
  325.                         └───────────────┘
  326.  
  327. WRITE foreground background message
  328.  
  329.      Writes a string onto the screen using the specified foreground and
  330.      background colors. Tildes (~) in the message are interpreted as
  331.      spaces, and a semi-colon (;) at the end of the message tells BEN not
  332.      to wrap to the next line.
  333.      
  334.      The "foreground" and "background" colors can be specified with special
  335.      words that BEN recognize. These words are: BLACK, BLUE, GREEN, CYAN,
  336.      RED, MAGENTA, BROWN, LIGHTGRAY, DARKGRAY, LIGHTBLUE, LIGHTGREEN,
  337.      LIGHTCYAN, LIGHTRED, LIGHT MAGENTA, YELLOW, and WHITE.
  338.      
  339.      You can also specify the colors with a number if you want. For
  340.      example, instead of using the word "BLACK", you can use the number 0.
  341.      Instead of using the word "BLUE", you can use the number 1. And so on.
  342.  
  343.      Examples: BEN WRITE LIGHTRED BLUE Hello~World!
  344.                BEN WRITE LIGHTGREEN BLACK This~is~a~test!;
  345.                BEN WRITE 7 1 Another~test!
  346.  
  347. WRITEC foreground background message
  348.  
  349.      Same as WRITE, but the message is centered between the two sides of
  350.      the monitor.
  351.  
  352.      Examples: BEN WRITEC LIGHTRED BLUE Hello~World!
  353.                BEN WRITEC LIGHTGREEN BLACK This~is~a~test!;
  354.                BEN WRITEC 7 1 Another~test!
  355.  
  356. WRITEV x y foreground background message
  357.  
  358.      Same as WRITE, but the message is written as a vertical column that
  359.      starts from the position (x,y).
  360.  
  361.      Examples: BEN WRITEV 1 1 YELLOW BLUE An~important~message
  362.                BEN WRITEV 40 10 LIGHTCYAN BLACK Hello!
  363.                BEN WRITEV 80 1 7 1 Great!!!
  364.  
  365. MUSIC FUNCTIONS
  366. ───────────────
  367. BEEP
  368.  
  369.      Creates a beep sound.
  370.  
  371.      Example:   BEN BEEP
  372.  
  373. PLAY playstring
  374.  
  375.      Plays music using the computer's speaker. The playstring is exactly
  376.      the same in format as the BASIC PLAY statement. Please refer to
  377.      BEN.TXT for a complete discussion.
  378.  
  379.      Examples: BEN PLAY O5CDEFGFEDCP1CC
  380.                BEN PLAY ]EEEC
  381.  
  382. SOUND frequency duration
  383.  
  384.      Uses the computer's speaker to produce a tone with the specified
  385.      frequency for the specified duration. Frequency is measured in hertz
  386.      and duration is measured in milliseconds.
  387.  
  388.      Examples: BEN SOUND 1000 1000
  389.                BEN SOUND 2000 100
  390.  
  391. SCREEN FUNCTIONS
  392. ────────────────
  393. CLS background
  394.  
  395.      Clears the screen with the specified color.
  396.  
  397.      The colors can be specified with special words that BEN recognize.
  398.      These words are: BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN,
  399.      LIGHTGRAY, DARKGRAY, LIGHTBLUE, LIGHTGREEN, LIGHTCYAN, LIGHTRED, LIGHT
  400.      MAGENTA, YELLOW, and WHITE.
  401.  
  402.      You can also specify the color with a number if you want. For example,
  403.      instead of using the word "BLACK", you can use the number 0. Instead
  404.      of using the word "BLUE", you can use the number 1. And so on.
  405.  
  406.      Examples: BEN CLS BLUE
  407.                BEN CLS GREEN
  408.  
  409. COLOR foreground background
  410.  
  411.      Changes the current writing color. ANSI.SYS must be loaded for this
  412.      function to operate.
  413.  
  414.      The "foreground" and "background" colors can be specified with special
  415.      words that BEN recognize. These words are: BLACK, BLUE, GREEN, CYAN,
  416.      RED, MAGENTA, BROWN, LIGHTGRAY, DARKGRAY, LIGHTBLUE, LIGHTGREEN,
  417.      LIGHTCYAN, LIGHTRED, LIGHT MAGENTA, YELLOW, and WHITE.
  418.  
  419.      You can also specify the colors with a number if you want. For
  420.      example, instead of using the word "BLACK", you can use the number 0.
  421.      Instead of using the word "BLUE", you can use the number 1. And so on.
  422.  
  423.      Examples: BEN COLOR YELLOW BLUE
  424.                BEN COLOR WHITE RED
  425.                BEN COLOR 7 1
  426.  
  427. CURSOR ON/OFF/FULL/HALF
  428.  
  429.      Changes the cursor shape. Use ON for a normal cursor (_), OFF for no
  430.      cursor ( ), FULL for a block cursor (█) and HALF for a half-block
  431.      cursor (▄).
  432.  
  433.      Examples: BEN CURSOR OFF
  434.                BEN CURSOR FULL
  435.  
  436. EGAVGA ON/OFF
  437.  
  438.      Switches the EGA 43 / VGA 50 line mode on or off. If the EGA 43 / VGA
  439.      50 line mode is switched on successfully, an errorlevel of 2 is passed
  440.      back to the batch file. Otherwise, an errorlevel of 1 is returned.
  441.  
  442.      Example:  BEN EGAVGA ON
  443.                IF ERRORLEVEL 2 IF NOT ERRORLEVEL 3 ECHO Success!
  444.                IF ERRORLEVEL 1 IF NOT ERRORLEVEL 2 ECHO Failure!
  445.                BEN PAUSE EGAVGA OFF
  446.  
  447. GETVIDEO
  448.  
  449.      Finds out what kind of video system is installed and returns the
  450.      result via %BEN% (or %BEN2%, %BEN3%, etc. Please refer to section 2.3:
  451.      "BEN and Environment Variables" for further details.)
  452.  
  453.      The possible values that can be returned are as follows:
  454.  
  455.      MONO:     The computer has a monochrome system.
  456.      CGA:      The computer has a CGA system.
  457.      EGA:      The computer has an EGA system.
  458.      MCGA:     The computer has a MCGA system.
  459.      VGA:      The computer has a VGA system.
  460.  
  461.      Example:  BEN GETVIDEO
  462.                IF "%BEN%"=="VGA" BEN ECHO You've got a VGA card!
  463.  
  464. LOCATE x y
  465.  
  466.      Moves the screen cursor to the position (x,y).
  467.  
  468.      Examples: BEN LOCATE 1 1
  469.                BEN LOCATE 10 15
  470.  
  471. SCROLL x1 y1 x2 y2 direction
  472.  
  473.      Scrolls the text enclosed in the (x1,y1)-(x2,y2) box. 'Direction' can
  474.      be one of the following: UP, DOWN, LEFT, RIGHT.
  475.  
  476.      Examples: BEN SCROLL 1 1 80 25 UP
  477.                BEN SCROLL 10 10 20 20 LEFT
  478.  
  479. MISCELLANEOUS FUNCTIONS
  480. ───────────────────────
  481. CLEANUP
  482.  
  483.      This function should be called at the end of batch files. It does four
  484.      things:
  485.      1.   Changes the writing color to normal DOS color (same as calling
  486.           BEN COLOR LIGHTGRAY BLACK).
  487.      2.   Changes the cursor to a normal shape (same as calling
  488.           BEN CURSOR ON).
  489.      3.   Erases all the environment variables that have been created by
  490.           BEN (IE. %BEN%, %BEN2%, %BEN3%, etc.)
  491.      4.   Restores the PATH if the SAVEPATH function had been called
  492.           previously. (Please refer to the discussion on the SAVEPATH
  493.           function.)
  494.  
  495.      Example:  BEN CLEANUP
  496.  
  497. DELAY milliseconds
  498.  
  499.      Pauses the computer for the specified number of milliseconds. (1000
  500.      milliseconds = 1 second)
  501.  
  502.      Examples: BEN DELAY 1000
  503.                BEN DELAY 5000
  504.  
  505. DIRDISP directory
  506.  
  507.      Displays a file selection box and allows the user to select a file.
  508.      The name of the selected file is stored into %BEN% (or %BEN2%, %BEN3%,
  509.      etc. Please refer to section 2.3: "BEN and Environment Variables" for
  510.      further details.)
  511.  
  512.      If the user presses ESC and opts not to choose any file, then %BEN% is
  513.      set to contain nothing.
  514.  
  515.      Example:  BEN DIRDISP C:\
  516.                IF "%BEN%"=="" GOTO CHOSE_NOTHING
  517.                BEN ECHO You've chosen %BEN%!
  518.                GOTO END
  519.                :CHOSE_NOTHING
  520.                BEN ECHO You didn't choose any file!
  521.                :END
  522.  
  523. DIRDISPA directory filemask sortorder returnstring
  524.  
  525.      This is the advanced version of DIRDISP. In addition to the starting
  526.      directory, you can specify the file mask and the sorting order.
  527.      
  528.      'Filemask' specifies the types of file you want to display. For
  529.      example, if you want to display only EXE files, you can use a filemask
  530.      of "*.EXE". If you want to display both EXE and COM files, you can use
  531.      a filemask of "*.EXE~*.COM" [different types of files are separated
  532.      with tildes (~).]
  533.      
  534.      'Sortorder' specifies the order which DIRDISPA uses to display the
  535.      files. It can be one of the following:
  536.  
  537.      NAME      -    Files sorted on names in ascending order.
  538.      EXTENSION -    Files sorted on extensions in ascending order.
  539.      TIME      -    Files sorted on time from the earliest to the latest.
  540.      SIZE      -    Files sorted on size from the smallest to the largest.
  541.      X         -    Files are unsorted.
  542.  
  543.      You can also specify only the first letter of the sortorder you want.
  544.      For example, instead of "BEN DIRDISPA C:\ *.* NAME", you can use "BEN
  545.      DIRDISPA C:\ *.* N". This is not suggested, however, because it
  546.      decreases the legibility of your batch file.
  547.  
  548.      Example:  BEN DIRDISPA C:\ *.BAT~*.SYS~*.EXE EXTENSION
  549.                BEN ECHO You've picked the file %BEN%!
  550.  
  551. EXTRACT source mask
  552.  
  553.      This is a function that extracts a certain part of a fully qualified
  554.      filename (eg. the result from DIRDISP or GETCD) and stores it into
  555.      %BEN% (or %BEN2%, %BEN3%, etc. Please refer to section 2.3: "BEN and
  556.      Environment Variables" for further details.)
  557.  
  558.      'Source' specifies the source string from which you want to extract
  559.      information. Usually, you should place an environment variable here.
  560.  
  561.      'Mask' specifies the part of the selected filename you want BEN to
  562.      return to you. It can contain one or more letters which define what
  563.      BEN should put into %BEN%:
  564.  
  565.      D         -    Returns only the drive part of the source (eg. C:)
  566.      P         -    Returns only the path part of the source without the
  567.                     trailing backslash (eg. \TELECOM)
  568.      \         -    Adds a trailing backslash to the path
  569.      N         -    Returns only the name part of the source (eg. AUTOEXEC)
  570.      .         -    Adds a dot to the name
  571.      E         -    Returns only the extension part of the source (eg. BAT)
  572.      
  573.      Example:  BEN DIRDISP C:\
  574.                BEN EXTRACT %BEN% N.E
  575.                BEN ECHO You've selected the file %BEN%!
  576.  
  577. FLUSH
  578.  
  579.      Clears the keyboard buffer.
  580.  
  581.      Example:  BEN FLUSH
  582.  
  583. GETCD
  584.  
  585.      Finds out what the current directory is and stores it into %BEN% (or
  586.      %BEN2%, %BEN3%, etc. Please refer to section 2.3: "BEN and Environment
  587.      Variables" for further details.)
  588.  
  589.      Example:  BEN GETCD
  590.                BEN ECHO Hey man, you're in the %BEN% directory!
  591.                
  592. PAUSE
  593.  
  594.      Pauses the computer until the user presses a key.
  595.  
  596.      Example:   BEN PAUSE
  597.  
  598. SAVEPATH
  599.  
  600.      Saves the PATH environment variable into a file called SAVEPATH.DAT
  601.      (this file is stored in the current directory) and erases the PATH
  602.      environment variable. Using this function can free up environment
  603.      space so that BEN functions that make use of the environment (eg.
  604.      GETLINE) can function better. Remember to use the CLEANUP function to
  605.      restore the PATH upon the completion of the batch file.
  606.  
  607.      Caution:  Make sure that you don't change directory after using
  608.                SAVEPATH. If you do, you must change back to the directory
  609.                where SAVEPATH stores SAVEPATH.DAT before you run CLEANUP.
  610.  
  611.      Example:  @ECHO OFF
  612.                BEN SAVEPATH
  613.                BEN ECHO Your PATH has been saved!
  614.                BEN CLEANUP
  615.                BEN ECHO Your PATH is restored!
  616.  
  617. SHELL
  618.  
  619.      "Jumps to DOS". After this function is used, the user can work in DOS
  620.      as long as he/she want. He/she can let the batch file regain control
  621.      by typing EXIT.
  622.  
  623.      Example:  BEN SHELL
  624.  
  625. T filename
  626.  
  627.      Runs all the instructions in the data file. This lets BEN perform its
  628.      jobs at a quicker speed. Please refer to BEN.TXT for a complete
  629.      discussion.
  630.  
  631.      Examples: BEN T MYFILE.DAT
  632.                BEN T C:\BATCH\INSTRUCT
  633.  
  634. ───────────────────────────────────────────────────────────────────────────
  635. BEN and environment variables
  636. ─────────────────────────────
  637. Several of BEN's functions (IE. GETKEY, GETKEYL, GETKEYU, GETLINE,
  638. GETLINEL, GETLINEU, DIRDISP, DIRDISPA, EXTRACT, GETCD and GETVIDEO) return
  639. their results using environment variables. After you use any one of these
  640. functions, you can access the data that BEN returns by calling the variable
  641. %BEN%. Just put %BEN% in your batch file where you want the data to appear.
  642. For example, if you want to get the user's name and re-display it, you can
  643. do the following:
  644.  
  645. BEN WRITE White Black Please~enter~your~name:~; GETLINE
  646. BEN WRITE White Black Your~name~is~%BEN%!
  647.  
  648. If you stack several functions that return data via environment variables,
  649. the first result would be stored into %BEN%, the second result into %BEN2%,
  650. the third into %BEN3%, and so on. For example, if you want to ask the user
  651. to enter two favorite colors and re-display them, you can do the following:
  652.  
  653. BEN WRITE White Black Enter~your~two~favorite~colors:
  654. BEN GETLINE GETLINE
  655. BEN WRITE White Black So~they~are:~%BEN%~and~%BEN2%!
  656.  
  657. Note:     At the end of your batch file, you should make a call to BEN's
  658.           CLEANUP function to erase all the variables that BEN have created
  659.           (IE %BEN%, %BEN2%, %BEN3%, etc.)
  660.  
  661. ───────────────────────────────────────────────────────────────────────────
  662. Shareware Registration
  663. ──────────────────────
  664. BEN is NOT free software. BEN is NOT public domain software. BEN is
  665. shareware: you are expected to pay a registration fee to the author of this
  666. program if you find it useful. You are allowed to use BEN for free within a
  667. trial period of 60 days. After 60 days, if you continue to use BEN, you
  668. must register.
  669.  
  670. There are three editions of BEN available for registration:
  671.  
  672. A>   Personal Edition - $39
  673.  
  674.      With registration, you get the following:
  675.      -    Complete BEN package on a disk:
  676.  
  677.           -    BEN.EXE with your specified registration name encoded into
  678.                the code.
  679.                
  680.           -    BENMOUSE.EXE (a bonus version of BEN that has the ability to
  681.                make use of mouses) with your specified registration name
  682.                encoded into the code.
  683.                
  684.           -    BENEDIT.EXE with your specified registration name encoded
  685.                into the code.
  686.                
  687.           -    All other BEN-related files.
  688.                
  689.      -    Next version of the complete BEN package on a disk free of
  690.           charge.
  691.           
  692.      -    One printed manual that covers all aspects of BEN.
  693.           
  694.      -    Free technical support.
  695.           
  696. B>   Programmer's Edition - $99
  697.  
  698.      With registration, you get the following:
  699.      -    Complete BEN package on a disk:
  700.  
  701.           -    BEN.EXE with your specified registration name encoded into
  702.                the code.
  703.                
  704.           -    BENMOUSE.EXE (a bonus version of BEN that has the ability to
  705.                make use of mouses) with your specified registration name
  706.                encoded into the code.
  707.                
  708.           -    BENEDIT.EXE with your specified registration name encoded
  709.                into the code.
  710.                
  711.           -    All other BEN-related files.
  712.                
  713.      -    Next version of the complete BEN package on a disk free of
  714.           charge.
  715.           
  716.      -    One printed manual that covers all aspects of BEN.
  717.           
  718.      -    A distribution license. With this license, you are permitted to
  719.           use BEN to create batch utilities that you can distribute,
  720.           royalty-free.
  721.           
  722.      -    Free technical support.
  723.           
  724. C>   Business Edition - $199
  725.  
  726.      With registration, you get the following:
  727.      -    Complete BEN package on a disk:
  728.  
  729.           -    BEN.EXE with your specified registration name encoded into
  730.                the code.
  731.                
  732.           -    BENMOUSE.EXE (a bonus version of BEN that has the ability to
  733.                make use of mouses) with your specified registration name
  734.                encoded into the code.
  735.                
  736.           -    BENEDIT.EXE with your specified registration name encoded
  737.                into the code.
  738.                
  739.           -    All other BEN-related files.
  740.                
  741.      -    All future versions of the complete BEN package on a disk free of
  742.           charge.
  743.           
  744.      -    Five sets of printed manuals that covers all aspects of BEN.
  745.           
  746.      -    A site license for unlimited number of users on a LAN.
  747.           
  748.      -    A distribution license. With this license, you are permitted to
  749.           use BEN to create batch utilities that you can distribute,
  750.           royalty-free.
  751.           
  752.      -    Free technical support.
  753.           
  754. To order, please send $39, $99 or $199 (depending on which edition you
  755. want) + $5 Postage/Handling to the following address:
  756.  
  757.                             Simon Lee
  758.                         7905 Bayview Ave.
  759.                             Unit 1019
  760.                        Thornhill  Ontario
  761.                              Canada
  762.                              L3T 7N3
  763.  
  764. Notes:
  765.  
  766. -    Do specify the registration name (eg. Mr. Bill Smith, ABC Company).
  767. -    Do specify the size of the disk you want (IE. 5.25" or 3.5")
  768. -    Pay in cash or cheque.
  769. -    Make all cheques payable to Simon Lee.
  770. -    Pay in Canadian currency if ordered from Canada. Pay in US currency if
  771.      ordered from US or other countries.
  772.  
  773. *    You can simplify the registration process by selecting the "Register"
  774.      option under the system menu in BENEdit.
  775.  
  776.