
  ---------------------------------------------------------------------------

   SETENV.COM     V1.11  Copyright (c) 1996-1997 by Matthias Paul
                                                    Ubierstrae 28
                                                    D-50321 BRHL
                                                    GERMANY

   EMail: <Matthias.Paul@post.rwth-aachen.de>

   URL: http://www.rhrz.uni-bonn.de/~uzs180/mpdokeng.html

   URL: ftp://ftp.rhrz.uni-bonn.de/pub/pc/dos/misc/setenv.zip
   URL: ftp://ftp.uni-stuttgart.de/pub/systems/msdos/util/system/setenv.zip
   URL: http://www.leo.org/pub/comp/platforms/pc/msdos/utils/envutils/
   URL: ftp://ftp.leo.org/pub/comp/platforms/pc/msdos/utils/envutils/...
                                                               ...setenv.zip

   Last edit: 1997-05-24

  ---------------------------------------------------------------------------

   DISCLAIMER:

   Unintended usage may cause harmful data corruption!
   Use at your own risk!
   No warranties of any kind, neither expressed nor implied!

   Trademarks are owned by their respective owners.
                                                                             
  ---------------------------------------------------------------------------

   SETENV.COM is a small FreeWare utility, especially designed for
   DR DOS 6.0, DR PalmDOS, Novell DOS 7, and Caldera OpenDOS.
   The current version won't run under other DOS operating systems.

   The operating systems mentioned above provide a CONFIG.SYS SET=
   directive to prebuild the later environment, which is called pre-
   environment, here.  The internal handling of this pre-environment
   is rather different from the handling of the later environment
   variables in batchjobs.  It is convenient to assign variables in
   CONFIG.SYS (e.g. %CONFIG%), but on the other hand, using this
   interesting SET= feature, there are some remaining disadvantages:

   Each TSR loaded by INSTALL=/INSTALLHIGH=/HIINSTALL= will have its
   own environment, built from the current pre-environment.  But most
   TSRs never use their environment, hence this is just wasted memory.
   Since you cannot delete entries from the pre-environment as you can
   from the later environment, you may loose one or two KB of rare DOS
   memory in many advanced configurations (that is, loading many TSRs
   in CONFIG.SYS).  Some TSRs free their unused environment after the
   installation, which partially solves the problem.  But this way,
   the memory gets more and more fragmented, which still isn't optimal.

   SETENV.COM works around these problems by faking an empty environment
   to the system.  So, the kernel will give only a minimal environment
   (20-140 Bytes, depending on the calling path to the TSR, s.b.) to
   new TSRs to be installed, no matter of the actual size of the pre-
   environment!

   Since the current version of SETENV.COM does not parse command line
   options, it will toggle the detected status each time it is called.
   If the pre-environment is not empty, the first call will hide the
   current pre-environment to fake an empty environment.  The next call
   will than restore the old pre-environment, and so forth...

   SETENV.COM itself is not a TSR (terminate and stay resident program),
   which would be somewhat contra-productive in this respect...

   Using SETENV.COM, you can also clear a given pre-environment and
   rebuild it from scratch.  For this, all you have to do is hiding the
   pre-environment, and afterwards assigning a new variable to the faked
   empty environment by using the CONFIG.SYS SET= directive.  The old
   hidden pre-environment is lost this way.

   Normally, you will need SETENV.COM only to temporarily hide the pre-
   environment for the duration of TSRs to be loaded, that do not need
   any of the settings assigned to the pre-environment.  This can be
   done easily by giving one call to SETENV.COM in front of the TSR(s),
   and another call to SETENV.COM afterwards.  You can do this repeatedly
   in CONFIG.SYS.  When the pre-environment is in its normal status,
   that is 'unhidden', you can assign new values to it by using the
   CONFIG.SYS SET= directive.  When it is in the 'hidden' status, giving
   SET= would discard the hidden pre-environment, and would further rebuild
   a new pre-environment starting with the new value given by SET=.

   For maximum flexibility, SETENV.COM itself can be called by INSTALL=
   (.COM-type), but also by DEVICE= (.SYS-type), which would in fact make
   no sense for MS-DOS/PC-DOS, since these OS'es always execute DEVICE=
   directives prior to INSTALL= directives.

   Errorlevel, when called by INSTALL= etc.
   (preferred, because of the more detailed return codes):

        0 = DOS version too old (1.xx)
        1 = Pre-environment restored or empty
        2 = Pre-environment hidden
      250 = Break by Emergency-BreakOut-Hotkey
      251 = Pre-environment is full
      252 = Command processor already loaded
      253 = Pre-environment is not achievable
      254 = Unknown DR DOS version (currently unsupported)
      255 = Wrong DOS issue (MS-DOS/PC-DOS)

   Error codes, after successfully calling SETENV.COM by DEVICE=:

        0 = After installation (even on error)
    32771 = Later (this should be impossible...)
    sonst = Errorcodes by DOS

   By using the DR DOS 6.0, Novell DOS 7, and Caldera OpenDOS undocumented
   ERROR= and ONERROR= directives (please have a look at my documentation
   NWDOSTIP.TXT from MPDOSTIP.ZIP), you can test on these codes, and
   perform conditionally jumps depending on the results.

   To run SETENV.COM successfully, you may not call COMMAND.COM prior to
   the last call of SETENV.COM (which would, by using INSTALL=COMMAND.COM,
   otherwise be possible long before executing the SHELL= directive).
   The problem is here, that a executing COMMAND.COM in some way closes
   the pre-environment, which becomes unaccessable afterwards, even
   if you type EXIT again.  (This problem applies not to users of
   4DOS.COM/NDOS.COM, because these command processors do not patch or
   use "DR DOS" internal data structures as COMMAND.COM does.  However,
   although this is an advantage here, it could also be a disadvantage in
   other scenarios.)  For details, have a look at my NWDOSTIP.TXT file.

   When loading device drivers, you do not need SETENV.COM, since device
   drivers don't have an environment assigned to them.

    Example for SETENV.COM in CONFIG.SYS:

     ...
     SET test=wert
     REM The pre-environment is not empty, now.
     INSTALL=SETENV.COM
     REM Now, to the kernel the pre-environment appears to be empty.
     REM So, the following TSR will get only a minimal environment.
     INSTALL=TSR.COM
     REM This call will toggle the status of the pre-environment:
     INSTALL=SETENV.COM
     REM Opps, the old contents was restored again... :-)
     ...

   Having problems when installing SETENV.COM, you can press its
   emergency-breakout-hotkey during installation:

    <Shift>+<Ctrl>+<Alt>

   Then, SETENV.COM won't assign any changes to the system, and will show
   a message to release the hotkey for continuation of CONFIG.SYS.


   There is one more issue of optimization:

   The kernel will always pass the calling path to the TSR in an extended
   environment record (since DOS 3.1+).  SETENV.COM cannot do anything
   about it.  For minimal size of this record, you should try to truncate
   the calling path to TSRs as much as possible.  Without moving the files
   on your harddisk, you can do so by using temporarily assignments to
   SUBST-drives.  Since LASTDRIVE= has not yet come to effect in CONFIG.SYS
   (despite from MS-DOS 7), you don't have much drive letters to select
   from.  But you can in fact override already assigned drive letters by
   SUBST!  At first attempt, I would try to use drive B: for this, since
   you will normally boot from A: or C:, not B:, so B: is normally unused
   during the boot (even if you'd have a floppy B: installed).

    Example for SUBST.EXE in CONFIG.SYS to install a TSR, located in
    "c:\dir1\dir2\dir3\dir4\dir5\tsr.com":

     ...
     INSTALL=c:\nwdos\subst.exe b: c:\dir1\dir2\dir3\dir4\dir5
     INSTALLHIGH=b:tsr.com
     INSTALL=c:\nwdos\subst.exe b: /D
     ...

   This way, you can save another 25 bytes (used for the string
   "\dir1\dir2\dir3\dir4\dir5") in this example.  Doing this all
   over CONFIG.SYS and AUTOEXEC.BAT, you can easily save a KB, maybe more.


   Of course, you can combine both optimization methods to get the
   absolute minimal environment for TSRs:

             16 bytes for the MCB-header
           +  2 bytes for an empty environment by using SETENV.COM
                      (just an end-marker 0)
           +  2 bytes for count of following strings (normally one)
           + 14 bytes for a minimal filespec (B:12345678.ABC)
           +  1 byte  end-marker of filespec (0)
          -----------
             35 bytes, which need 48 bytes because of the allocation
                      scheme by paragraphs  16 bytes.

                      To be accurate:

                      For filespecs shorter than 6 chars, the amount of
                      memory used for it would be 7..11 bytes, which
                      would result in 28..32 bytes total, fitting in
                      2 paragraphs.  This way, you would save another
                      16 bytes...

                      I propose new INSTALL /E /Z[:mode] /D[:letter] = ...
                      options to implement all these features directly
                      in future releases of Caldera OpenDOS.  This is,
                      what I think of:

                      /E[:region] to let the kernel assign the environment
                         in higher memory than the TSR itself (like /E
                         from PTS/DOS), which would avoid fragmentation
                         of memory, after freeing the environment.

                      /Z[:mode] to include SETENV.COM's functionality
                         in the DOS kernel (/Z='z'ero-environment)

                      /D[:letter] for the optimization using temporarily
                         assigned 'SUBST'-drives.

   Summary:

   By using SETENV.COM you can save some KiloBytes of rare DOS memory
   (typically amounting to 1-3 KByte with many advanced system
   configurations), depending on the number of drivers loaded by
   INSTALL=/INSTALLHIGH=/HIINSTALL= and the current size of the
   pre-environment.  Paradoxically, you won't get that much in less
   advanced or otherwise less optimized configurations, because
   normally you won't have that many TSRs loaded in CONFIG.SYS then.

   Since SETENV.COM is very easy to use and changes to CONFIG.SYS can
   be done in some minutes, there is no reason, why not to optimize your
   configuration.  If your TSRs do not need their environment, there is
   absolutely no compatibility problem; if they do, some of them might
   complain, that's all.  Mind, how much effort has to be done or money
   has to be spend to get some KiloByte reduced size by extreme code
   optimizations or improved memory managers...

   So far, this original SETENV.COM feature cannot be found in any known
   memory manager/optimizer.


   Have fun,

    Matthias Paul


  ---------------------------------------------------------------------------

