DOS TIMETOOL version 1.01

by David F. Leigh
dave.leigh@cratchit.org
http://www.cratchit.org

"A DOS Utility?  In the Year 2000?  Are you CRAZY!?"

  Absolutely not.  I do work on a lot of projects in a lot of environments, 
  and one thing I HAVE to be able to do is keep track of the time I spend 
  on various tasks, regardless of where I am.  Also, since my laptop is 
  rather slow I get the most of it by running DR DOS.  It's fast, and 
  totally bulletproof (when you're using a laptop you want to have
  something that won't go nuts if the battery suddenly dies).

  So I wrote this tool for DOS.  I can run it on DOS, on Linux or Unix in a
  DOSEMU box, on OS/2, on any flavor of Windows, and even on a Mac with a
  SoftPC emulator.

  Since it's written with single-tasking DOS in mind, DOS TIMETOOL is 
  designed to work even when it's not running!  More on this in a moment.

PURPOSE 

  What DOS TIMETOOL does is let you quickly and easily track the time you
  spend on up to 20 tasks during the day.  It's similar in purpose to 
  Sirtaj Singh Kang's KDE Personal Time Tracker for Linux (karm version 0.5).
  DOS TIMETOOL is a bit more flexible, though.

FEATURES

  DOS TIMETOOL has some surprisingly cool features for such a small and
  simple application.  For example:

  * DOS TIMETOOL is VERY (around 30k) small and VERY fast.  That was my
    number one goal.  I wanted to be able to put this thing on a floppy
    and carry it around, with the data file, and use it wherever I 
    happened to be.

  * You can add and delete projects while the clock is running.  There's
    no need to do anything special for editing.  In fact, there's no
    configuration file at all.  Just a small (under 1K!) file where your
    times are stored.  You don't even have to have the TIMETOOL.DAT file
    at all... it will be created for you if it's not there.

  * You can correct the accrued time.  Hey, folks, this is a TOOL, and 
    I don't like to be limited by my tools.  The fact is, sometimes I
    forget to switch the clock to a different project.  This feature
    lets me fix my mistakes.

  * You can delete the currently active project. If you do this, then 
    DOS TIMETOOL turns off the clock. It doesn't try to second-guess 
    you... you'll have to tell it what project you're working on.

  * DOS TIMETOOL sorts your projects by number automatically. This is
    how my timesheet is arranged, so that's how it's displayed here.

  * You can number your projects however you like.  None of this 
    sequential auto-numbering garbage.  I number mine with the actual
    codes we use in our Project Status Reporting System (which resemble)
    GL codes in some organizations.  Use what you like.  By the way,
    alphabetic characters are OK.

  * You can export your timesheet to a comma-separated variable file,
    suitable for import into Excel, Lotus Notes, dBase, or just about
    any spreadsheet or database.

  * This isn't a deficiency, it's a feature: You can't edit a project
    number once it's been entered. Since you can add, delete, and 
    edit accrued times, I chose not to implement a feature that would
    rarely be used.

  * OK, this one's a deficiency.  I limited DOS TIMETOOL to 20 projects
    simply because I didn't want to scroll.  Later on I might scroll and
    increase the number of projects... perhaps I'll detect the screen
    resolution as well. But frankly, I've spent more time on this 
    documentation than I did in writing the first usable DOS TIMETOOL.  
    So it can wait.

  * Timetool versions from 1.0 on have limited mouse support using DOS 
    interrupt 33H. You can click on any project to start the clock, and 
    you can click on the menu bar at the bottom of the screen. Deleting
    Exporting, and Help also support the mouse.

PURPOSE and USE

  Here's how I use DOS TIMETOOL on a daily basis:

  Since I fill in a timesheet on a daily basis I start it up first thing
  in the morning.  You can place it in your AUTOEXEC.BAT or in a Windows
  Startup folder if your memory is as bad as mine.  The first thing I do
  is press "R" to Reset all of the accrued times to zero.  Then I press
  "S" and type in the project number I'll be working on first thing. 
  Then I exit the program. DOS TIMETOOL saves its current state, and the
  next time it starts up it acts as if it were never turned off at all.
  By this I mean that it will calculate accrued time for the time it
  was not running.

  When I start some work that's to be billed to a different project, I
  simply fire up DOS TIMETOOL (at under 30k it loads FAST) and press "S"
  again and tell it the number of the new task.  Since I can only bill
  time to one project at a time, TIMETOOL suspends the last project and
  starts accruing time to the new one.

  At the end of the day I fill in my timesheet using DOS TIMETOOL to 
  provide the number of minutes I worked on each project.  I actually
  enter the number of minutes into the spreadsheet and let it translate
  it into hours and minutes for me. If you're even lazier than I am you
  can export the DOS TIMETOOL data to a CSV file and import it into
  your spreadsheet directly

  This is a VERY simple program to use.  The best way to figure it out
  is just to use it.  But for completeness, here's a list of the 
  functions:
    * AddProj  - Adds a project. You supply the project number, 
                 project name, and a seed value for the accrued
                 time (just a nicety in case you're adding the
                 project as an afterthought, and have already spent
                 some time on it.  This happens to me all the time.)
    * Correct  - Corrects the accrued time for a specified project.
    * Delete   - Deletes a project.
    * EndTask  - Stops the clock on the current task without starting a
                 new task.
    * ResetAll - Resets the accrued time for all projects to zero.
    * StartTask- Stops the clock on the currently active project (if any
                 and start it on the selected project.
    * Help     - Displays the About and Help screens.
    * eXport   - exports DOS TIMETOOL data to a comma-separate file 
                 called TIMETOOL.CSV, which can be imported into most
                 spreadsheets and databases.
    * Quit     - Saves the current state of the program and exist 
                 gracefully.

  That's all.  The only thing you should know in this age of Windows 
  is that DOS TIMETOOL uses Verb - Object syntax.  You choose one of
  the commands (verbs) above, then type in the name of the object
  (project) that it should act upon, if necessary.  Commands like 
  EndTask, Quit, Help, and ResetAll need no objects, of course.

TECHIE STUFF (boring!)

  DOS TIMETOOL is written in Asic 5.00 ("Almost BASIC"), a shareware
  BASIC compiler from 80/20 software.  I've included all of the project
  files in the distribution, so there's really nothing to tell you about 
  how to compile it...  The TIMETOOL.PRJ file already has the compiler 
  options set up for you.

  But, just so you know... You should compile it with the Decimal Math
  option on and debugging info off.

  If you want to modify and compile your own, feel free, but acquiring 
  ASIC is up to you.  Just do a search on the web for ASIC500.ZIP.  
  You'll find it.

  In case you don't, it should work just as well using QBASIC or 
  QuickBASIC, though you might have to futz a bit with the FormatHrs
  routine, since datatypes might differ.  Please don't be surprised 
  when your EXE is much larger than my COM file.

  When you look at the code you'll see that the lines are short, there's 
  only one mathematical operator per line and I don't embed functions 
  in other functions.  These are limitations of ASIC. You may be tempted
  to think you can "improve" the code by "fixing" these deficiencies, 
  but if you do it won't compile.  ASIC is exceedingly fast and efficient, 
  and it gets some of that efficiency by forcing a little work on you.  
  Don't fight it, just trust me, all this extra stuff results in a smaller
  executable than you'd get with another BASIC compiler.  You may also 
  notice that I didn't use any user-defined functions; instead I used
  GOSUBS and everything's global.  That's simply because the program is
  so small and limited that I wanted to keep everything in the same
  source file.  ASIC requires that each SUB be in a separate source
  file, and that just wasn't necessary here.

  Why did I write this in ASIC rather than C?  Because as I said, ASIC
  is fast and efficient, and if I was going to include the source, I'd
  really like for it to be readable to a great majority of the potential
  users, not just C programmers.  I don't care what you code in, or 
  whether you code at all... you should be able to pick this up.

LICENSE (even more boring than the techie stuff)

  DOS TIMETOOL 
  Time Management Tool
  Copyright (C) 2000 David F. Leigh

  This program is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 2
  of the License, or (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but it is provided 100% completely and totally AS IS. WITHOUT ANY 
  WARRANTY; without even the implied warranty of MERCHANTABILITY or 
  FITNESS FOR A PARTICULAR PURPOSE. In fact, I don't even guarantee
  that this program will run at all. See the GNU General Public License 
  for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to 
      The Free Software Foundation, Inc.
      59 Temple Place - Suite 330
      Boston MA  01222-1307
      USA
  or visit the web at http://www.fsf.org/licenses

CONTACT INFORMATION

  The author is the maintainer of this software.  If you have improvements
  or suggestions, please contact Dave Leigh at dave.leigh@cratchit.org, or
  visit his website at http://www.cratchit.org.

*end of timetool.txt*