home *** CD-ROM | disk | FTP | other *** search
/ Black Box 4 / BlackBox.cdr / dosutils / batlog10.arj / BATLOG.DOC next >
Text File  |  1991-11-24  |  11KB  |  228 lines
  1.  
  2.      BATLOG 1.0
  3.  
  4.      FlatLand Software
  5.      Tracy Mickley
  6.      Copyright 1991
  7.  
  8.      Batlog was designed to aide debugging and logging activity of complex 
  9. DOS batch files. Batlog will create a running ASCII text file named BATLOG.LOG
  10. and log your activity each time it is run. Batlog will also execute a *.EXE or
  11. *.COM file and log the 'shelled' program DOS ERRORLEVEL upon termination. In 
  12. addition Batlog will log, upon request, available drive space and directory 
  13. listings.
  14.  
  15.      WARRANTY
  16.  
  17.      There is no warranty expressed or implied. FlatLand Software will assume
  18. no liability for any damages or loss of use to your hardware, software or data
  19. through your use of Batlog. 
  20.  
  21.      OPERATION
  22.  
  23.      You insert Batlog with it's command line switches and comments into your
  24. batch files to track it's progress and to create an audit trail for later
  25. review. Simply type Batlog followed by optional command line switches along
  26. with any comment you want included in the batlog.log file. The optional command line
  27. switches can be placed anywhere on the command line. I tend to put them after
  28. the comments I want logged since it makes it easier to read the comments later. Run
  29. BATLOG a couple times, look at the BATLOG.LOG output file and you'll see it is
  30. a simple program to run and use constantly. A brief help screen will be
  31. displayed when you enter BATLOG with no command line arguments.
  32.  
  33.      SWITCHES
  34.  
  35.      /A:x = available drive space left in bytes. This can be any valid
  36. drive letter. If no drive letter is specified the default drive is checked 
  37. and logged.
  38.  
  39.      /D:*.* = Directory listing is functionally similar to the DIR
  40. command in DOS with the exception that if no files argument is given,
  41. the switch is ignored. Wildcards (* and ?) are honored.
  42.  
  43.      /E:x = Errorlevel exit where x is a number from 0 to 255. This
  44. tells Batlog to return to DOS with the specified errorlevel. I haven't 
  45. figured out a real good use for this yet, but it's there if you want to 
  46. use it.
  47.  
  48.      /O:filename.ext = Optional output filename. This allows you to
  49. change the default output filename from BATLOG.LOG to any valid
  50. filename and path.
  51.  
  52.      /R:filename.ext = Runs the specified filename. This switch allows
  53. you to execute most any *.EXE or *.COM file and log the errorlevel it returns.
  54. Batlog will end with this same errorlevel. Note you must provide the full
  55. path and filename, including the extension if specified file is not in the same
  56. directory as Batlog. If the specified program is in the same directory as 
  57. Batlog, you must still use the full filename with extension. If you find a
  58. returned error level of -254, this means you didn't supply the full filename
  59. with extension. This switch will also allow command line arguments to be passed
  60. to the program being executed. 
  61.  
  62. Here's an example:
  63.  
  64. BATLOG toss the Fido mail  /r:tossmail.com -100 -.arc -new
  65.  
  66.      Now you've got a commented log file with 'toss the Fido mail' and told
  67. Batlog to execute the tossmail.com program with it's required switches. Batlog
  68. will exit with any DOS errorlevel that tossmail.com returns so it can be acted
  69. on in your batch file. See ABOUT BAT FILES for more on how to use
  70. DOS ERRORLEVELS and why this command is very useful.
  71.  
  72.      /N:filename.exe = identical to the /R: switch except that Batlog
  73. will terminate with a 0 errorlevel instead of the executed programs returned
  74. errorlevel.
  75.  
  76. Here's a typical batlog run.
  77.  
  78. BATLOG Check for existing *.bas files and run ask.exe /a: /d:*.bas /r:ask.exe
  79.  
  80. (Note: A Batlog command line can be 128 characters long and may wrap on your
  81. screen as you enter your comment and switch settings.)
  82.  
  83. Here's the sample result excerpt from the log file:
  84.  
  85. =====================================================================
  86. 10-23-1991 14:03:07
  87. Check for existing *.bas files and run ask.exe /a: /d:*.bas /r:ask.exe
  88. Disk space :4536320  bytes available on drive 
  89. Files matching :*.bas
  90. TEST2.BAS      18635 08-31-91 08:15p
  91. TEST3.BAS      22058 10-21-91 09:52p
  92. TEST1.BAS      15833 08-31-91 08:09p
  93. Execute File :ask.exe
  94. Returned from File :ask.exe with ERRORCODE 3 
  95. ERRORLEVEL set on exit is: 3 
  96. =====================================================================
  97.      
  98. The first line is the time and date of this batlog run. This will always be
  99. there in any run. The second line is the command line comment and switches.
  100. Note that you can place a comment either before or after your switch settings.
  101. The third line shows the result of the /a: switch and gives you the amount of
  102. available space on your drive. We used the default drive by not specifying a
  103. drive letter. Any valid drive letter can be used. The third line shows the
  104. result of the /d: switch. This requested a directory of all files matching the
  105. *.bas parameter. Much as you would from the command line prompt. Lines 5
  106. through  7 show which files are there. Line 8 shows that we had Batlog execute
  107. a program named ASK.EXE. Line 9 shows Batlog has resumed control and that
  108. ASK.EXE returned an errorlevel code of 3. The last line shows that Batlog then
  109. exited with an errorlevel of 3. 
  110.      ABOUT BAT FILES
  111.  
  112.      Most programs will exit a program with an ERRORLEVEL passed to DOS
  113. if the program aborts abnormally. Many programs use the DOS ERRORLEVEL
  114. as a method of communicating results of the programs execution. Often times
  115. this is documented. Often times it's not. You can use the /r: switch in 
  116. Batlog to find out which ERRORLEVELS you are getting and write your batch
  117. file to react accordingly. A lengthy explanation of how to use batch file
  118. ERRORLEVELS is beyond the scope of these doc's. Indeed many entire chapters
  119. have been devoted to it's use. I'll provide one brief example. Let's say we
  120. have a program called tossmail.com and it when it executes it will return
  121. three different ERRORLEVELS when it terminates; 0, 1 and 2. 0 in this example
  122. says it executed with no problems. 1 indicates it didn't find any mail to 
  123. toss and 2 indicates it tried to process the mail but the disk is full. Here's
  124. a small hypothetical batch file:
  125.  
  126. rem example batch file
  127. :TOP
  128. BATLOG Run the bbs program
  129. BBS.EXE
  130. BATLOG Got some mail in, now toss it /r:tossmail.com -c:\mail
  131. if errorlevel 2 goto packdisk
  132. if errorlevel 1 goto nomail
  133. if errorlevel 0 goto top
  134. :packdisk
  135. BATLOG Pack the disk to make room /a:c: /r:packdisk.exe
  136. if errorlevel 1 goto packfailed
  137. goto top
  138. :nomail
  139. BATLOG Didn't get any mail in /d:c:\mail\*.pk?
  140. goto top
  141. :packfailed
  142. BATLOG Still too full so check drive space /a:c:
  143. goto top
  144. end
  145.  
  146.      This bat runs the bbs.exe program. When the bbs program exits it falls
  147. to the next line in the batch file which is the tossmail.com program invoked
  148. from BATLOG. (Note the command line switch "-c:\mail" for tossmail.com is also
  149. passed.) Now tossmail.com exits and then BATLOG will log the error level 
  150. tossmail terminated with and will exit with the same error level. The batch
  151. file checks for the error level with the "if errorlevel" lines. If the 
  152. errorlevel is 2, the batch file jumps to the :packdisk label where the 
  153. available disk space is logged and then a packing program is run via BATLOG
  154. and then jumps back to the :top label to start it all over again. If the
  155. packdisk.exe program exits with an errorlevel of 1, it jumps to the :packfailed
  156. label and BATLOG makes note of it and checks the available space again so you
  157. can act on it later to add more into your batch file to handle this 
  158. circumstance. That's it in a nutshell but will give you an idea of how useful
  159. BATLOG can be. 
  160.  
  161. LIMITATIONS NOTE: 
  162.      The shell feature has worked with everything I've tossed at it
  163. but I'm sure there is something somewhere it won't shell out. Most likely
  164. this will be an instance where this not enough memory to invoke the child
  165. process. The /r: (shell) command does not invoke another COMMAND.COM. You 
  166. should make a point of testing all applications invoked with the /r: command
  167. before you use it in important automated routines.
  168.  
  169. SUPPORT BBS:
  170.      Support and upgrades can be found on:
  171.      
  172.      TEXT bbs   
  173.      FlatLand Software
  174.      12/24/96/14.4baud USR Dual Standard
  175.      1-701-239-6048
  176.      Fido node 288/6
  177.  
  178. REGISTRATION COST:
  179.      Registration for license is $15.00. The second license is $10.00.
  180. Additional licenses are $5 for the next 18 copies. You can register on-line on
  181. TEXT bbs using Mastercard/VISA on TEXT bbs or send check/money order to
  182. FlatLand Software. You may also mail-in a credit card registration using the 
  183. registration form at the end of this file. Company purchase orders will be
  184. honored by invoice billing. The latest version is available by disk for an
  185. additional $5.00. All registration fees are US funds.
  186.  
  187. LICENSE:
  188.      You have license to test this program for 14 days. If you find it useful
  189. and continue to use it, you need to register it. License is like a book. 
  190. This allows you to use it on one machine at a time per licensed copy. If you
  191. have it installed on more than one machine, then you need more than one license.
  192. Automated use on different machines at different times is not use like a book.
  193. Site licenses are available. Contact FlatLand Software at TEXT bbs.
  194.  
  195. FlatLand Software
  196. Tracy Mickley
  197. 3113 24 Ave SW
  198. Fargo, ND 58103 USA
  199.  
  200. Program name and version #:__________________________________
  201.  
  202. Name:_______________________________________________________
  203.  
  204. Address:____________________________________________________
  205.  
  206. City, State, Zip:___________________________________________
  207. (Province and Postal Code if Canadian)
  208.  
  209. If mail-in credit card registration:
  210. Name as it appears on card:_________________________________
  211.  
  212. Credit Card Number:_________________________________________
  213.  
  214. Expiration Date:____________________________________________
  215.  
  216. Authorized Signature:_______________________________________
  217.  
  218.      ADDENDUM: OTHER FLATLAND SOFTWARE
  219.  
  220.      Tstat - A TBBS dayfile analyzer that tracks all bbs activity.
  221.      Ustat - A TBBS user analyzer that tracks all bbs user activity.
  222.      Himess - A TBBS utility that helps to prevent message base numbers from          
  223.               exceeding 65000
  224.      Tratio - A TBBS utility that allows automated D/L bytes limits from 
  225.               upload ratios.
  226.      Tbill - Again for TBBS. Currently under development. Creates comma
  227.              delimited output files for time billing use for dBase or TDBS
  228.              programs.