═══ 1. About ForeWarn ═══ FOREWARN was written to fill a void that appears to exist in the shareware market. The goal of the program is to provide a means of producing forewarnings whenever the program is run based on a data file which is maintained in standard ASCII format similar to the Unix CRONTAB format. The program should also allow for rollover dates for such data as birthdays. Additional information may be found on the following topics: File Disk File Operations. Edit Record manipulation. Options Program operation options. General General information on operation of ForeWarn. ═══ 2. File ═══ Description of File Menu Reload Reloads the data file and discards current edits Clear Deletes all records Save Saves all records About Displays information about the Author and WiSHware ═══ 3. ABOUT ═══ o Select the File menu and choose the About command. Information about the author and the version number will be displayed. ═══ 4. RELOAD ═══ o Select the File menu and choose the Reload command. Use this command to discard all records and load the disk file into memory again. Warning: all changes made to any records will be lost when this command is selected. ═══ 5. CLEAR ═══ o Select the File menu and choose the Clear command. This command is used to clear all records from memory. Warning: all changes made to any records will be lost when this command is selected. ═══ 6. SAVE ═══ o Select the File menu and choose the Save command. This command is used to save all data to the disk file. The program requires that the user confirm that the data should be saved to the disk before continuing. ═══ 7. Edit ═══ The majority of the code for ForeWarn is centered around the editor. The editor has been written to be as simple and logical as possible. The user interface is designed to be as intuitive as possible and follows the OS/2 2.0 Application Design Guide When the edit mode is chosen from the command line, the records of the datafile are displayed in the following format: mm/dd/yy hh:mm:ss DELAY sound Message... To select a record for editing, simply move the mouse pointer to the desired item and click with button 1. A box will appear around the record to indicate that the record has been selected. After selecting an item, the following actions may be selected from the Edit menu: Delete Deletes the current selected record Add After Adds a record after the currently selected record or at the end of all the records if none are selected Change Used to change a record ═══ 8. DELETE ═══ o Select the Edit menu and choose the Delete command. To delete any record from the data file, select the record by moving the pointing device to the desired record and clicking button 1. After selecting an item, pull down the Edit menu and select Delete. The item is then deleted from the records in memory. The data is not written to the data file on disk until Save is selected from the File menu. All data can be deleted by selecting Clear from the File menu. ═══ 9. ADDAFTER ═══ o Select the Edit menu and choose the Add after command. Data can be added in two ways. The first is to select an item and then select Add after from the Edit menu. The data will be added immediately after the selected record. If a record is not selected when Add after from the Edit menu, the record is added at the end of all the records. To add a record to the data file, select the record by moving the pointing device to the desired record and clicking button 1. After selecting an item, pull down the Edit menu and select Add after. The Edit Dialog will pop up to fill in the data to be added. Selecting Cancel from the Edit Dialog will stop editing the record and nothing will be added to the current records. Selecting Change from the Edit Dialog will add the new record. The data is not written to the data file on disk until Save is selected from the File menu. ═══ 10. CHANGE ═══ o Select the Edit menu and choose the Change command. To add or change any records using the ForeWarn editor, the Edit Dialog is used. This dialog box contains a total of twelve entry fields for the data in a record. Note: The four fields in the Advance group are combined to calculate the number of seconds in the delay field of the data file. The dialog group is intended to make it easier for the user to specify the delay time. The Edit Dialog box is displayed when Add after is selected from the Edit menu or when a record is selected for editing by double clicking button 1 of the pointing device on a record or selecting Change from the Edit menu. The data in the Edit Dialog box is divided into groups. These groups are provided to functionally separate the purpose of the data. These groups are: Deadline The six fields which make up the deadline are the Hour, Minute, Second, Day, Month, and Year of the data file. These fields define the actual date of the event to be defined in the record. Leap years affect the number of days that are selectable when the selected month if February. Advance The four fields which make up the advance group are the Hour, Minute, Second, and Day. These fields are combined to create the delay field of the data file. The advance group also contains Year and Month fields for symetry, but these fields are not accessible. Message This is the same field as the one in the data file and contains a single field which is used to edit the message to be displayed when an event is active. Sound This field provides a list of the sounds which may be associated with records. When DOS compatibility is selected from the Options dialog box, this field is ignored. The following table summarizes the method for editing records from the Edit Dialog box: ┌──────────┬───────┬──────────┐ │Group │Field │method │ ├──────────┼───────┼──────────┤ │Deadline │Hour │Spin Box │ ├──────────┼───────┼──────────┤ │" │Minute │Spin Box │ ├──────────┼───────┼──────────┤ │" │Second │Spin Box │ ├──────────┼───────┼──────────┤ │" │Day │Spin Box │ ├──────────┼───────┼──────────┤ │" │Month │Spin Box │ ├──────────┼───────┼──────────┤ │" │Year │Spin Box │ ├──────────┼───────┼──────────┤ │Advance │Hour │Spin Box │ ├──────────┼───────┼──────────┤ │" │Minute │Spin Box │ ├──────────┼───────┼──────────┤ │" │Second │Spin Box │ ├──────────┼───────┼──────────┤ │" │Day │Spin Box │ ├──────────┼───────┼──────────┤ │ │Message│Edit Box │ ├──────────┼───────┼──────────┤ │ │Sound │Spin Box │ └──────────┴───────┴──────────┘ The data is not written to the data file on disk until Save is selected from the File menu. All data can be restored by selecting Reload from the File menu. Note that reloading the data from the disk discards all edits made since the data was last saved to the disk file. ═══ 11. OPTIONS ═══ Description of Options Use DOS Version Compatibility A checkbox used to select the type of file format for saving and loading. When Dos Compatibility is selected, all sound information is lost and the sound field is not saved in the data file. When the data file is loaded, ForeWarn attempts to determine the format of the data file. If DOS compatibility has not been selected and the file is a DOS format file, ForeWarn will automatically switch to DOS mode. Backup data file A checkbox used to turn on or off backups of the data file. Autosort on Load A checkbox used to force the data file to be sorted when it is loaded from disk. This applies to Reload also. Autosort on Save A checkbox used to force the data file to be sorted when it is Saved. Eliminate Expired Events A checkbox used to delete events which have expired when Save is selected. A record expires when it is associated with a specific year and the full date has passed. Enable Sound A checkbox used to allow the program to play the sounds associated with the records. Note that this only works if DOS Compatibility is turned off. ═══ 12. GENERAL INFORMATION ═══ ForeWarn has been designed using the IBM C/Set++ from the PDK and provides a convenient method for providing alerts for important dates and times. The following topics provide more information on the use of ForeWarn: Parameters Details on command line parameters. Colors Information on the use of colors to display events. Variables Information on the required system variables for ForeWarn to operate. Data Format General information on the format of the data file. Copyright Copyright Notice. Liabilities Liabilities notice. Future Enhancements List of planned future enhancements. Known Problems List of known problems and limitations. Author Means for contacting the author. ═══ 13. PARAMETERS ═══ ForeWarn accepts parameters on the command line to control the mode of operation. The following command lines are supported: -e Enter edit mode to change database records or options -c Only check dates (default) -? Display command line parameters ═══ 14. COLORS ═══ To enhance the user interface, Forewarn does not go through normal checks to display the warnings in dialog boxes when the edit mode is chosen. ForeWarn utilizes colors to indicate the status of events. There are three colors that are used: RED : Active dates which meet the criterion for advance notice (i.e. the current date plus the advance is greater than or equal to the target date) BLUE : Expired events. If the option to delete expired events has been specified in the options dialog box, these lines will be deleted when the data is saved. Expired events are events in which the deadline includes a specific year and that year or the actual date has passed. BLACK : Normal data that meets neither of the above. ═══ 15. VARIABLES ═══ To install the OS/2 version of ForeWarn you must have os/2 version 2.1 (beta or GA release) installed on the target system. The following system variables must be set: FOREWARN_INI FOREWARN_DAT These two variables can be set in the system config.sys so that they will be available to all OS/2 sessions by adding the following lines: set FOREWARN_INI=d:\driectory\forewarn.ini set FOREWARN_DAT=d:\directory\forewarn.dat and replace the "d:" with the drive to store the respective files and "directory" with the target directory. The file referenced by the variable FOREWARN_INI is the file to store initialization information between sessions. The file FOREWARN_DAT is used to store the data used by the program. The names of the files can be anything legal to the file system used on the particular disk. If the file system is of type FAT, the file name specification must be limited to the 8.3 FAT format. If the file is HPFS the filename can be anything legal to OS/2 HPFS format. Note: If the destination for the data file is on a FAT formatted partition the file cannot have an extension if the option for creating backup files is selected. ForeWarn will not lose data, it will simply warn the user of the problem and stop. In this case, select the Options dialog and turn off backups. ═══ 16. DATA FORMAT ═══ The datafile used by FOREWARN.EXE requires nine fields for every line of data except for comment lines which must have a pound sign (#) as the first character in the line. The nine fields of each dataline are: sec: + min: | Expiration time for forewarning hour: + day: + month: | Expiration date for forewarning year: + delay: Period of time to make forewarning before expiration sound: Sound index message: Message to be displayed when the forewarn period occurs The limits of each of the fields are as follows: ┌───────┬───────┬────────┬───────┬──────┐ │field │minimum│maximum │default│length│ ├───────┼───────┼────────┼───────┼──────┤ │sec │0 │59 │current│2 │ ├───────┼───────┼────────┼───────┼──────┤ │min │0 │59 │current│2 │ ├───────┼───────┼────────┼───────┼──────┤ │hour │0 │23 │current│2 │ ├───────┼───────┼────────┼───────┼──────┤ │day │1 │31 │current│2 │ ├───────┼───────┼────────┼───────┼──────┤ │month │1 │12 │current│2 │ ├───────┼───────┼────────┼───────┼──────┤ │year │80 │99 │current│2 │ ├───────┼───────┼────────┼───────┼──────┤ │delay │0 │99999999│259200 │8 │ ├───────┼───────┼────────┼───────┼──────┤ │sound │0 │3 │0 │2 │ ├───────┼───────┼────────┼───────┼──────┤ │message│1 char │70 chars│N/A │100 │ └───────┴───────┴────────┴───────┴──────┘ If a asterisk (*) is present in a field, the default value will be used. In most cases, the default is the current date or time, and for the delay, the default is 259200 seconds or 3 days. Each of the fields can be separated by spaces, commas, or tabs. Every line must contain all nine fields. Comments may be omitted, and if the file is edited with the editor provided, all comments will be removed if the file is saved. The editor does place a special header of comments at the beginning of the datafile whenever it saves it. This header of comments is shown following # sec min hour day month year delay(sec) sound message # # 1 day = 86400 seconds # default delay is 3 days or 259200 seconds # # sec: 0-59 # min: 0-59 # hour: 0-23 # day: 1-31 (maximum) # month: 1-12 # year: 80-?? (Year is express as a 2 digit number since 1900) # # A '*' in any field is substituted with the current day/time # The delay cannot be left out! # Fields can be separated by a space, comma, or tab # # Any line beginning with a '#' is interpreted as a comment # These comments are placed in the file to aid in editing a datafile with a standard ASCII editor. ═══ 17. COPYRIGHT ═══ FOREWARN is a ShareWare product which is subject to all copyright restrictions applicable to a product of this type. This program may not be included with any other package without explicit written permission by the author. ═══ 18. LIABILITIES ═══ The author of this program is not responsible for any damages incurred as a result of failure of this program to perform as expected or stated. This program is continually undergoing revisions and some bugs may be found. To the best of the author's knowledge, this program works as stated in this documentation and every effort has been made to insure that the program operates accurately and without error. ═══ 19. ENHANCEMENTS ═══ As with any useful program, ForeWarn is constantly undergoing change. Following is a list of the planned enhancements: MMPM MMPM support for realistic sounds will be added. Threads This version of ForeWarn is single threaded. A future revision will incorporate multiple threads. Colors Rather than relying on specific colors for Active, Expired, and Normal records, a furture release will allow the user to select specific colors for these events. Size/Position The current version does not store the current position and size of the session when it is terminated. A future release will have this feature. ═══ 20. PROBLEMS ═══ The following is a list of known problems and limitations in the current revision of ForeWarn: Unknown There are no known bugs in this version ═══ 21. AUTHOR ═══ Comments for corrections and enhancements are welcomed by the author and can be sent to: William Scott Hiles 2 Savannah St. King George, VA 22485-9331 or via email at: whiles@relay.nswc.navy.mil ═══ ═══ Unix is a registered trademark of ATT laboratories ═══ ═══ By the IBM OS/2 2.0 Application Design Guide, references to the mouse buttons are based on number. This is done to allow for the mouse buttons to be swapped for left and right handed pointing devices. Button 1 is the button located under the index finger. For a right handed mouse, button 1 is the left button. ═══ ═══ A Leap Year occurs every four years. Any year which is a multiple of 4 has an extra day at the end of February. ForeWarn handles this from the Edit Dialog box by allowing the spin box for the day to advance to 29 for February when no year is specified or when the year is a multiple of 4. If a year is specified and it is not a multiple of 4, the month of February is limited to 28 days. ═══ ═══ When DOS compatibility is selected from the Options menu, the sound field is not included in the data file. The total number of fields is eight when DOS compatibility is selected.