***************************************************************************** * * * Documentation for * * * * -- RemindMe V1.0 -- * * * * Copyright © 1994 Marcus Stratmann * * * ***************************************************************************** SHORT DESCRIPTION RemindMe is a simple events reminder. It reads the events from a file and checks if the user should be notified. Weekly, monthly, yearly and unique events are possible. CONTENTS The RemindMe package includes the following files: .Product-Info the product description RemindDates a sample events file RemindMe the main program RemindMe.doc the documentation DISTRIBUTION RemindMe is FREEWARE. This program may be freely distributed as long as all files of the package remain unchanged and are included with the distribution. Any commercial distribution of this package without the prior written consent of the author (Marcus Stratmann) is expressly prohibited. Copyright © 1994 by Marcus Stratmann REQUIREMENTS This program should run on any AMIGA. If it doesn't: please tell me! INSTALLATION Copy RemindMe into your C: directory or any other directory which is in your search path. Copy the file RemindDates into your S: directory and enter your own events. Include RemindMe in your startup-sequence. When RemindMe is called, the current date should be set correctly, so you better call SetClock before. The lines in your startup-sequence may look like this: ... SetClock load RemindMe ... FORMAT OF THE EVENTS FILE Your personal events are described in the file S:RemindDates. Each line contains the description of one event. Comments start with a semicolon (;) in the FIRST row of a line. The whole line is considered as a comment and is ignored. You can use one of the following formats for each event: WEEKLY weekday [WARN warndays] MESSAGE event-message MONTHLY monthday [WARN warndays] MESSAGE event-message YEARLY yearday [WARN warndays] MESSAGE event-message UNIQUE date [WARN warndays] MESSAGE event-message For specification of the header use the format HEADER header-message Statements in [] are optional and can be omitted. RemindMe doesn't distinguish between uper and lower case. So "WEEKLY" is the same as "weekly" or "WeEkLy". You can use some special codes for your header- and event-messages. These are indicated by a backslash "\" followed by a character. Special codes are: \e escape character (ASCII 27) \f form feed (clears the screen) \n line feed (new line) \t vorizontal tab \\ a backslash ("\") Description of the keywords and their parameters: HEADER header-message This defines the message RemindMe displays first when it notifies you of your events. Everything in the line after the keyword HEADER is considered as your header-message (except leading blanks). If HEADER is specified more than once, RemindMe will take the last header-message. When there are no events to remind you of RemindMe doesn't display the header-message. WARN warndays This is the number of days you want to be notified before the event takes place. When the number of days until the event is less or equal to the value of warndays RemindMe will display the message belonging to the event. A value of zero for warndays means that RemindMe only notifies you on the day of the event, not before. If you specify a negativ number, RemindMe will take its absolute value. If WARN is omitted, RemindMe assumes a value of zero for warndays. MESSAGE event-message Everything in the line after the keyword MESSAGE is taken as the event-message (except leading blanks). This is displayed together with the date of and the number of days to the event. The length of the message is limited to 80 characters. WEEKLY weekday This defines a weekly event. weekday should be replaced by one of the following: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY This is the weekday your weekly event is going to happen. * NOTE: RemindMe always takes the next possible date which matches the specification. E.g. if you say WEEKLY MONDAY WARN 14 MESSAGE Monday again! RemindMe will only remind you of the next monday and not of the monday seven days later, though it is in the range of 14 warndays, too. This is also effective for MONTHLY and YEARLY. MONTHLY monthday This defines a monthly event. Valid numbers for monthday are 1 to 31 and -1 TO -31. A positive number stands for the corresponding day of the month. If a negative number is specified, the days are counted from behind. So -1 belongs to the last day of the month (not 0!) and in a month with 30 days, -30 belongs to the first day of the month. If a month doesn't have the required number of days, the next matching month is taken. YEARLY yearday This defines a yearly event. yearday is of the form day.month. where day and month are both numbers. RemindMe checks if the date is valid. UNIQUE date This defines an event that takes place only once. date is of the form day.month.year where day, month and year are all numbers. Don't forget the century when specifying the date; 1994 and 94 are different years! Again, the validity of the date is checked. COMMAND-LINE OPTIONS The syntax for the RemindMe command line is given as: RemindMe [ALL] [TEST] The text in brackets ("[]") indicates an optional parameter. Here's the meaning of the options: ALL Normally RemindMe will display only those events whose occurrence lie in the specified warndays range. But when the option ALL is given, RemindMe will display all events, even those whose occurrence does not lie in the warndays range. Use this to see which events you have entered in the events file S:RemindDates. TEST When reading the file S:RemindDates the program will not report any errors or warnings. If you want to test, if your events file is ok, use the TEST option. RemindMe will then report possible errors and give you the corresponding line numbers. OUTPUT OF THE PROGRAM Let's have a look at the output RemindMe produces. I started the program on 11-Oct-1994 from the command line with RemindMe ALL TEST and with the sample events file of this this archiv in use. Here's the output of the program: RemindMe V1.0, Copyright (c) 1994 Marcus Stratmann. Error line 16: Illegal weekday Warning line 18: Obsolete date 1 error(s), 1 warning(s). don't forget: tomorrow (Mo, 12-Sep-1994): Oh no, monday again! in 4 days (Th, 15-Sep-1994): This is the 15th day of the month in 19 days (Fr, 30-Sep-1994): Month is over! Any money left? in 20 days (Sa, 1-Oct-1994): This is the first day of the next month ... in 50 days (Mo, 31-Oct-1994): This is the 31st day of the month in 104 days (Sa, 24-Dec-1994): Christmas! Don't forget the presents! in 386 days (Mo, 2-Oct-1995): This is a monday, too. in 536 days (Th, 29-Feb-1996): Intercalary day In the first line you find the program name, version and copyright note. This is only output when the TEST option is active. The next lines give you a summary of the errors and warnings. As you can see, in line 16 an illegal weekday was specified (moonday instead of monday) which gives you an error message. In line 18 of the events file the date 01.03.1966 was used which is more than 28 years over. This results in the warning "obsolete date". * NOTE: RemindMe never changes the events file! That means it doesn't discard obsolete events. This prevents data losses due to a wrong current date set. The errors and warnings summary is displayed only when the TEST option is active. The next part of the output gives a summary of the events. As I used the ALL options, all events from the events file are displayed. Events which lie in the past are not shown. In the first line of this part the header-message is shown. If you don't specify a header-message, none is shown (you guessed that, hm? :-) For each event you get: - the days until the occurence of the event (0 days is replaced by "today", 1 day by "tomorrow") - the date of the event in the form - the message for the event This part of the output is shown only when there are any events to be displayed. ERRORS, WARNINGS AND RETURN CODES There are two differnt kind of error: "hard" errors and "soft" errors. Soft errors occur when RemindMe reads the events file and finds a syntactic error in it. In this case it skips to the next line. If the TEST option is active, you get an error message indicating the line number and the cause of the error. Soft errors don't interrupt the program. All other errors are hard errors. These result in the termination of the program, as something really important went wrong. Hard errors are shown even if the TEST option is not set. Warnings inform you that something unexpected has happen, which doesn't seriously affect the execution of the program. As in the case of soft errors, warnings are displayed only if the TEST option is active. Hard errors: File not found The events file S:RemindDates wasn't found. Can't examine file The progaram couldn't examine the length of the events file. This should be a file, not a directory S:RemindDates is a directory, not a file. File is empty The file S:RemindDates is empty. No Memory There is not enough free memory for the program. Can't open file The program can't open the events file. Error reading file An error occurred while reading from the file. Date seems to be wrong The current date seems to be wrong. You get this message when the year is set to less then 1994. Soft errors: Illegal weekday The weekday after the keyword WEEKLY is wrong. Legal weekdays are MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY Illegal day The day after the keyword MONTHLY is wrong. Valid numbers are 1 to 31 and -1 TO -31. Illegal date The date after one of the keywords YEARLY or UNIQUE is wrong. The format is day.month. for YEARLY and day.month.year for UNIQUE. Maybe you forgot a "." or you stated a date which doesn't exist. Remember that all parts of the date consist of numbers, so don't use something like "oct" for the month. MESSAGE expected The program didn't find the keyword MESSAGE. Every event needs a message (which might be empty) following the MESSAGE keyword. Keyword expected The program expected one of the keywords WEEKY, MONTHLY, YEARLY, UNIQUE, HEADER. This might be a sequel of an error in the line before. To protect you from such consequences you should use only one line for each event. Illegal number The program unsuccessfully tried to read a number (e.g. the day of a date). String too long The length of a string the program can read is limited to 100 char- acters. You stated a string (e.g. a date) which is longer than 100 characters. Warnings: Obsolete date The date stated after UNIQUE is obsolete. You should erase this line from the events file. Message truncated The length of messages is limited to 80 characters. If your message is longer, the program will truncate it. Return codes: This is what the program gives back to the operating system when it quits. The code for warnings is 5, for soft errors 10 and for hard errors 20 (except for 'wrong date', which gives back 10). The highest error code which occures is given back as the return code. THE AUTHOR Send bug reports, suggestions, money, food :-) or other nice things to: Marcus Stratmann Böttcherstr. 13 46244 Kirchhellen Germany E-Mail: uste01@unidozr.hrz.uni-dortmund.de (until March 1995) "Der Tag würde mehr Spaß machen, wenn er später anfinge."