TLog -- Training Diary and Log E. F. Bacon OVERVIEW TLog is an intuition based program that allows you to record daily statistics and monitor your training progress. You can maintain a daily record of distance, time, heart rate, weight and temperature. Furthermore you can link a text file with the entry and keep a free form diary. Through its AREXX interface, tlog allows you to automatically get to a scheduler to post reminders of upcoming events. The AREXX commands provide the basis for generating custom reports from the tlog data base. SHAREWARE & SUPPORT Tlog is copyrighted by Edward F. Bacon of Nantmeal Village, PA. This release of Tlog is shareware. Please understand that the shareware concept depends on user support. If you find this utility useful, please send a contribution. If you feel it is not worth anything, don't use it. If you believe someone else could find use for tlog, pass it on along with all of the supporting files and documentation. I would appreciate any feed back on this program. Future releases depend on users specifying what they need from such a program. Only bugs that get reported can be fixed and only features requested can be added. Registered users will receive updates and the loudest voice for future enhancements. STARTING TLOG From WorkBench To start TLog form the Workbench simply double click the TLog TOOL icon. If a data base exists, you can double click the PROJECT icon, or select the PROJECT icon, hold the shift key and select the TLog TOOL icon. In other words, TLog starts like any other Workbench application. From CLI To start TLog from the CLI just enter tlog. Currently there are no command line arguments. [Future releases may permit the user to set options and execute an AREXX script from the command line. What do you think?] When first started TLog opens a background window that may be accessed from any other window with the following menu bar: Project Open Save Close AREXX About Quit View Data Report Graph Settings Save Settings NOTE Settings Palette Date Format Warnings Help The rest of this file is organized around the above list of topics with an additional section describing the AREXX commands. Project Menu The project menu presents the menu items: Open Save Close AREXX About Quit Project-Open Keyboard equivalent Right-Amiga-O The Open menu item either creates a new set of tlog files or opens an existing one. For each training log there are three files; a data base file with the .dbf extension and an index file with the .ndx extension. These files are dBase III compatible files. There is also an icon file, .info extension, which holds the current configuration for TLog. Selecting Open brings up a file requestor that shows all the files that have a .dbf extension in the current directory. You may select one of existing training log data bases or specify the name of a new data base in the text gadget. There is no need to enter the .dbf or .ndx extension, tlog considers the "name of the training data base" to be the base file name and appends the appropriate suffices when needed. The data base files opened define the active data base for tlog and the base file name is displayed in the Data Window, Report Window, and Graph Window. Only one data base may be active at a time, that is if you select the Open menu item and specify a new data base the old one is automatically closed. The demo version of tlog only opens a data base named "logtest" in the current directory. It does not put up the file requestor, rather it displays a window reminding you of the limitation. This is a warning and may be suppressed by resetting Settings-Warnings. Project-Save Keyboard equivalent Right-Amiga-S The Save menu item flushes the internal buffers for the data base. You may want to use this selection occasionally to prevent loss of data. Project-Close Keyboard equivalent Right-Amiga-C The Close menu item flushes the internal buffers and closes the current data base. You may want to use this selection occasionally to prevent loss of data. Note two things: closing the active data base disables certain buttons and menus in other windows; the flush and close operations are also performed by Open and Quit automatically. Project-AREXX Keyboard equivalent Right-Amiga-X The AREXX menu item puts up a window with a text gadget and requests the name of an AREXX script to execute. The AREXX process is called asynchronisly. Tlog uses .tlog as its default AREXX extension. That is if no extension appears in the name you specified, .tlog is appended. For example to execute the AddEvent.tlog script, enter "AddEvent" in the text gadget. If you wanted to execute another script, enter the full file name and parameters. For example to use phonebook.rexx to get Ed's number, you would enter "phonebook.rexx Ed". Project-About The About menu item shows a sub-item with the self-serving information on TLog. This is the address you can use to send comments, bug reports and cash. Project-Quit Keyboard equivalent Right-Amiga-Q Selecting the Quit menu item brings up a requestor to verify that you really want to quit. When you do, the internal buffers are flushed and data base files closed before the program terminates. View Menu The View menu has the following items: Data Report Graph The demo version does not support the Report or Graph windows. Rather you are encouraged to use the AREXX commands to generate custom reports and graphs. The Data Window is opened when you select View-Data. A later section details the Data Window. Settings Menu The Settings menu has the following items: Save Settings NOTE Settings Palette Date Format Warnings Help Settings-Save Settings Selecting the Save Settings menu updates the .info file with the current values of the user-setable variables. See the section on TOOLTYPES and configurable variables below. Settings-NOTE Settings Selecting NOTE Settings menu item opens a window that allows you to determine the directory, file extension and editor to use with the NOTES button of the Data Window. Three text gadgets appear labeled NOTEDIR, NOTEEXT, and EDITOR. Each text box displays the current values. You can modify them by clicking on the text box and typing the new value. The standard Amiga text gadget editing keys are available. The RESET gadget returns all three to their original values. Your new values take effect when you click on the window close gadget. Settings-Palette Selecting the Palette menu item brings up a color palette requestor. You may modify a screen color by selecting the color and adjusting its value by moving the RGB sliders. You can CANCEL the change, or RESET to the values by selecting the labeled gadget. OK leaves the new colors in place. Settings-Date Format Selecting the Date Format menu item opens up a submenu displaying the various date displays available. Select the format that appeals to your needs in the normal fashion. This affects the date display on the left side of the Data Window and the format of dates returned to AREXX scripts. It does not change the date on the calendar of the Data Window, the format within the data base, nor the format of journal file titles. Note that the date format may be changed by an AREXX script. Scripts should save the old format and restore it, in order to keep the sanity of any active user. Settings-Warnings Selecting the Warnings menu item toggles the internal flag to disable or enable the display of warning messages. Settings-Help The On-Line Help is not available in this release. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= -=-=-=-= Data Window Selecting the View-Data menu item from the background window opens the Data Window. This window allows you to make daily entries into your training log, browse through the data base, attach journal entries or "notes", or schedule an upcoming event. When a TLog database is open, its name appears in the Data Window title and all gadgets and menu items are enabled. If no data base is open the title is blank and many of the gadgets and menu items are ghosted, indicating they are disabled. The Data Window displays data from the training log on the left side of the window and a calendar on the right side. At the bottom of the window are gadgets that allow movement through the data base and one for creating notes (journal entries). The Data Window acts as the principle graphical interface to tlog. The following sections describe the menu bar and various gadgets found on the Data Window. Data Window Menu The Data Window has one menu title, DATA, with two menu items: Add Delete New DATA-Add Keyboard equivalent Right-Amiga-A The Add menu item takes the text gadgets of the Data Window and enters them into the active TLog data base. The index for this entry is the current date displayed in the upper left area of the window joined with the entry labeled Key. Any previous data for this combination of the date and your key is over written by the new data. To make multiple entries for the same date vary the Key. For example, each day you could enter data for your AM and PM workouts or your daily GOAL by using the Keys AM, PM and GOAL respectively. If no data base is opened, this menu item is disabled and has no effect. DATA-Delete Keyboard equivalent Right-Amiga-D The Delete menu item removes the current record from the data base. The current record is determined by the current date displayed in the upper-left portion of the window and the Key field. You are prompted before the recorded is removed. The data is left on the window for you to add, in case you have a second thoughts. DATA-New Keyboard equivalent Right-Amiga-N The New menu item enters default data into the text gadgets and sets the current date (upper left) to the calendar date. If no data base is opened, these menu items are disabled and have no effect. Data Gadgets There are 6 text gadgets in the left half of the Data Window labeled: Key, Distance, Time, Heart Rate, Weight, and Temperature. Click on one of the text boxes and log your data. Hitting return activates the next gadget. Distance, Heart Rate and Weight must be entered as floating point numbers (i.e. decimals). The Time must be entered in a format of HH:MM:SS, where HH represents the hours, MM the minutes, and SS the seconds. If you miss type a warning box pops up and tells you. To disable the warnings reset Settings-Warnings. The data fields have the meaning you give them. For instance, Heart Rate could be resting pulse in the morning; Temperature could be the ambient or your body temperature. Distance could be miles or kilometers. Time however, is in hours:minutes:seconds; and there is an AREXX function to return the time in seconds. The Key item acts as a user-defined key for storing entries in the data base. The Key may then be used as a filter when generating reports from the TLog data base. For example, each day you could enter data for your AM and PM workouts or your daily GOAL by using the Keys AM, PM and GOAL respectively. You could record performance statistics for various types of competition ( TT, RR, CRIT ). Or monitor your progress in a particular event TT-DWTN (which to me means the monthly Downingtown Time Trial). The Key may be up to 10 characters. The default Key is 10 dots, .........; this fills up the text gadget, so you must delete or backspace over some dots to make your entry. [The default was blanks, but Intuition did those annoying DisplayBeep() screen flashes for no apparent reason. Now you have the "apparent dots".] In any report generation programs you create, I recommend that you scan the for substrings rather than test for equality. The Data Window Calendar On the right side of the Data Window display is a calendar. You advance the year by clicking on the right arrow adjacent to the year. Advance the month by clicking on the right arrow next to the month. The left arrows decrement the month or year. When a TLog data base is open the calendar days that have entries in the data base are highlighted in color 7 (red). If you click on a day with an entry, the contents of the first record for that day are displayed in the data fields (text gadgets). Notice that the current date, displayed in the upper left, matches the calendar day. To view other data for the same day press the Next gadget. The Next gadget is in the lower right portion of the window and has a single right arrow, ">", in it. If you click on a calendar day that has no entry, the default values for the data fields are displayed. You can edit the fields and add a new record with the DATA-Add menu selection (Right-Amiga-A). If you click on the same calendar day multiple times, the AREXX script named AddEvent.tlog is invoked. The version of AddEvent supplied with this release acts as an interface to schedule an event in Gramma Software's Nag Plus. Please study AddEvent.tlog and feel free to modify it for your own schedule program's requirements. N.B. this feature is activated by multiple selections of the same day in succession and not by "double-clicking". This means you can select a day, edit the data, add the record, and select the same day again to bring up AddEvent. Data Base Gadgets In the lower right portion of the Data Window are four directional gadgets used for browse through the data. The First Record gadget, labeled "<<", takes you to the first active record of the current data base. It is the left most of the four gadgets. The Last Record gadget, labeled ">>", moves to the last active record. It is located on the far right of the group. The two gadgets in the middle take you one record at a time through the data. Either use the Previous gadget, "<", or the Next gadget, ">" to view each active record. You might think of these as controls for a tape deck, rewind, reverse, forward, and fast forward. However, the names first, previous, next and last are reflected in the AREXX commands. If no data base is open these gadgets are ghosted and disabled. NOTES Gadget and Diary At the bottom of the Data window (on the right side) is a gadget labeled NOTES. Selecting this gadget calls an editor with an input file defined by the calendar date. You can then use this to as a free form journal or diary record of your training. The editor is determined by the value of EDITOR in the TOOLTYPES of the .info files; or by the value in Settings-NOTE Settings window. The default editor is the version of Micro Emacs that comes on the EXTRAS disk, TOOLS/MEMACS. The file name is derived from the calendar date and the values of NOTEDIR and NOTEEXT in the TOOLTYPES or Settings-NOTE Settings. The base file name is the calendar date in ISO format. That is YYMMDD, where the digits YY are the year, MM the month and DD the day. This corresponds to DATEFORMAT = 1 in TLog. You have no control over the base file name, but may customize the file name by defining NOTEDIR and NOTEEXT. NOTEDIR is a pathname or directory name that you choose to store your journal entries. Some personal scheduler programs store their files in a user-defined directory. You may find it beneficial to use a common directory and thus establish another connection between TLog and your scheduler. There is no default NOTEDIR. NOTEEXT is a file extension appended to the file name, for example .txt. There is no default NOTEEXT, but you may wish to define it to satisfy your own conventions. When the NOTES gadget is selected the TLog screen goes to the back and the editor is invoked. After you have recorded your notes, save the file and exit in the normal fashion. The TLog screen comes to the front and we are back in business. There is only one textual journal entry for each date (its name is derived from the calendar date and not the data base key). If you select NOTES for a day that already has a journal file, most editors display the contents of that file and allow you to edit it. The command string is "EDITOR filename". You might be able to pass fixed command line arguments to your editor by specifying them in the string that defines EDITOR. If it doesn't work this is an unsupported feature and not a bug. If the command to invoke your editor fails (e.g. exec cannot find the editor) no message is given, but the TLog screen comes to the front immediately. TOOLTYPES and Settings The various user-defined settings are stored in the .info files, both for the tool icon, TLog.info, and the project icon, logtest.info. You may edit the startup values by using the Workbench Info tool to modify the TOOLTYPES. The following TOOLTYPES are defined: NOTEDIR -- directory where journal (diary) entries are found NOTEEXT -- extension appended to journal files DATEFORMAT -- display format for the current date EDITOR -- program called when NOTES gadget is selected WARNINGS -- 0 turns off warning messages, 1 turns them on AREXX interface The AREXX interface has two designs in mind. First to provide the basis for rudimentary report generation from TLog. And second, to provide a connection to other applications. Basically the commands allow you to move through the data base and make inquiries. There are no commands to modify (add or delete) records in the data base. Many commands affect a global variable referred to as the CurrentRecord. These commands often return a string that corresponds to the CurrentRecord in result. Therefore, your script should set OPTIONS RESULT. The fields of the CurrentRecord are delineated with vertical bars '|'. The following fragment parses the various fields of result into variables that suggest their meaning: parse var result dbdate '|' dbheart '|' dbdist '|' dbtime '|' dbweight '|' dbtemp '|' dbkey opendb filename takes a filename as a string argument. It is the base name for the data base. The current release ignores the argument and opens "logtest". The data base must be opened to perform any other operation. closedb flushes the internal buffers and closes the data base. firstrec rewinds the data base pointers to the first record. The record is read into CurrentRecord and returned in result. nextrec advances the data base pointers, reads into CurrentRecord and returns it in result. prevrec backs up the data base pointers, reads into CurrentRecord and returns it in result. lastrec move the pointers to the end of the data base. The last active record is read into CurrentRecord and returned in result. dateformat d takes a digit d as an argument, 1 through 7, and sets the DATEFORMAT. getdateformat returns the current DATEFORMAT in result. currentdate returns the date from the CurrentRecord (in the current DATEFORMAT) in result. currenttime returns the time from the CurrentRecord expressed as the number of seconds in result. Useful for doing arithmetic on time values. The two AREXX scripts, MonthTot.tlog and AddEvent.tlog, are examples that reflect the two design criteria mentioned earlier. MonthTot.tlog generates a report of the total distance for each month. It is primitive but lends itself to many simple and useful modifications. AddEvent.tlog is an interface between TLog and the personal scheduler Nag Plus. KNOWN BUGS v1.0 : The use of the user key to make multiple entries for one day, combined with the delete feature, made the algorithm to determine if there is data for a particular day rather complex. As a result there may be days that have data in the data base that are not painted red (color 7) on the calendar. The AREXX interface has a memory leak.