home *** CD-ROM | disk | FTP | other *** search
/ Otherware / Otherware_1_SB_Development.iso / amiga / utility / cli / shelltim.lzh / ShellTimer.doc < prev    next >
Encoding:
Text File  |  1992-02-04  |  11.2 KB  |  345 lines
  1.  
  2.                                 ShellTimer
  3.  
  4.                                    by
  5.                               John Lindwall
  6.  
  7.                            4138 Illinois St #8
  8.                            San Diego, CA 92104
  9.  
  10.                            johnl@crash.cts.com
  11.  
  12.                                3 Feb 1992
  13.  
  14.  
  15. Quick Description
  16. =================
  17.  
  18. ShellTimer is a multitasking-friendly shell-based stopwatch program.  It is
  19. useful  when  you need to measure the amount of time taken by an operation.
  20. With this simple shell command you can start a timer and later stop it; the
  21. elapsed time will be displayed.
  22.  
  23. ShellTimer  can  be  useful  to  time  compile/link operations, renderings,
  24. program  executions,  script  files,  etc.   Since  it  is shell-based, the
  25. command  can  be  invoked  from  AmigaDOS  scripts, from Arexx macros, from
  26. makefiles, or interactively.
  27.  
  28. This program requires AmigaDOS 2.04.
  29.  
  30. If you want to try it out without reading this whole document, type
  31.  
  32. 1> ShellTimer HELP
  33.  
  34. at  the  shell prompt, and you'll see the help message.  You should be able
  35. to  figure  things  out from there.  Note that the program ShellTimerDaemon
  36. must be available (IE in your current directory or path).
  37.  
  38. ShellTimer does not run from WorkBench.
  39.  
  40. The  ShellTimer  system  (which  includes the programs ShellTimerDaemon and
  41. ShellTimer)  is  released  into  the  Public  Domain  by  the  author, John
  42. Lindwall.   I  ask  that  the  archive be kept intact with the docs and the
  43. source  code.   Bug  reports should be sent to me at johnl@crash.cts.com or
  44. the address above.
  45.  
  46. Source  code is included.  The compiler I use is SAS/C 5.10b.  My editor is
  47. TurboText.  My machine is an A1000 with 2.75MB RAM and an 80 MB hard disk.
  48.  
  49.  
  50. Requirements
  51. ============
  52.  
  53. ShellTimer  and  ShellTimerDaemon require AmigaDOS 2.04.  The programs make
  54. use  of  features  specific  to  this  OS  version,  including  local shell
  55. environment   variables,   ReadArgs(),   AllocVec(),  CreateMsgPort(),  and
  56. System().
  57.  
  58. The  programs  could  be  modified  to  run under 1.3, but I don't have the
  59. inclination.
  60.  
  61.  
  62. ShellTimer Guts
  63. ===============
  64.  
  65. The  ShellTimer  system  is  comprised  of  two  programs,  ShellTimer  and
  66. ShellTimerDaemon.   These  two program act together, as client (ShellTimer)
  67. and  server  (ShellTimerDaemon),  to perform the timing function.  You must
  68. have both programs to use this system.
  69.  
  70. ShellTimer  is  your  interface  to the timing functions.  It allows you to
  71. start  a  timer, stop a timer, query the current value of a timer, cancel a
  72. timer session, and terminate the server.
  73.  
  74. ShellTimerDaemon  runs  quietly in the background waiting for requests from
  75. the  client.  ShellTimer depends on ShellTimerDaemon, so it must be running
  76. in  your  system  for  the  timing  functions to work.  ShellTimerDaemon is
  77. well-behaved and doesn't consume much system RAM.
  78.  
  79. ShellTimerDaemon does not recognize any arguments.
  80.  
  81. You  can  start up ShellTimerDaemon from your S:user-startup file by adding
  82. the line:
  83.  
  84. run <NIL:  >NIL:  ShellTimerDaemon
  85.  
  86. You  can  also start it up by dropping the ShellTimerDaemon's icon into the
  87. WBStartup drawer.
  88.  
  89. Of course, you can manually start the daemon from the shell or WorkBench.
  90.  
  91. Note that you do NOT have to explicitly start up ShellTimerDaemon at all if
  92. you  don't  want  to.   When ShellTimer is invoked with a valid command, it
  93. checks   to   see   if   ShellTimerDaemon   is   currently   running.    If
  94. ShellTimerDaemon is not located, ShellTimer will try to invoke it.  All you
  95. have to do is place ShellTimerDaemon in a directory contained in your path.
  96.  
  97. The ShellTimerDaemon continues to run in the background until it receives a
  98. QUIT  command from ShellTimer.  The AmigaDOS Break command can also be used
  99. to terminate the daemon by sending it a Control-C.
  100.  
  101. ShellTimerDaemon is not a Commodity, so don't look for it in the Exchange.
  102.  
  103.  
  104. Simple Usage
  105. ============
  106.  
  107. The  main use of ShellTimer is to allow the user to start and stop a timer,
  108. and  view  the  elapsed  time.  This is a simple operation; no command line
  109. arguments are required.
  110.  
  111. Typing
  112.  
  113. 1> ShellTimer
  114.  
  115. at  the  shell  prompt will start the timer.  Typing it again will stop the
  116. timer and display the elapsed time.  For example:
  117.  
  118. 1> ShellTimer
  119. 00:00:04
  120.  
  121. The  elapsed  time  is usually expressed in the form HH:MM:SS.  If a day or
  122. more  has  passed,  the  format  is  DD HH:MM:SS, where DD is the number of
  123. elapsed days.  No finer resolution then a second is supplied.
  124.  
  125. When  ShellTimer  is invoked with no arguments, it asks the daemon if there
  126. is a pending (previously started) timer session.  If not, the daemon starts
  127. a  new  session by recording the current time.  If there IS a pending timer
  128. session,  the daemon terminates the session, computes the elapsed time, and
  129. instructs  the  client  to  print  the  result.  In this manner, successive
  130. invocations  of  ShellTimer toggle between starting the timer, and stopping
  131. the timer.
  132.  
  133. Note that the daemon tracks timer sessions on a shell-by-shell basis.  This
  134. means  that  you can start timer sessions in several shell windows and each
  135. one  is  maintained  independently.   You cannot, for example, stop a timer
  136. session  initiated  in  shell  #1  by issuing a STOP command from shell #2.
  137. Shell  #2  can only affect IT'S own timer session.  (The daemon records the
  138. shell's process number along with the associated timing information).
  139.  
  140.  
  141. Advanced Usage
  142. ==============
  143.  
  144. Here is the template for ShellTimer:
  145.  
  146. ShellTimer START/S,STOP/S,CANCEL/S,QUIT/S,HELP/S,V=VERBOSE/S,Q=QUERY/S
  147.  
  148. START   - Initiates a timer session.  The current timer request is cancelled
  149.           (if one is pending) and a new one is started.
  150.  
  151. STOP    - Stops the timer and prints the elapsed time (STOP - START).
  152.           Unlike a real stopwatch, you cannot continue timing after
  153.           stopping the timer.  You have to START the timer anew.
  154.  
  155. CANCEL  - Aborts the current timer session.
  156.  
  157. QUIT    - Causes the daemon to quit.  Any pending timer sessions are lost.
  158.           Use this command if you want to kill the ShellTimerDaemon program.
  159.  
  160. HELP    - Displays a help message.
  161.  
  162. VERBOSE - Causes all output to be more wordy.  The default is to be terse.
  163.           In verbose mode, all commands are acknowledged with a printed
  164.           reply.  Furthermore, the format of the printed elapsed time is
  165.           changed.  The terse default format is [DD] HH:MM:SS.  The
  166.           verbose format is
  167.           Timer stopped - Elapsed Time: D Day, HH Hours, MM Minutes, SS Seconds
  168.           Verbose mode tries to generate smart and readable output.
  169.  
  170. QUERY   - Print the current elapsed time, without cancelling the session.
  171.           This is used to check the amount of time that has passed without
  172.           stopping the timer.
  173.  
  174. The  basic commands are START, STOP, CANCEL, QUIT, HELP, and QUERY.  Supply
  175. only  one  of  these  commands on each invocation.  The VERBOSE flag can be
  176. supplied along with the command if you'd like verbose output.
  177.  
  178. As mentioned in the "Simple Usage" section you need not supply any command.
  179. Successive  invocations  of ShellTimer toggle between starting and stopping
  180. the timer.
  181.  
  182.  
  183. Example Usage
  184. =============
  185.  
  186. Interactive Example -------------------------------------------------
  187.  
  188. The following lines show various ways that ShellTimer can be invoked from
  189. the Shell:
  190.  
  191. 1> ShellTimer
  192. 1> ShellTimer
  193. 00:01:23
  194.  
  195.  
  196. 1> ShellTimer
  197. 1> ShellTimer VERBOSE
  198. Timer stopped - Elapsed Time: 2 Seconds
  199.  
  200.  
  201. 1> ShellTimer START VERBOSE
  202. Timer started
  203. 1> ShellTimer QUERY VERBOSE
  204. Timer Query - Current elapsed time: 45 Seconds
  205. 1> ShellTimer QUERY
  206. 00:01:05
  207. 1> ShellTimer STOP
  208. 00:01:27
  209.  
  210.  
  211. 1> ShellTimer VERBOSE
  212. Timer started
  213. 1> ShellTimer CANCEL
  214. Timer cancelled
  215. 1> ShellTimer STOP
  216. No pending timer request
  217.  
  218.  
  219.  
  220. 1> ShellTimer QUIT
  221. ShellTimerDaemon unloaded
  222.  
  223.  
  224. Makefile Example-----------------------------------------------------
  225.  
  226. You can use ShellTimer to time compiles and links invoked from a Makefile.
  227. Here's a simple example:
  228.  
  229. foo: foo.c
  230.     @ShellTimer Start
  231.     lc -L foo.c
  232.     @echo "Time required for compile and link " NOLINE
  233.     @ShellTimer Stop
  234.  
  235.  
  236. ARexx Example -------------------------------------------------------
  237.  
  238. You can also invoke ShellTimer from ARexx macros (via AmigaDOS, not
  239. directly).  Here's a semi-lame example - I used this script to test memory
  240. consumption of the program:
  241.  
  242. /* Test ShellTimer programs */
  243.  
  244. address command
  245.  
  246. do forever
  247.     shelltimer verbose
  248. end
  249.  
  250.  
  251. AmigaDOS Script Example ---------------------------------------------
  252.  
  253. You can invoke Shelltimer from AmigaDOS script files as well.  If you look
  254. at the top of the two source files, ShellTimer.c and ShellTimerDaemon.c,
  255. you'll see that an AmigaDOS script file is embedded there, resembling the
  256. following:
  257.  
  258. ;/* Execute me to Compile and link ShellTimer.c
  259. shelltimer start verbose
  260. lc -. -O -ms -b1 -cfistq -j73 -Lit -tr ShellTimer.c
  261. echo "Time to compile and link: " NOLINE
  262. shelltimer stop
  263. quit
  264. */
  265.  
  266. The idea of embedding the compile/link commands in the C file is borrowed
  267. from the examples given by CATS programmers in their AmigaMail articles.
  268.  
  269.  
  270. Miscellaneous Notes
  271. ===================
  272.  
  273. 1. ShellTimer is pure, and can be made resident.
  274.  
  275. 2. If you're going to use ShellTimer a lot, set up an alias like so:
  276.  
  277.    alias ST ShellTimer
  278.  
  279.    or if you prefer wordy output try:
  280.  
  281.    alias ST ShellTimer verbose
  282.  
  283.    These aliases go in your shell-startup file.  (It can get tedious typing
  284.    'ShellTimer' all of the time).
  285.  
  286.    Alternately, you can safely rename ShellTimer to whatever you like.
  287.    However, if you rename  ShellTimerDaemon,  then ShellTimer will no
  288.    longer be able to automatically start it up.
  289.  
  290. 3. The AmigaDOS 2.0 VERSION command can be used on the ShellTimer and
  291.    ShellTimerDaemon executables.
  292.  
  293. 4. This program doesn't work reliably with the backtick feature of 2.0.
  294.    The problem is that timer sessions are identified by the Process ID
  295.    of the calling Shell.  When backticks are encountered in a shell
  296.    command a new shell is invoked to execute the command.  If your system
  297.    has a lot of shell activity going on you may not have the same Shell
  298.    ID for each backtick expression.
  299.  
  300.  
  301. Code Notes
  302. ==========
  303.  
  304. This archive should include the source code for the ShellTimer system.  The
  305. source files are
  306.  
  307.      ShellTimer.c
  308.      ShellTimerDaemon.c
  309.      ShellTimer.h
  310.  
  311. I  use  SAS/C  5.10b.   My Manx compiler is out of date (3.6a) and so won't
  312. compile the ANSI stuff, so I made no effort to be portable (or non-portable
  313. for that matter).
  314.  
  315. The compile/link commands are embedded at the top of each C file.  To build
  316. the programs type
  317.  
  318. 1> execute ShellTimer.c
  319. 2> execute ShellTimerDaemon.c
  320.  
  321. The program are fairly simple.  Comments are minimal - sorry.  Feel free to
  322. make  fixes or enhancements.  I'd appreciate being contacted if you do some
  323. neat  stuff  with  the code (see my addresses at the top of this document).
  324. I'm happy to fix any bugs you'd care to report.
  325.  
  326.  
  327. Dedication
  328. ==========
  329.  
  330. The ShellTimer system is dedicated to my loving wife, Deanne.
  331.  
  332. The  inspiration  for this program came from a series of discussions with a
  333. friend  at  work, Steve Harris.  He is a fan of OS/2 and was thinking about
  334. writing  a  similar  program  for that OS.  (We use a similar type of timer
  335. program under MS-DOS to time our 'makes').  I figured that I'd like to have
  336. a ShellTimer for my Amiga...  so here it is.
  337.  
  338.  
  339. Version History
  340. ===============
  341.  
  342. 1.0     Initial release of ShellTimer and ShellTimerDaemon. JWL 03 Feb 1992
  343.  
  344. End of ShellTimer.doc
  345.