TLog v2.01 -- 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. Thank you to all who have both contributed suggestions for improvement and contributed financial support. 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 can just enter tlog. Currently there is only one command line argument. To specify a settings file to load use the -s option. For example to use efb.prefs rather than the standartd settings enter tlog -s efb.prefs 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 View Data About Quit Edit Add Delete New Macros Report Graph AREXX Settings Warnings Create Icons? Edit Settings Palette Date Format Save Settings 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 View Data About Quit Project-Open Keyboard equivalent Right-Amiga-O The Open menu item opens a set of tlog files. When tlog starts a training data base automatically opens. No longer may you directly open other files from tlog. However, an AREXX script may close the active data base and (rather impolitely) not reopen it. Use the menu item to re-open the training log. Please see the later section "More on Tlog files". 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-View Data Keyboard equivalent Right-Amiga-V The Data Window is opened when you select View Data. A later section details the Data Window. The Data Window is opened when tlog starts. You close the window with the close gadget. AREXX scripts that scan the data base execute quicker if the Data Window does not have to be updated. But it is kinda neat to see your season flash before your eyes :) 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. Edit Menu The Edit menu provides the following items: Add Delete New Edit-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. Edit-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. Edit-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. Macros Menu The Macros menu has the following items: Reports Graphs AREXX Macros-Reports Keyboard equivalent Right-Amiga-R Executes the AREXX script defined by the Reports Macro setting. Macros-Graphs Keyboard equivalent Right-Amiga-G Executes the AREXX script defined by the Graphs Macro setting. The above scripts may be customized or replaced by the user, see the description of the Edit Settings menu item below. Two sample scripts are provide for generating graphs and reports from the data base. Note that the data and index files are dBase III compatable. Rather than use the ARexx interface directly, your script might start an application that is dBase compatable and has more sophisticated reporting and graphing tools. Macros-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 FindKey.tlog script, enter "FindKey TT" in the text gadget (here TT is an argument passed to the FindKey macro). If you wanted to execute another non-tlog 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". Settings Menu The Settings menu has the following items: Warnings Create Icons? Edit Settings Palette Date Format Save Settings Settings-Warnings Selecting the Warnings menu item toggles the internal flag to disable or enable the display of warning messages. Settings-Create Icons? Selecting the Create Icons? menu item toggles the internal flag to disable or enable the creation of icons for the data base file. Settings-Edit Settings Selecting Edit Settings menu item opens a window that allows you to modify the environment for the "NOTES" feature and the scripts used to generate Reports or draw Graphs. Three string gadgets appear labeled NOTEDIR, NOTEEXT, and EDITOR determine the directory, file extension and editor to use with the NOTES button of the Data Window. 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 two string gadgets labled Report Macro and Graph Macro define the AREXX scripts and their arguments to be invoked with the Reports and Graphs menu items. The RESET gadget returns all string gadgets to their original values. Your new values take effect when you click on the OK gadget. Selecting the window close gadget or the CANCEL gadget makes no change to the string values. 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-Save Settings The current settings are saved according to the usual (2.0) Amiga conventions. If you have defined a user file through the SETTINGS tooltype (see below) or on the command line, that file is updated. If you have not defined a file, TLog.prefs, in the directory for TLog is updated. If that file cannot be overwritten the settings are written to ENV:TLog/TLog.prefs and ENVARC:TLog/TLog.prefs. Note if you do not have the ENV: and ENVARC: volumes assigned a requester will appear. You may make an assignment or click CANCEL. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 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 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 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 3 (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. N.B. some editors, like TurboText, run in the background when invoked. This makes the TLog screen come to the front immediately even if the editor started. Simply use the screen to back gadgets to get to the editor. (Now that I have Amiga DOS 2.04, the tlog screen will eventually become a public screeen. This solves the problem as well). =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 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 TOOLTYPE is defined: SETTINGS -- defines name of settings (preferences) file to load =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= More on Tlog files ... 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. Currently tlog only opens a data base named "logtest" in the current directory. You can track multiple atheletes or different types of training by storing the data base files in separate directories. Alternatively, with a binary editor you can modify the string "logtest" in the preference (settings) file and start tlog with different settings. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 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. All but the first field of the CurrentRecord are delineated by spaces. The date (first) field is enclosed in double quotes, ", for example "NOV 10, 1991". 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 N.B. that the user key field may have several tokens separated by spaces. In the above example all of the trailing tokens are collected into dbkey. (AREXX HINT: there is no dot after dbkey. dbkey. -- with the dot, stores the next token in dbkey and throws the rest away). AREXX functions provided by TLog: 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. SAMPLE AREXX SCRIPTS Some AREXX scripts have been provided. Note that they require a number of support libraries in order to execute. Each script is easily modified to meet your particular requirements. AddEvent.tlog interface between TLog and the personal scheduler Nag Plus. Invoked when you double click on a calendar date, this is used to schedule an event for that day. MonthGrf.tlog takes a single parameter which is user defined SearchKey. A running total of the monthly distances are plotted against the total distance for records with the SearchKey. This is the default script for the Graphs menu. MonthTot.tlog takes a single parameter which is user defined SearchKey. A running total of the monthly distances are printed against the total distance for records with the SearchKey. This is the default script for the Graphs menu. FindKey.tlog takes a single parameter which is user defined SearchKey. Data for any record with that key is printed. MonthTot1.tlog a simple version of MonthTot.tlog that does not use the special support libraries. test.tlog something silly. KNOWN BUGS 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 3) on the calendar. I really think I have tested all possiblilities and eliminated the bugs, but ... In the future a utility will be provided to re-synchronize the data and index files. This winows out deleted records and makes the data base smaller and the index faster. My support library (YAIL) does not yet manage images in menus for both 1.3 and 2.0. So I removed my photo from the About menu. Use of public screens for 2.0 systems will improve the interface to AREXX and other external programs. Why is there a silly screen anyway?