home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / batch / errlvl12.zip / ERRLVL.DOC < prev    next >
Text File  |  1991-10-15  |  6KB  |  176 lines
  1.  
  2.  
  3.                                 ERRLVL, v1.2
  4.                                 -------------
  5.                                 from TifaWARE
  6.  
  7.  
  8.  
  9.  
  10. What's New
  11. ----------
  12.  
  13.  
  14.      New to version 1.2 is support for DOS v4.0 and v5.0. This required a
  15. new approach to locating the ERRORLEVEL. Adding support for other versions
  16. will be easy once the magic offsets are known.
  17.  
  18.      With version 1.1, I have substantially reorganized ERRLVL's source
  19. code, placing commonly-used procedures, equates, and macros in separate
  20. files. Sharing code in this way will make it my programming task easier.
  21. From the user's point of view, however, there's no change. 
  22.  
  23.      Version 1.0 was the first public release of ERRLVL.
  24.  
  25.  
  26.  
  27.  
  28. Introduction
  29. ------------
  30.  
  31.  
  32.      ERRLVL is a simple hack to display the return code from whatever
  33. program COMMAND.COM ran before. Use it when you'd like to know the actual
  34. return code but don't want to bother with statements like:
  35.  
  36.           if ERRORLEVEL 255 echo 255
  37.           if ERRORLEVEL 254 echo 254
  38.           if ERRORLEVEL 253 echo 243
  39.           ...
  40.           if ERRORLEVEL 1   echo 1
  41.  
  42. (Geez, why'd Microsoft do it this way?) Additionally, ERRLVL preserves the
  43. value of ERRORLEVEL so you can use it in batch files to maintain detailed
  44. logs of program usage.
  45.  
  46.  
  47.  
  48.  
  49. Usage
  50. -----
  51.  
  52.  
  53.      Running ERRLVL is straightforward. Once you've placed the program
  54. where DOS can find it, type ERRLVL -? to display a brief help message
  55. similar to the following:
  56.  
  57.      TifaWARE ERRLVL, v1.2a, 12/28/90 - displays previous ERRORLEVEL.
  58.      Usage: errlvl [-options] [msg]
  59.      
  60.      Options:
  61.        -? = display this help message
  62.      
  63.      msg is an optional message to display before the errorlevel.
  64.  
  65. [If you don't remember anything else, at least remember how to display
  66. this help message.]
  67.  
  68.      Typically you'll invoke ERRLVL without arguments. As long as your
  69. shell is COMMAND.COM from a supported version of DOS, ERRLVL will display
  70. the errorlevel; ie, the return code from the preceding program. Also, you
  71. can prefix this with a message, say, to keep track of return codes from a
  72. particular program.
  73.  
  74.  
  75.  
  76.  
  77. If You Have Any Trouble
  78. -----------------------
  79.  
  80.  
  81.      ERRLVL will let you know of any problems that arise. Here are the
  82. messages you might see and how you should deal with them:
  83.  
  84.      errlvl: invalid option -- x.
  85.           - Type "ERRLVL -?" for a list of valid options.
  86.  
  87.      errlvl: unable to locate errorlevel.
  88.           - Make sure you're using COMMAND.COM as the parent 
  89.             shell and that it's from a supported version of 
  90.             DOS. 
  91.  
  92. These messages are written to the standard error device. In this way, they
  93. won't disappear down a pipe or into a file should you redirect ERRLVL's
  94. output.
  95.  
  96.      Additionally, ERRLVL exits with the same return code as the previous
  97. program. That is, it preserves the errorlevel. The only exceptions occur
  98. when help is given (return code will be 1) or when the errorlevel cannot
  99. be located (return code will be 10).
  100.  
  101.  
  102.  
  103.  
  104. Requirements
  105. ------------
  106.  
  107.  
  108.      TifaWARE ERRLVL runs on PC-compatible machines operating under DOS
  109. v3.30, v4.0, and v5.0. It requires only 1K of memory. Running it under
  110. 4DOS, MKS Toolkit, or some other COMMAND.COM replacement will not harm
  111. anything, but the value displayed will probably be meaningless.
  112.  
  113.      Adding support for other versions of DOS is fairly easy. You'll need
  114. to figure out where COMMAND.COM stores the errorlevel, and for this you
  115. can use the accompanying program FINDELVL. Issue the following commands:
  116. "findelvl | findelvl 145 147 | findelvl 147 148 | sort > findelvl.out" and
  117. scan the output. With luck it will contain one pair of matching values -
  118. the magic spot - plus a bunch of unique ones. [Refer to FINDELVL.C if it
  119. doesn't.]  Once you've uncovered this spot, you can either modify
  120. ERRLVL.ASM (search for ErrLocTbl) and recompile it yourself or contact me.
  121.  
  122.  
  123.  
  124. Who Owns It?
  125. ------------
  126.  
  127.  
  128.      I am releasing this program into the public domain. Since 1984 I have
  129. used public-domain software extensively, and I find it to be a terrific
  130. idea. Most programs are useful, and the source instructive. And they cost
  131. nothing! With this small contribution to the public domain I hope to pay
  132. back my gratitude to those other programmers who have made my computing so
  133. much easier.
  134.  
  135.      However, this program carries no obligation on my part to support
  136. users or provide future upgrades. I try to write clean code and believe it
  137. is "bug-free". Nevertheless, use this program ***AT YOUR OWN RISK***. Scan
  138. the source yourself, make any desired changes, and recompile the program,
  139. if possible. Make this standard practice with newly-acquired software and
  140. you'll not only protect your system from viruses but also get a better
  141. feel for exactly how programs work!
  142.  
  143.      As author of this program, I have two requests: First, please keep
  144. together the original source code, documentation, and executable if you
  145. distribute the package. This just makes it easier for others to use the
  146. software. Second, let me hear what you think of it - I'd appreciate a
  147. postcard with your comments. Enjoy!
  148.  
  149.  
  150.  
  151.  
  152. Kudos
  153. -----
  154.  
  155.  
  156.      Many thanks go to Borland for its stand-alone debugger, which greatly
  157. reduced the time spent developing this program. Thanks are also due to
  158. Josep Fortiana Gregori (D3ESJFG0@EB0UB011 on BITNET) who supplied a code
  159. fragment suggesting how to find ERRORLEVEL in RAM and to Yan Juras for
  160. pointing out where exactly to look.
  161.  
  162.  
  163.  
  164.  
  165.  
  166.                           George A. Theall
  167.  
  168.                              TifaWARE
  169.                        506 South 41st St., #3M
  170.                       Philadelphia, PA.  19104
  171.                               U.S.A.
  172.  
  173.                          +1 215 662 0558
  174.  
  175.                theall@gdalsrv.sas.upenn.edu (Internet)
  176.