

   ENVY: A 16-bit batch enhancement utility for MS-DOS, Windows 95,
      Windows 98, and Windows NT.


   Version 1.00 ( Trial version )

   Copyright (c) 2000 by James K. Lawless
   Email: jimbo@radiks.net
   Web:   http://www.radiks.net/jimbo


   Table of Contents

      What is ENVY?
      Installing ENVY
      How does one use ENVY?
      Command Descriptions
      Is ENVY "crippleware"?
      Registering ( paying for use of ) ENVY
      Upgrading from a prior version of ENVY
      Disclaimer
      Help!  What to do if you encounter problems.
      Technical Specifications
      Distribution


   *-- What is ENVY

      ENVY is a 16-bit command-line tool that provides enhanced batch
      file extensions.

      ENVY's primary feature is the ability to alter MS-DOS environment
      variables ( which works in Windows 95, Windows 98, and under
      the COMMAND.COM command-processor under Windows NT. )

      The goal of ENVY is to provide features which bring the venerable
      MS-DOS batch file system up to a more robust programming system.


      ENVY makes 37 new batch scripting commands available for your use.

   *-- Installing ENVY

      If you are reading this, you have already unzipped the archive
      containing ENVY ( ENVY100.ZIP ).


   *-- How does one use ENVY

      To invoke ENVY, simply type ENVY and the appropriate ENVY
      command and parameters at a command-prompt.

      When you first run the trial version of ENVY, you'll see the
      following message:


        This is an unregistered evaluation (trial) copy of ENVY, 
        a batch file enhancer.

        You will see this message for 7 seconds when you run ENVY after
        a power-up and/or on each new day.

        The registered version of ENVY does not have this limitation.

        If you use ENVY beyond the 30 day evaluation period you must
        register or discontinue using ENVY.

        You may register by visiting the following URL:

             http://www.radiks.net/jimbo

      This message will appear each time you use the TRIAL
      version of ENVY after you've started your computer.

      It will also appear during ENVY's first use each day.
      ( If you begin using ENVY at 11:58 p.m., it will run
      in an unobstructed manner until 12:00 a.m.  It will
      then display the registration message and will pause
      for 7 seconds.

      This restriction does not exist in the registered version.



      ENVY adds 37 commands for use primarily in batch files ( although
      many of the commands can easily be run directly from a command-prompt.)

      Try the following at a command-prompt ( the command-prompt must
      be a 16-bit command-prompt such as COMMAND.COM.  The environment
      variable commands will not work under 32-bit command-processors
      such as NT's CMD.EXE. )

         envy -date X
         set

      A list of your environment variables will scroll by the screen.

      You should see one near the end of the list that shows the
      variable "X" containing today's date.  It might look something
      like this:

         X=08/23/00

      The ENVY -date command takes the current date and places it
      in the environment variable specified as the first argument.

      Now, try this:

         envy -time X
         set

      You should now see that the variable X contains the
      current time.

      These values can now be used in batch files by placing
      the percent-sign symbols around the variables.

      Please refer to the sample batch files to observe how
      the ENVY commands can be used to augment a batch file.





   *-- Command Descriptions

      To invoke ENVY, simply type ENVY and the appropriate ENVY
      command.



        ENVY  -checkenv       number

      The checkenv command compars the specified number to the
      available space left in the parent environment block.  If
      the remaining space is less than the specified number, an
      ERRORLEVEL 0 is generated.

      If the available memory is greater or equal to the number
      specified, an ERRORLEVEL 1 is generated.

      The purpose of this command is to allow you to test to see
      if you have enough environment space free before attempting
      to use any of ENVY's environment-variable commands.



        ENVY  -checkmax       number

      The checkmax command is similar to checkenv.  Rather than
      checking for free space, it checks the specified number
      against the TOTAL space in the parent environment block.

      Again, this command is intended to be useful at the beginning
      of a script to help determine if the parent environment
      block is big enough for a given task.



        ENVY  -clearenv

      The clearenv command completely erases all entries in the
      parent environment.  You may wish to use the -saveenv
      command to save the environment to a text file before
      using clearenv.



        ENVY  -compare  num1 op num2

      The compare command compares two numbers based on an
      operator.  ERRORLEVEL is set to 1 if the comparison
      is true, 0 if false.

      Valid operators are:

         eq    Equal
         lt    Less than
         gt    Greater than
         le    Less than or equal
         ge    Greater than or equal
         ne    Not equal

      See the usage in the sample batch files NAME.BAT,
      WORDS.BAT, and PRIMES.BAT.


        ENVY   -copy           var srcvar

      The copy command is used to copy the contents of srcvar to
      var.  This can normally be accomplished by using the built-in
      MS-DOS SET command.

      The SET command, however, is limited to about 127 characters.

      The copy command will copy an environment variable of any size
      ( up to about 32K. )

      Please note that you do not need to specify the percent-sign
      symbols around the "srcvar" argument.  "srcvar" is expected
      to be a variable name, not the expanded contents.



        ENVY  -ctime          var

      The ctime command sets the specified variable to a time/date
      string in a format similar to the following:

         Wed Aug 23 21:54:44 2000



        ENVY  -date           var

      The date command stores the current date in MM/DD/YY format
      into the specified variable.



        ENVY  -dec            var

      The dec command decrements ( or decreases ) the number held
      in the specified variable by 1.



        ENVY  -deletevar      var

      The deletevar command is used to remove all occurrences of a
      variable from the parent environment.  It's possible to actually
      create multiple copies of an environment variable if you mix
      usage of the SET MS-DOS command with an ENVY option and you
      use a lower-case variable name.

      I highly recommend always using upper-case environment variable
      names.



        ENVY  -eko            str1 .. strN

      The eko command is an enhanced "ECHO" command that will allow
      you to specify hexidecimal characters in place of a string.

      Place a "#" symbol followed by two hexadecimal digits for the
      character you desire to output as a string by itself.

      For instance:

         ENVY -eko "Hello," #0d #0a #0d #0a "world!"

      ...will display "Hello," on one line, a blank line, then
      "world" on the last line.

      The eko command does not automatically add a carriage-return
      and linefeed when done.  You must specify them yourself
      as #0d and #0a respectively.

      The eko command will also allow you to output characters
      that are tricky ( if not impossible ) to display using the
      normal MS-DOS ECHO command.  Two such characters are the
      "<" and ">" characters.  These characters have a special
      purpose in an MS-DOS command; the provide input and output
      redirection.

      If you'd like to display "<" the ENVY command would be:

         ENVY -eko #3c

      If you'd like to display ">" the ENVY command would be:

         ENVY -eko #3e

      

        ENVY  -expr           var term operator term

      The expr command is used to solve a long-integer
      mathematical or bitwise expression.  Valid operators are:

         +     Addition       ( var = term1 + term2 )
         -     Subtraction    ( var = term1 - term2 )
         *     Multiplication ( var = term1 * term2 )
         /     Division       ( var = term1 / term2 )
         mod   Modulus        ( var = term1 mod term2 )
         and   Bitwise "AND"  ( var = term1 and term2 )
         or    Bitwise "OR"   ( var = term1 or term2 )
         xor   Bitwise "EXCLUSIVE-OR" ( var = term1 xor term2 )

      Please refer to the sample PRIMES.BAT file which uses expr
      to calculate prime numbers between 2 and 1000. 



        ENVY  -filename       var [drive path basename ext ] filenameandpath

      The filename command is used to retrieve segments of a fully
      qualified path and filename.  You can retrieve either the
      drive-letter ( with colon ), path, base filename, or extension.

      The command:

         ENVY -filename x drive C:\temp.txt

      ...would leave the "x" variable with the value "C:".



        ENVY  -findinpath     filename

      The findinpath command sets ERRORLEVEL to 1 if the specified
      filename can be found in the existing PATH environment variable.



        ENVY  -getdir         var

      The getdir command retrieves the current working directory
      into the given variable.



        ENVY  -getxy          varx vary

      The getxy command retrieves the current cursor x and y
      positions into the two specified variables.



        ENVY  -gotoxy         numberX numberY

      The gotoxy command sets the cursor position to the specified
      x and y values.



        ENVY  -inc            var

     The inc command increments ( or increases ) the numeric value
     of a variable by 1.  This command is useful in counter-controlled
     loop processing.

     Please refer to the LOOP20.BAT sample file for a demonstration
     of a counter-controlled loop.



        ENVY  -index          var str srchstr

     The index command is used to retrieve the position of "srchstr"
     within the specified string "str".  If the srchstr value is
     found, its zero-relative position is stored in var, otherwise
     a -1 is stored in var.

     The index command is case-sensitive.  If you need to look
     for a string that may appear in different cases, you may
     need to transform the string to upper-case or lower-case
     using the -ucase or -lcase commands.



        ENVY  -key            var

     The key command waits for a kestroke and returns its decimal
     numeric value in the specified var.



        ENVY  -lcase          var str

     The lcase command converts the specified string to lower-case and
     stores the result in the specified variable.



        ENVY  -length         var str

     The length command stores the length of the specified string in
     variable str.



        ENVY  -loadenv        filename

     The loadenv command loads the parent environment block with the
     environment strings in the file specified.  The loadenv command
     is intended to be used with files generated by the -saveenv command.


        ENVY  -match          str srchstr

     The match command will set ERRORLEVEL to 1 if srchstr is found
     in str.  The search does not depend on case.

     The primary intent of the match command was to be able to determine
     if the user is running a command-processor appropriate for use
     with the ENVY program.  Consider the following batch file snippet:

        ENVY -match %COMSPEC% cmd.exe
        if ERRORLEVEL 1 goto get_out

     If the current command-processor name contained cmd.exe, we
     could abort the attempt to process the batch file.



        ENVY  -random         var max

     The random command generates an integer random number from 0
     to 1 below the "max" specified value.

     If you wanted to simulate a dice-roll, you might want to use
     the following:

       : get random number from 0 to 5
       ENVY -random D1 6
       : bump it up by 1 for 1 to 6 range
       ENVY -inc D1

     Please refer to the DICE.BAT batch file in the sample
     programs.



        ENVY  -readln         var

     The readln command is one of the most versatile commands that
     ENVY has to offer.  It allows an environment variable to be
     set via an input line.  This line can either be input interactively
     or as piped input from another program or file.

     The sample NAME.BAT file accepts the users name via readln.

     

        ENVY  -replace        var str chr1 chr2

     The replace command replaces all occurrences of character 1
     with character in string.  The result is stored in a variable.

     Let's say you need to create a directory based on the current
     date.  You could use the -date command to retrieve the current
     date into an environment variable.

     However, if you try to use the MS-DOS "md" or "mkdir" commands,
     the "/" characters found in the date will cause the command to
     fail.

     We could then use the replace command to translate the slashes
     to a more innocuous character, such as an underscore "_".

     Consider the following batch file fragment.

        ENVY -date X
        ENVY -replace Y %X% / _
        md %Y%

     If today's date happened to be 8/23/00, you'd see a new directory
     "08_23_00" after the execution of the above lines.

     See the DATEDIR.BAT example program to see the above in action.

     Either ( or both ) of the two characters can be specified in
     hexadecimal using the # symbol followed by two hex digits.

        ENVY  -saveenv        filename

     The saveenv command saves all environment variables in the
     parent environment to the file specified in filename.

     Usually, this is done right before a call to -clearenv so
     the the environment can be later reloaded with -loadenv.



        ENVY  -seterrorlevel  number

     The seterrorlevel command allows ERRORLEVEL to be set so that
     it can be tested by other portions of the batch file.



        ENVY  -sleep          seconds

     The sleep command pauses for the specified number of seconds.
     This command can be used to provide slight delays in your
     programs execution ( perhaps while you're waiting for the
     user to read something from the screen. )



        ENVY  -sprintf        var str1 .. strN

     The sprintf command is named from a similar function found
     in the C programming language's standard string library.

     The intent of sprintf is to provide a formatting mechanism.
     It can be used to build environment strings which contain
     characters difficult to specify on a command-line ( such
     as "<" and ">". )

     The sprintf command builds the output string based on each
     string found after the specified variable in the argument
     list.  If a string is found to begin with the "#" symbol,
     the next two characters are treated as hexadecimal digits.
     The resulting character is appended to the growing string.



        ENVY  -substr         var str start length

     The substr command extracts a segment of a string and
     leaves the fragment in the specified variable.  The start
     offset is relative to zero.



        ENVY  -time           var

     The time command retrieves the current time in HH:MM:SS
     24-hour format.  The result is stored in the specified
     variable.

     

        ENVY  -ucase          var str

     The ucase command converts the specified string to upper-case and
     stores the result in the specified variable.



        ENVY  -word           var num str

     The word command extracts the word number "num" ( relative
     to zero) from the specified string.  This command is useful
     when parsing input from the user.  The -wordcount command
     may be useful in conjunction with this command.

     Please see the WORDS.BAT demo batch file for a demonstration
     of the two commands.


        ENVY  -wordcount      var str

     The wordcount command counts the number of words in the
     specified string, separated by space characters, tabs,
     carriage-returns, and linefeeds.



        ENVY  -write  var filename

     The write command writes the data found in the specified
     variable to the specified filename.  The variable may
     contain the "<" or ">" characters which would cause
     problems with the normal MS-DOS ECHO command.

     The write command does not add a carriage-return linefeed
     to the end of the file.

     The data is appended to the file.  If the specified file
     does not exist, the write command will create it.


        ENVY  -writeln  var filename

     The writeln command is identical to write except that it adds
     a carriage-return and linefeed after the specfied variable data.

    
   

   *-- Is ENVY "crippleware"?

      In a word...yes.

      The trial version of ENVY displays a 7-second message
      after each reboot or after the date changes to a new
      day.

      The registered version does not contain this restriction.



   *-- Registering ( paying for use of ) ENVY

      ENVY is shareware.

      It is not free software.

      You may use it for a trial period of 30 days.  If you continue
      to use it after 30 days or if you use it for any purposes
      you are required to register the software.

      The registration fee for the software is $20.00 in U.S. funds for
      each copy that has a potential to be used ( i.e. if you have 5
      people in your company and 4 of them may need to use ENVY, you
      are required to pay 4 registration fees ).

      If you use ENVY in a batch file that exists on an LAN shared
      drive, but is executed by 500 users, you'll need 500 licenses
      for ENVY.  ( Actually, in this case, a site license would
      make more sense. )

      Please remit payment by check ( drawn on a U.S. Bank ) to:

         James K. Lawless
         2414 4th Avenue
         Council Bluffs, IA 51501

      If you live outside of the U.S., please contact me via e-mail at
      jimbo@radiks.net to work out details.

      You may also register electronically via RegSoft.  Please refer
      to the appropriate link on my shareware web page:

         http://www.radiks.net/jimbo/share.html


   *-- Upgrading from a prior version of ENVY

      As a registered ENVY user, you are entitled to a free upgrade
      to the next major release of envy ( and all minor releases
      in between. )

      Subsequent versions of ENVY will have to be registered at
      the regular price of $20.

      If you feel you are entitled to an upgrade please contact me
      via e-mail.


   *-- Disclaimer

      I claim no responsibility nor liability for damages incurred to
      hardware / software during usage of ENVY.  Nor am I responsible
      for any monetary losses related to use of ENVY.  Use ENVY
      at your own risk.


   *-- Help!  What to do if you encounter problems.

      If you encounter problems using ENVY, please report the
      problem to me via e-mail.


   *-- Technical Specifications

      ENVY was written in Visual C++ 1.52 and was compressed
      with LZEXE.



   *-- Distribution

      You may not resell ENVY, but you may include it on media
      such as CD-ROM shareware collections.  You may also upload it
      to any BBS or place it on any FTP site or Web page.

      If you would like to bundle ENVY with a commercial application
      please contact me to negotiate a licensing agreement.


