ShellTimer by John Lindwall 4138 Illinois St #8 San Diego, CA 92104 johnl@crash.cts.com 3 Feb 1992 Quick Description ================= ShellTimer is a multitasking-friendly shell-based stopwatch program. It is useful when you need to measure the amount of time taken by an operation. With this simple shell command you can start a timer and later stop it; the elapsed time will be displayed. ShellTimer can be useful to time compile/link operations, renderings, program executions, script files, etc. Since it is shell-based, the command can be invoked from AmigaDOS scripts, from Arexx macros, from makefiles, or interactively. This program requires AmigaDOS 2.04. If you want to try it out without reading this whole document, type 1> ShellTimer HELP at the shell prompt, and you'll see the help message. You should be able to figure things out from there. Note that the program ShellTimerDaemon must be available (IE in your current directory or path). ShellTimer does not run from WorkBench. The ShellTimer system (which includes the programs ShellTimerDaemon and ShellTimer) is released into the Public Domain by the author, John Lindwall. I ask that the archive be kept intact with the docs and the source code. Bug reports should be sent to me at johnl@crash.cts.com or the address above. Source code is included. The compiler I use is SAS/C 5.10b. My editor is TurboText. My machine is an A1000 with 2.75MB RAM and an 80 MB hard disk. Requirements ============ ShellTimer and ShellTimerDaemon require AmigaDOS 2.04. The programs make use of features specific to this OS version, including local shell environment variables, ReadArgs(), AllocVec(), CreateMsgPort(), and System(). The programs could be modified to run under 1.3, but I don't have the inclination. ShellTimer Guts =============== The ShellTimer system is comprised of two programs, ShellTimer and ShellTimerDaemon. These two program act together, as client (ShellTimer) and server (ShellTimerDaemon), to perform the timing function. You must have both programs to use this system. ShellTimer is your interface to the timing functions. It allows you to start a timer, stop a timer, query the current value of a timer, cancel a timer session, and terminate the server. ShellTimerDaemon runs quietly in the background waiting for requests from the client. ShellTimer depends on ShellTimerDaemon, so it must be running in your system for the timing functions to work. ShellTimerDaemon is well-behaved and doesn't consume much system RAM. ShellTimerDaemon does not recognize any arguments. You can start up ShellTimerDaemon from your S:user-startup file by adding the line: run NIL: ShellTimerDaemon You can also start it up by dropping the ShellTimerDaemon's icon into the WBStartup drawer. Of course, you can manually start the daemon from the shell or WorkBench. Note that you do NOT have to explicitly start up ShellTimerDaemon at all if you don't want to. When ShellTimer is invoked with a valid command, it checks to see if ShellTimerDaemon is currently running. If ShellTimerDaemon is not located, ShellTimer will try to invoke it. All you have to do is place ShellTimerDaemon in a directory contained in your path. The ShellTimerDaemon continues to run in the background until it receives a QUIT command from ShellTimer. The AmigaDOS Break command can also be used to terminate the daemon by sending it a Control-C. ShellTimerDaemon is not a Commodity, so don't look for it in the Exchange. Simple Usage ============ The main use of ShellTimer is to allow the user to start and stop a timer, and view the elapsed time. This is a simple operation; no command line arguments are required. Typing 1> ShellTimer at the shell prompt will start the timer. Typing it again will stop the timer and display the elapsed time. For example: 1> ShellTimer 00:00:04 The elapsed time is usually expressed in the form HH:MM:SS. If a day or more has passed, the format is DD HH:MM:SS, where DD is the number of elapsed days. No finer resolution then a second is supplied. When ShellTimer is invoked with no arguments, it asks the daemon if there is a pending (previously started) timer session. If not, the daemon starts a new session by recording the current time. If there IS a pending timer session, the daemon terminates the session, computes the elapsed time, and instructs the client to print the result. In this manner, successive invocations of ShellTimer toggle between starting the timer, and stopping the timer. Note that the daemon tracks timer sessions on a shell-by-shell basis. This means that you can start timer sessions in several shell windows and each one is maintained independently. You cannot, for example, stop a timer session initiated in shell #1 by issuing a STOP command from shell #2. Shell #2 can only affect IT'S own timer session. (The daemon records the shell's process number along with the associated timing information). Advanced Usage ============== Here is the template for ShellTimer: ShellTimer START/S,STOP/S,CANCEL/S,QUIT/S,HELP/S,V=VERBOSE/S,Q=QUERY/S START - Initiates a timer session. The current timer request is cancelled (if one is pending) and a new one is started. STOP - Stops the timer and prints the elapsed time (STOP - START). Unlike a real stopwatch, you cannot continue timing after stopping the timer. You have to START the timer anew. CANCEL - Aborts the current timer session. QUIT - Causes the daemon to quit. Any pending timer sessions are lost. Use this command if you want to kill the ShellTimerDaemon program. HELP - Displays a help message. VERBOSE - Causes all output to be more wordy. The default is to be terse. In verbose mode, all commands are acknowledged with a printed reply. Furthermore, the format of the printed elapsed time is changed. The terse default format is [DD] HH:MM:SS. The verbose format is Timer stopped - Elapsed Time: D Day, HH Hours, MM Minutes, SS Seconds Verbose mode tries to generate smart and readable output. QUERY - Print the current elapsed time, without cancelling the session. This is used to check the amount of time that has passed without stopping the timer. The basic commands are START, STOP, CANCEL, QUIT, HELP, and QUERY. Supply only one of these commands on each invocation. The VERBOSE flag can be supplied along with the command if you'd like verbose output. As mentioned in the "Simple Usage" section you need not supply any command. Successive invocations of ShellTimer toggle between starting and stopping the timer. Example Usage ============= Interactive Example ------------------------------------------------- The following lines show various ways that ShellTimer can be invoked from the Shell: 1> ShellTimer 1> ShellTimer 00:01:23 1> ShellTimer 1> ShellTimer VERBOSE Timer stopped - Elapsed Time: 2 Seconds 1> ShellTimer START VERBOSE Timer started 1> ShellTimer QUERY VERBOSE Timer Query - Current elapsed time: 45 Seconds 1> ShellTimer QUERY 00:01:05 1> ShellTimer STOP 00:01:27 1> ShellTimer VERBOSE Timer started 1> ShellTimer CANCEL Timer cancelled 1> ShellTimer STOP No pending timer request 1> ShellTimer QUIT ShellTimerDaemon unloaded Makefile Example----------------------------------------------------- You can use ShellTimer to time compiles and links invoked from a Makefile. Here's a simple example: foo: foo.c @ShellTimer Start lc -L foo.c @echo "Time required for compile and link " NOLINE @ShellTimer Stop ARexx Example ------------------------------------------------------- You can also invoke ShellTimer from ARexx macros (via AmigaDOS, not directly). Here's a semi-lame example - I used this script to test memory consumption of the program: /* Test ShellTimer programs */ address command do forever shelltimer verbose end AmigaDOS Script Example --------------------------------------------- You can invoke Shelltimer from AmigaDOS script files as well. If you look at the top of the two source files, ShellTimer.c and ShellTimerDaemon.c, you'll see that an AmigaDOS script file is embedded there, resembling the following: ;/* Execute me to Compile and link ShellTimer.c shelltimer start verbose lc -. -O -ms -b1 -cfistq -j73 -Lit -tr ShellTimer.c echo "Time to compile and link: " NOLINE shelltimer stop quit */ The idea of embedding the compile/link commands in the C file is borrowed from the examples given by CATS programmers in their AmigaMail articles. Miscellaneous Notes =================== 1. ShellTimer is pure, and can be made resident. 2. If you're going to use ShellTimer a lot, set up an alias like so: alias ST ShellTimer or if you prefer wordy output try: alias ST ShellTimer verbose These aliases go in your shell-startup file. (It can get tedious typing 'ShellTimer' all of the time). Alternately, you can safely rename ShellTimer to whatever you like. However, if you rename ShellTimerDaemon, then ShellTimer will no longer be able to automatically start it up. 3. The AmigaDOS 2.0 VERSION command can be used on the ShellTimer and ShellTimerDaemon executables. 4. This program doesn't work reliably with the backtick feature of 2.0. The problem is that timer sessions are identified by the Process ID of the calling Shell. When backticks are encountered in a shell command a new shell is invoked to execute the command. If your system has a lot of shell activity going on you may not have the same Shell ID for each backtick expression. Code Notes ========== This archive should include the source code for the ShellTimer system. The source files are ShellTimer.c ShellTimerDaemon.c ShellTimer.h I use SAS/C 5.10b. My Manx compiler is out of date (3.6a) and so won't compile the ANSI stuff, so I made no effort to be portable (or non-portable for that matter). The compile/link commands are embedded at the top of each C file. To build the programs type 1> execute ShellTimer.c 2> execute ShellTimerDaemon.c The program are fairly simple. Comments are minimal - sorry. Feel free to make fixes or enhancements. I'd appreciate being contacted if you do some neat stuff with the code (see my addresses at the top of this document). I'm happy to fix any bugs you'd care to report. Dedication ========== The ShellTimer system is dedicated to my loving wife, Deanne. The inspiration for this program came from a series of discussions with a friend at work, Steve Harris. He is a fan of OS/2 and was thinking about writing a similar program for that OS. (We use a similar type of timer program under MS-DOS to time our 'makes'). I figured that I'd like to have a ShellTimer for my Amiga... so here it is. Version History =============== 1.0 Initial release of ShellTimer and ShellTimerDaemon. JWL 03 Feb 1992 End of ShellTimer.doc