home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast.iso / pathutil / desetp12.zip / FINDENV.DOC < prev    next >
Text File  |  1991-09-07  |  10KB  |  189 lines
  1.                                     FINDENV
  2.                                     
  3.                A utility for finding the DOS active environment
  4.                         (Version 1.0 - February 24, 1990)
  5.            Copyright (c) Donald E. Ekman 1990.  All rights reserved.
  6.            
  7.  
  8. FINDENV locates the active DOS environment and displays its location, size,
  9. free space, and contents on the screen.  As the display is generated, the 
  10. string-terminating nulls are replaced with a visible character.  FINDENV has
  11. been tested with DOS Versions 2.01 through 3.3, 4.01 and 5.0; it has not been
  12. tested with Version 4.0.  Because FINDENV uses undocumented features of DOS to
  13. find the active environment, its correct operation for versions of DOS with
  14. which it has not been tested is not assured.
  15.  
  16.  
  17. USAGE
  18.  
  19. FINDENV is invoked by the command line:
  20.  
  21.      FINDENV
  22.      
  23.  
  24. MESSAGES
  25.  
  26. FINDENV first displays a copyright notice, followed by the location of the
  27. active environment, its size, the amount used, and the free space.  The
  28. contents of the environment are then displayed, with the string-terminating
  29. nulls presented as visible characters.
  30.  
  31. There are no error messages.  FINDENV might be made more robust in a variety
  32. of ways.  For example, during the recursive pointer chasing to find the active
  33. shell, a count of pointers might be kept, with some sort of exit if the count
  34. exceeds some reasonably large value.
  35.  
  36.  
  37. NOTES
  38.  
  39. It might seem that FINDENV has little utility.  Certainly its output is not
  40. remarkably entertaining.  It's real utility is in providing a means for finding
  41. the active DOS environment, thus making various other programs possible, such
  42. as SETPATH, which permits path environment variables longer than 128 bytes to
  43. be inserted into the environment.  It is also useful for verifying that SETPATH
  44. works properly with MS-DOS 5.0.  In that version of DOS, the SET and PATH
  45. commands, when used to display environment variables, refuse to display any more
  46. than the first 128 bytes of any variable.  Since the command line buffer size
  47. ordinarily prevents one from setting variables any longer than that, DOS 5.0
  48. doesn't bother to try to display more than the first 128 bytes.
  49.  
  50. There are a number of methods in general use for finding the DOS environment.
  51. Not all of these methods are reliable, and not all distinguish between the root
  52. environment and the active environment.  That having been stated, some
  53. definitions are in order.
  54.  
  55. The active environment is that copy of the environment that is associated with
  56. the currently active command processor (normally COMMAND.COM), and of which a
  57. copy is passed to programs by that command processor.   This environment  stores
  58. the current path, prompt, and comspec environment variables, along with any
  59. other environment variables created with the SET command.
  60.  
  61. When the command processor causes a program to be loaded for execution, it
  62. creates a copy of the active environment and passes it to the program to be
  63. executed.  This program environment is ephemeral;  when the program terminates,
  64. the program environment disappears.   A program is given the  address of its
  65. program environment through its Program  Segment Prefix (PSP).  The word at
  66. offset 2C in the PSP contains the segment address of the program environment.
  67. (The address offset is always zero and so is not included in the PSP.)  A 
  68. program may, using documented features of DOS, operate on its program 
  69. environment.  (A program may not, using only documented DOS features, gain
  70. access to the active environment, however.)
  71.  
  72. There may or may not be a third environment, which may be called the root
  73. environment.  This is the environment that is set up when the system boots.
  74. Ordinarily this is identical to the active environment.  However, if you 
  75. invoke a secondary command processor, the environment inherited by that
  76. secondary command processor is the active environment, and is a copy of the
  77. root environment.  It is this copy that is passed to programs, and which
  78. controls the active path.  Thus it is the active environment that we want to
  79. find, and the active environment is not necessarily the root environment.
  80.  
  81. To locate the active environment FINDENV first finds the active command
  82. processor (normally COMMAND.COM).  It then finds its environment, which
  83. is by definition the active environment.  Both steps involve using features
  84. of DOS that are not officially documented.  This means that what works with
  85. current versions of DOS may not work for subsequent versions.  However, it
  86. should be noted that the techniques used to find the active environment in
  87. DOS 5.0 haven't changed since DOS 3.3.
  88.  
  89. An environment is simply a memory block.  In DOS, memory is allocated in groups
  90. of (16-byte) paragraphs, aligned at paragraph boundaries, called memory blocks.
  91. Each memory block contains a 16-byte header called the Memory Control Block
  92. (MCB) for that memory block.  In DOS Versions through 3.3, only the first 5
  93. bytes out of 16 are used.  The first byte contains a MCB identifier in the
  94. form of the letter M for all but the last memory block, for which the letter Z
  95. is used as the identifier.  (The M and Z, which also show up as a signature in
  96. .exe files, are said to be the initials of Mark Zbikowski, one of the authors of
  97. DOS 2.0.)  DOS uses these bytes to verify the integrity of the memory
  98. allocation.
  99.  
  100. The 2nd and 3rd bytes of the MCB contain the segment address of the owner of the
  101. memory block.  That is, these bytes contain the segment address of the PSP of
  102. the program that requested the block.  This segment address is stored in the
  103. usual way words are stored in Intel architecture: low-order part in byte 2,
  104. and high-order part in byte 3.  If a program deallocates memory located in the
  105. middle of the MCB chain, DOS changes bytes 2 and 3 in the MCB to zeros.  This
  106. memory block is then available for other uses.
  107.  
  108. Bytes 4 and 5 of the MCB contain the number of 16-byte paragraphs in the memory
  109. block.  The count does not include the size of the MCB.  Using this information,
  110. DOS can trace through the chain of MCBs.  To find the first MCB, it uses the
  111. undocumented DOS service 52h.  It calls interrupt 21 with AH=52; on return,
  112. ES:(BX-2) contains a pointer to the first MCB.
  113.  
  114. Starting with DOS 4.0, the last eight bytes of the MCB contain the name of the
  115. program that owns the block.  In DOS 5.0, the memory arena may also include
  116. Upper Memory Blocks (UMBs).   (The DOS allocation method call includes or
  117. excludes UMBs.  UMBs are those available blocks of memory between 640k and
  118. 1 meg.)  If UMBs are included, the 16 bytes at the end of the regular memory
  119. will contain an MCB to skip over video or other memory to the first UMB area.
  120.  
  121. FINDENV completes the first step--locating the active command processor--by
  122. noting that offset 16h of the PSP points to the PSP of the parent of the
  123. current process. The pointer points to itself when the active command processor
  124. is reached.
  125.  
  126. Having found the PSP of the active command processor, FINDENV can then locate
  127. the active environment, but doing so is DOS-version-dependent.  FINDENV looks at
  128. offset 2C in the PSP of the active command processor.  If the active command
  129. processor is the root command processor, the word at 2C is 0, and the active
  130. environment is the memory block after the command processor, regardless of the
  131. DOS version.
  132.  
  133. If the active command processor is not the root command processor, then the
  134. location of the active environment is version dependent.  The active command
  135. processor is a program,  and so has its own program environment.   For DOS 3.1
  136. and earlier, this program environment is also the active environment.  For
  137. versions 3.2 and later, the active command processor places a memory block
  138. immediately following itself, which contains the active environment.  It does
  139. not use the program environment.
  140.  
  141. For DOS versions 3.2 and earlier, offset 2C points to the program environment.
  142. For versions 3.3 and later, offset 2C points to the active environment.  While
  143. the placing of the active environment was changed with version 3.2, the address
  144. in 2C changed only in version 3.3.  This curiosity accounts for the testing
  145. of the variables _osmajor and _osminor in the FINDENV code.  The active
  146. environment is the next block in memory if offset 2C=0 or if the DOS version is
  147. 3.2.  Otherwise, the active environment is pointed to by 2C.
  148.  
  149. Having located the active environment, FINDENV uses a simple  MCB calculation
  150. to determine the size of the environment.   To determine the amount in use,
  151. FINDENV notes that the strings are stored with a single ASCII zero terminating
  152. each, and a double ASCII zero at the end of all strings.  A scan for a double
  153. zero locates the end of the used part of the environment.  Subtraction gives
  154. the amount free.
  155.  
  156.  
  157. PROGRAMMING
  158.  
  159. FINDENV was written in C, and compiled with the Microsoft C Version 5.10
  160. compiler, and linked with the Microsoft Version 5.03 linker.  The small memory
  161. model was used, which required careful treatment of the environment space,
  162. which is accessible only  with far pointers.  The code is not robust; no
  163. error checking is performed.  As to style, that is a matter for individual
  164. evaluation.
  165.  
  166.  
  167. LICENSE
  168.  
  169. You may use this program and distribute it freely, provided that no charge is
  170. made for its distribution, and all copyright notices are retained.  The general
  171. information for which the code is illustrative maybe used in derivative works.
  172.  
  173. The techniques of which the code is exemplary may, of course, be freely used in
  174. other software.  However, the actual code may not be used in any derivative work
  175. without the express permission of the author.  (Besides, you can certainly write
  176. better code than this.)
  177.  
  178. If you distribute this program, please keep this documentation file with it
  179. in some archived form.  Comments and suggestions for improvement should be
  180. sent to:
  181.  
  182.             Donald E. Ekman
  183.             3586 Berry Way
  184.             Santa Clara, CA  95051-1902
  185.             
  186.             Internet:  ekman@wdl30.wdl.loral.com
  187.                        ekman@ssd168.ssd.loral.com
  188.  
  189.