TIMECLOCK 1.0 Copyright 1994 Kenneth A. Reek All rights reserved. Internet: kar@cs.rit.edu SHAREWARE VERSION WHAT IS TIMECLOCK? ------------------ TIMECLOCK is a Windows program that keeps track of time you've spent on your computer. Time is charged to one or more "projects" from your list by "punching in" when you begin work on each project. In addition, projects may be grouped into different "categories" (e.g. business and pleasure) that you specify. To give one example, this will greatly simplify your compu- tation of the percentage of time your computer was used for business purposes, and thus the percentage of its value that you can depreciate or deduct as a business expense on your taxes. REGISTERING TIMECLOCK --------------------- TIMECLOCK is copyrighted software. It is not in the public domain, nor is it distributed for free. The author retains all rights to this software. TIMECLOCK is distributed as Shareware so you can try it out without risk to see if you like it. Use it for two weeks. If you don't like it, simply delete it and owe nothing. If you continue to use TIMECLOCK after the two week trial period, you must register your copy. For your conven- ience, the file REGISTER.TXT is included: it contains a registration form that you may use. The fee for individuals wishing to register a single copy of TIMECLOCK is US$15. The fee schedule for corporate users is shown in the REGISTER.TXT file. Send the form with your payment to the author: Kenneth A. Reek 3090 Griffin Rd Churchville, NY USA 14428-9512 ADVANTAGES OF REGISTERING TIMECLOCK ----------------------------------- The registered version of TIMECLOCK comes with a Windows-based report generator with options for more selective reporting than that provided in the shareware version. A printed manual, which contains more detail than the shareware documentation, is also available. Registered users will also receive the next upgrade to the program free of charge, and may call or write for information on the latest revision, to report bugs, or to make suggestions or other comments on TIMECLOCK. I am particularly interested in your ideas for making TIMECLOCK a more useful program. And, last but not least, you don't have to deal with the registration reminder screens any more! DISCLAIMER ---------- TIMECLOCK is supplied as is. The author disclaims any and all warranties, expressed or implied, including but not limited to warranties of merchant- ability and of fitness for any purpose. The author assumes no liabilities for any damages, direct or consequential, which may result from the use of TIMECLOCK. INSTALLING TIMECLOCK -------------------- Installation is easy. First, you must unpack the archive file containing the distribution (if you're reading this, you have done that already). You should have the following files: timeclk.exe TIMECLOCK program (Windows) report.exe report generator (MS-DOS) timeclk.ini sample initialization file project.txt sample project file timeclk.txt the file you are reading now register.txt registration form timeclk.log sample log file to illustrate report pgm. Copy all these files to any directory you wish; it is most convenient if they all reside in the same directory. To see how it runs, open the File Manager and display the directory containing TIMECLOCK. Now double-click the mouse pointer on "timeclk.exe". The display that you see is based on the information in the sample project file; you will be modifying this file to suit your own needs. Select one of the projects shown by clicking on it with the left mouse button; this "punches you in" on that project. Select another one; TIMECLOCK "punches you out" (nasty phrase!) of the old project before punching you into the new one. Now click the right mouse button anywhere on the screen: this punches you out of the current project without punching you into a new one. To see what the report generator produces, open a DOS window and change to the directory that you copied Timeclock into. Then run the report program like this: c:\timeclk: report > report.txt If you are punched into a project when you generate the report, you will see an error message telling you that the log file has a check-in entry with no corresponding check-out entry; you may ignore this error for now. Now you can examine the file that was produced using Notepad or any other editor. The report format is described in more detail later. NOTE: Be sure to delete the "timeclk.log" file that came with the distribution before starting to use Timeclock to record your actual usage. This sample log file was distributed only to demonstrate the output of the report generator. Should you decide to register TIMECLOCK, you may wish to add it to the StartUp group in the Program Manager. Here is how that is done: 1) Open the StartUp group. 2) Select File|New from the Program Manager. 3) Verify that the box which appears says "New Program Item", and click OK. 4) Enter the following values: Description: TimeClock Command Line: timeclk.exe Working Directory: (the directory where you put TIMECLOCK) 5) Click the OK button. Now TIMECLOCK will start automatically every time Windows is started. HOW TO USE TIMECLOCK -------------------- TIMECLOCK consists of two programs (timeclk.exe and report.exe), an optional initialization file (timeclk.ini), and your project description file (project.txt). timeclk.exe creates a file (timeclk.log) containing an entry for each time you punch in or punch out of a project. report.exe reads this log file and produces a report summarizing usage by project and by category. The following sections describe these processes in more detail. THE INITIALIZATION FILE: timeclk.ini ------------------------------------ The initialization file contains information that affects the way in which TIMECLOCK runs. The sample initialization file contains comments which describe each of the available entries. Lines beginning with # are comments; some sample entries are shown as comments -- to enable them, remove the leading "# " from the line. THE PROJECT FILE: project.txt ----------------------------- The project file contains entries that identify each of the projects you wish to track, and the categories to which they belong. The sample project file contains comments which describe the formats of these entries. It also contains the sample entries which you saw when you first ran timeclock. SELECTING COLORS ---------------- The initialization file and the project file both allow you to select the colors that will be used on the timeclock screen. This is done by giving intensities for red, green and blue as a three-value list, like this: 0,255,0 Each value is a number in the range 0 - 255. While it is possible to specify 16,777,216 different colors in this way, many Windows displays can show only 16. Here are the different colors you can specify: 255,255,255 White 128,128,128 Dark gray 192,192,192 Light gray 0,0,0 Black 255,0,0 Light red 128,0,0 Dark red 0,255,0 Light green 0,128,0 Dark green 0,0,255 Light blue 0,0,128 Dark blue 255,255,0 Light yellow 128,128,0 Dark yellow 255,0,255 Light magenta 128,0,128 Dark magenta 0,255,255 Light cyan 0,128,128 Dark cyan PUNCHING IN AND OUT ------------------- The timeclock displays your projects in lists, with one list for each category you have used. To "punch in" to a project, simply point at the name of the project with the mouse and click the left mouse button. The project name is shown in the title bar, the current entry is highlighted, and the elapsed time is shown for your convenience **. ** If you watch the elapsed time display for a while, you might see it skip a second every now and then. This is nothing to worry about, as the log file entries record the start time and end time for each project rather than a count of the seconds used. The anomaly in the display is caused by small differences between the system's clock and Windows' program scheduling mechanism. To punch in to a different project, simply point to it and click the left mouse button. The former project is automatically punched out, and the new project is punched in. To punch out of a project without punching in to another one, click the right mouse button anywhere on the screen. If a project is punched in when the timeclock program is terminated, it will automatically be punched out. The same is true when Windows exits. If the system crashes, though, the log file may be left with a "punch in" entry which has no corresponding "punch out" entry. This problem can be fixed by editing the log file as described below. THE TIMECLOCK LOG FILE: timeclk.log ----------------------------------- The format of the log file is simple: Date Time In/Out Project-Category The date is shown in yyyy/mm/dd format (to avoid any problems that two digit years might cause as we reach the year 2000), and the time is shown in hh:mm:ss format. This is followed by a tab, and either the word "IN" or the word "OUT" to specify punching in or out. This is followed by a tab, and the name and category of the project. A sample entry is shown below: 1994/02/25 13:12:57 IN Retirement mgr-Business Normally, you need never look at this raw data, as the reporting program produces summaries by project and by category. The file is created as an ordinary text file for two reasons, however. First, if you need an unusual report, a text file can be read by other programs or easily imported into a spreadsheet. Second, if the file is corrupted (for example by a system crash), it can be edited with any text editor (such as Notepad; do NOT use a word processor such as Write or Word) to repair the damage. THE REPORTING PROGRAM: report.exe --------------------------------- The reporting program in the shareware version is an MS-DOS program. The registered version comes with a Windows reporting program that provides many options to tailor the report, such as user-specified date ranges, the ability to report on a single project or a single category, and so forth. However, the shareware reporting program produces the same type of output as the registered version so that you can evaluate its usefulness. The reporting program reads the initialization file to learn the name of the log file; it then reads the log file and prints an error message describing each error found in the log file. It then prints a report to the standard output, which you will probably want to redirect to a file for later printing. Here is an example of how it is run from the MS-DOS prompt: c:\timeclk> report > report.txt Note that you must be in the TIMECLOCK directory when you run the report program. The report contains two sections. The first is a summary of usage by project. A list is printed for each category showing the projects in that category. The following values are shown: hours spent on the project, the percentage of the total use that this project represents, the percentage of the use in this category that this project represents, the number of sessions for the project, the average duration of each session, and the project name. At the end of each category's list is a line showing the totals for that category. The second section is a summary of usage by category. For each category, the following values are shown: hours spent on projects in the category, the percentage of the total use that this category represents, the number of sessions for the category, the average duration of each session, and the category name. The report generator does not read the project file (project.txt), so there is no problem if the log file contains entries for old projects which no longer exist in the project file. Thank you for trying out TIMECLOCK, and I hope you find it to be useful. Remember to register the program if you decide to use it past the trial period! Show your support of the shareware concept by registering the programs that you use -- this is the best way to ensure the continued development of new shareware software. K. Reek, 6/12/94