home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 616.lha / Notify_v1.01 / Notify.Doc.pp / Notify.Doc
Text File  |  1992-03-03  |  19KB  |  386 lines
  1.                                 NOTIFY
  2.                                 ------
  3.  
  4.                      Version 1.01  -  January 1992
  5.  
  6.                 Copyright © Michael Tanzer, 1991, 1992
  7.  
  8. +---------------------------------------------------------------------------+
  9. |                             N O T I C E                                   |
  10. |                                                                           |
  11. | Freely distributable.  Not to be used for commercial purposes without     |
  12. | written consent from the author.  Not to be distributed without this      |
  13. | notice and accompanying components intact.                                |
  14. |                                                                           |
  15. | This product is distributed on an 'as-is' basis, with no warranty of any  |
  16. | kind, either express or implied.  No responsibility whatsoever is assumed |
  17. | by the author for the use of this product, nor for any results of its     |
  18. | use.  No claim whatsoever is made as to this product's accuracy, useful-  |
  19. | ness, completeness, nor suitability to any purpose.                       |
  20. |                                                                           |
  21. | Components include the following files:                                   |
  22. |   Notify.Doc (this document)                                              |
  23. |   Notify                                                                  |
  24. |   NotifyTimer                                                             |
  25. |   NotifyNoise                                                             |
  26. |   NotifyDaily                                                             |
  27. |   NotifyChime                                                             |
  28. |   Notify_Add.info                                                         |
  29. |   Notify_List.info                                                        |
  30. |   NotifyDaily.info                                                        |
  31. |   NotifyChime.info                                                        |
  32. |   Notify.Doc.info                                                         |
  33. |   Install_Notify                                                          |
  34. |   Install_Notify.info                                                     |
  35. |                                                                           |
  36. +---------------------------------------------------------------------------+
  37.  
  38. Syntax:
  39. -------
  40.  
  41. The symbols '<' and '>' are used in this document to enclose optional
  42. parameters, i.e. those that may be but need not be specified.  Strings that
  43. must be specified verbatim are shown in upper case; parameters are shown in
  44. lower case.  For example, the line:
  45.     RX NOTIFY ADD time <message text>
  46. indicates that 'RX NOTIFY ADD' must be entered as shown (although not neces-
  47. sarily in upper case), 'time' is a required parameter, and 'message text' is
  48. an optional parameter.
  49.  
  50.  
  51. What is NOTIFY?
  52. ---------------
  53.  
  54. NOTIFY is a suite of Rexx programs that can be used to issue messages or run
  55. commands automatically at certain times of day.  Messages can be added 'on
  56. the fly', or can be entered into a file to be read in periodically.  When it
  57. is time for a message to be issued, a requester appears on the screen
  58. containing the current time and the message text; these may also be spoken
  59. via the SAY command.  If the first word of a message is 'CMD', it will be
  60. treated as a command which is issued to Amiga DOS.  Facilities are provided
  61. for the adding, editing, and deleting of messages, and for displaying the
  62. times and texts of pending messages.  You may also arrange for the current
  63. time to be announced at regular intervals.
  64.  
  65. Components of NOTIFY include:
  66.   Notify
  67.     This program controls the adding, editing, and deleting of messages for
  68.     specific times of day.  It also enables pending messages to be displayed,
  69.     and can be used to control whether times and messages will be spoken.
  70.   NotifyTimer
  71.     This program is launched asynchronously (by Notify) for each message.
  72.     It waits until the appointed time, then displays a requester showing the
  73.     time and message text.  If messages are to be spoken, it also invokes
  74.     NotifyNoise.  If messages begin with 'CMD', it directs them to Amiga DOS.
  75.     You should not invoke this program explicitly.
  76.   NotifyNoise
  77.     This program invokes the SAY command (usually in the Utilities directory)
  78.     to announce times and message texts.  It is invoked by NotifyTimer and
  79.     NotifyChime.
  80.   NotifyDaily
  81.     This program reads a file (usually s:NotifyDaily.data) which contains
  82.     messages which are to be issued on certain days.  It invokes Notify to
  83.     add each message to the list of pending messages for the current day.
  84.   NotifyChime
  85.     This program invokes NotifyNoise at regular intervals.  By default, it
  86.     causes the time to be announced every hour.
  87.  
  88. These programs must be copied into the directory to which rexx: has been
  89. assigned.  This can be done by double-clicking on the 'Install_Notify' icon.
  90.  
  91.  
  92. Why use NOTIFY?
  93. ---------------
  94.  
  95. NOTIFY provides the ability to handle any number of messages (storage
  96. permitting) with a minimum of effort.  NOTIFY requests can be made from the
  97. command line or with (naturally enough) requesters.  Messages can be issued
  98. on specific dates, certain days of the month, or certain days of the week.
  99. Best of all, NOTIFY is written in Rexx, so if you want to add or change a
  100. feature, you can do it easily.  And it's free.
  101.  
  102.  
  103. What you need in order to use NOTIFY:
  104. -------------------------------------
  105.  
  106. You must have the following libraries in your LIBS: directory:
  107.   rexxsyslib.library
  108.   rexxsupport.library
  109.   rexxarplib.library
  110.   arp.library
  111. These are available from a variety of sources and are not distributed with
  112. NOTIFY.
  113.  
  114.  
  115. How to use Notify:
  116. -----------------
  117.  
  118. Edit Notify and check the setting of the variable 'twentyfour'.  If you want
  119. message times to be displayed in 12-hour format, set this variable to 0; for
  120. 24-hour format, set it to 1.
  121.  
  122. To run Notify, enter:
  123.     RX NOTIFY <request <parameters>>
  124.  
  125. The following requests may be specified:
  126.  
  127.   ADD time <message text>
  128.     This adds a message to the NOTIFY message list.  The time can be either
  129.     a time of day or 'NOW' which causes the message to be issued immediately.
  130.     The message list is kept in environment variables.  You may always use a
  131.     12-hour format for the time if you suffix it with 'am' (or 'a') or 'pm'
  132.     (or 'p').  If 'twentyfour' is set to 1, all times entered without a
  133.     suffix are assumed to be in 24-hour format.  If 'twentyfour' is set to 0,
  134.     times entered without a suffix but with hours greater than 12 are assumed
  135.     to be 'pm'; any time between 1:00 and 12:59 is assumed to be for the next
  136.     occurrence of that time.  For example, if 'twentyfour' is set to 0 and
  137.     the current time is 3:30pm, 
  138.        3:31 = 3:31pm
  139.        3:29 = 3:29am (the following day).
  140.     If the current time is 11:30am,
  141.       12:00 = 12:00pm (noon)
  142.       11:00 = 11:00pm.
  143.     If a time is not specified, you will be prompted for one.
  144.  
  145.     The message text is optional, and may include backslashes (\) to indicate
  146.     that the following characters are to appear on the next line.
  147.  
  148.     If the first word of the message is 'CMD', the message will be treated as
  149.     a command which is issued to Amiga DOS.  You must specify an output
  150.     window (or NIL:) for any command that may type output to the screen; this
  151.     is necessary because NotifyTimer runs without a CLI.  You must also
  152.     specify complete paths for commands in directories other than c: and
  153.     for operands which indicate files. For example:
  154.       RX NOTIFY ADD 9:00 CMD SYS:UTILITIES/CLOCK
  155.     causes the CLOCK program to be run at 9 o'clock.  Enter:
  156.       RX NOTIFY ADD 19:00 CMD RX >NEWCON:0/0/640/200/ MYPROG
  157.     to run a Rexx program called 'MYPROG' at 7 pm.  Enter:
  158.       RX NOTIFY ADD NOW CMD ED S:NOTIFYDAILY.DATA
  159.     to edit the NotifyDaily data file immediately.  Of course, you always
  160.     have the option of modifying NotifyTimer to recognise other keywords or
  161.     to perform other tasks.
  162.  
  163.   EDIT msgno
  164.     This enables you to change the text of a message in the message list.
  165.     Message times, once entered, cannot be changed.
  166.  
  167.   DELETE msgno <msgno <msgno... >>
  168.     This enables you to delete one or more messages from the message list.
  169.     You may specify 'ALL' to delete all messages from the list.
  170.  
  171.   LIST
  172.     This causes a requester to be displayed showing the number, time, and
  173.     text of each pending message.  Backslashes (\) contained within message
  174.     texts are converted to slashes (/) before being displayed.  A string
  175.     gadget enables you to enter new requests; for example, you may enter LIST
  176.     to cause the display to be refreshed.  Pressing the return key when the
  177.     string gadget is blank (and selected) terminates the display.  If there
  178.     are more messages than can be displayed on a screen, the string gadget
  179.     will contain 'More...'; press the return key for the next screenful of
  180.     messages, or clear the gadget by pressing right-Amiga-X to enter a new
  181.     request.
  182.  
  183.     LIST is the default request when Notify is invoked.
  184.  
  185.   HELP (or '?')
  186.     This causes 'help' information to be displayed.
  187.  
  188.   QUIET
  189.     This sets a 'quiet flag' so that messages will be displayed but not
  190.     spoken.
  191.  
  192.   NOISY
  193.     This deletes the 'quiet flag' so that messages will be spoken as well
  194.     as displayed.  By default, the 'quiet flag' is not set.
  195.  
  196.  
  197. How to use NotifyNoise:
  198. -----------------------
  199.  
  200. Edit NotifyNoise and check the setting of the variable 'twentyfour'. If you
  201. want message times to be announced in 12-hour format, set this variable to 0;
  202. for 24-hour format, set it to 1.  Note that this setting operates indepen-
  203. dently of the same variable in Notify.  NotifyNoise uses the SAY command (in
  204. the Utilities directory) to make announcements.  If you have moved the SAY
  205. command to a different directory, or prefer to use a different command to
  206. make announcements, you will need to modify this program.
  207.  
  208. Typically, you would not explicitly execute NotifyNoise (or NotifyTimer).
  209. However, if you want to know what an announcement will sound like, enter:
  210.     RX NOTIFYNOISE time <message text>
  211. where 'time' is in 24-hour (hh:mm) format.
  212.  
  213.  
  214. How to use NotifyDaily:
  215. -----------------------
  216.  
  217. Edit NotifyDaily and check the settings of the following variables:
  218.   perpetual
  219.     If this variable is set to 1, the NotifyDaily data file will be re-read
  220.     daily at midnight so that messages for the new day can be added.  If set
  221.     to 0, the data file will be read only when NotifyDaily is invoked.
  222.   dateformat
  223.     Set this variable to indicate your preference for date format:
  224.       'E' = European (dd/mm/yy)
  225.       'U' = U.S.A.   (mm/dd/yy)
  226.       'O' = Ordered  (yy/mm/dd)
  227.     You must conform to this format when entering dates in the data file.
  228.   datafile
  229.     This variable specifies the name of the data file.
  230. Before running NotifyDaily, build a data file as directed below.  If this
  231. file cannot be found, no messages will be added.
  232.  
  233. To run NotifyDaily when the variable 'perpetual' has been set to 0, enter:
  234.     RX NOTIFYDAILY
  235. If the variable 'perpetual' has been set to 1, enter:
  236.     RUN >NIL: RX NOTIFYDAILY
  237. If you want to invoke NotifyDaily whenever you boot your machine, add one of
  238. the above commands to your startup sequence.
  239.  
  240. To display a 'help' panel for NotifyDaily, enter:
  241.     RX NOTIFYDAILY ?
  242.  
  243. The format of records in the NotifyDaily data file is:
  244.     date time <message text>
  245.  
  246. The date may be expressed as an actual date (in the format indicated by the
  247. 'dateformat' variable) or as a day of the week, as follows:
  248.   MON = Monday
  249.   TUE = Tuesday
  250.   WED = Wednesday
  251.   THU = Thursday
  252.   FRI = Friday
  253.   SAT = Saturday
  254.   SUN = Sunday
  255.   M-F = Monday through Friday
  256.   S-S = Saturday and Sunday
  257.   MWF = Monday, Wednesday, and Friday
  258.   TTH = Tuesday and Thursday
  259.   ALL = Every day
  260. If the date format is used, you may specify a wildcard ('??') for the year,
  261. month, and/or day.  The day can be specified as a day of the week; suffix
  262. this with a number to indicate which occurrence of that day in the month.
  263. For example, specifying MON3 for day and wildcards for year and month will
  264. cause the message to be issued on the third Monday of each month.
  265.  
  266. The time may be expressed either as a time of day or as 'NOW', which causes
  267. the message to be issued when the data file is read.  Times not suffixed with
  268. 'AM' (or 'A') or 'PM' (or 'P') are assumed to be 24-hour values.  Note that
  269. this can have different results if the variable 'twentyfour' in Notify is set
  270. to 0. Messages for the current day whose times have passed will not be added.
  271.  
  272. Examples:
  273.   Assume that 'dateformat' is set to 'E', 'perpetual' is set to 0, and
  274.   'twentyfour' (in Notify) is set to 0, and that NotifyDaily is invoked from
  275.   the startup sequence.
  276.   
  277.   01/01/?? NOW Happy New Year!
  278.     This message will be issued when the machine is booted on New Year's Day.
  279.   01/??/?? 10:00am Today is the first day of the month.
  280.     This message will be issued at 10am on the first day of each month.
  281.   SUN 2:00pm  Why aren't you mowing the lawn?
  282.     This message will be issued at 2pm every Sunday.
  283.   M-F 9:00am cmd sys:utilities/clock digital2
  284.     The CLOCK command will be run at 9am Monday through Friday.
  285.   31/12/99 6:00 I hope you're going to behave yourself tonight.
  286.     This message will be issued at 6pm if the machine is booted after 6am.
  287.   FRI/??/97 12:00pm
  288.     You will be notified of the time at noon on every Friday in 1997.
  289.   TUE1/11/?? NOW Today is Melbourne Cup Day.
  290.     This message will be issued when the machine is booted on the first
  291.     Tuesday of November.  Depending on your time zone, this message may be
  292.     too late, and you will have missed the race; consider as an alternative:
  293.     MON1/11/?? NOW Tomorrow is Melbourne Cup Day.             ...or perhaps:
  294.     TUE4/10/?? NOW Next Tuesday is Melbourne Cup Day.        ...depending on
  295.     whether the first of November falls on a Tuesday.
  296.  
  297.  
  298. How to use NotifyChime:
  299. -----------------------
  300.  
  301. Edit NotifyChime to inspect the variable 'interval' and modify it to change
  302. the default number of minutes per interval. NotifyChime will call NotifyNoise
  303. to announce the current time every so many minutes as indicated by this
  304. variable.  If 60 can be divided evenly by the interval, the first interval
  305. will begin at the next occurrence of a number of minutes divisible by the
  306. interval relative to the current hour.  For example, if the interval is 15
  307. and Notify Chime is invoked at 9:20, the time will first be announced at
  308. 9:30, then at 9:45, 10:00, 10:15, etc.  The interval can be left alone in
  309. the program and modified on the command line.
  310.  
  311. To run NotifyChime, enter:
  312.     RX "ADDRESS AREXX NOTIFYCHIME <interval>"
  313. where 'interval' is expressed in minutes.  You may enter this command again
  314. at any time if you want to modify the interval.  Once NotifyChime is running,
  315. the current interval can be displayed by entering:
  316.     RX NOTIFYCHIME STATUS
  317. To terminate NotifyChime, enter:
  318.     RX NOTIFYCHIME QUIT
  319. You can also enter:
  320.     RX NOTIFYCHIME ?
  321. to display a 'help' panel.  If NotifyChime is active, invoking it without
  322. specifying an interval will terminate it.  This enables an icon to be used
  323. to 'toggle' the function on and off as required.
  324.  
  325.  
  326. Other things you might like to know about NOTIFY:
  327. -------------------------------------------------
  328.  
  329. Approximately 13K is required to support the task running NotifyTimer for
  330. each message that is added; this task remains active until the time of the
  331. message regardless of whether the message is deleted.  Due to the fact that
  332. the RexxSupport delay() function is used to wait for the specified time, the
  333. CPU overhead of this task is negligible.
  334.  
  335. Similarly, NotifyChime will require a task each time the interval is set. If
  336. the interval is changed, any previously-launched task will run until the end
  337. of its interval before detecting that it has been superseded.
  338.  
  339. Testing revealed that the delay() function is not accurate; there should be
  340. fifty 'ticks' per second, but I have found this to be out by a factor of
  341. approximately two per cent.  Although adequate for short intervals, this
  342. caused longer delays to be over-length by about a minute per hour.  To
  343. correct for this, the programs that use the delay() function (NotifyTimer,
  344. NotifyChime, and NotifyDaily) contain loops which wait 90% of the remaining
  345. portion of the interval unless that portion is less than ten minutes.  This
  346. technique should ensure that the displaying and/or announcing of messages
  347. will begin within twelve seconds of their specified times.
  348.  
  349. NOTIFY was developed on an Amiga 500 under Amiga DOS 1.3 version 34.28, using
  350. ARexx 1.15, RexxArpLib.Library 2.52 and Arp.Library 39.1.  It has been tested
  351. under Amiga DOS 2.04.
  352.  
  353. I originally wrote NOTIFY because I wanted to be reminded to do various
  354. things in the course of a day.  Setting the CLOCK alarm was unsatisfactory;
  355. no message could be associated with an alarm, only one alarm could be set,
  356. and if I happened to be looking away from the screen when the alarm was
  357. issued, I would miss it altogether.  I found certain shareware products to be
  358. useful for keeping track of events occurring on specific days, but I could
  359. miss messages if I booted my machine too late in the day, and adding a single
  360. reminder for later in the same day involved a lot of stuffing around with
  361. the mouse (selecting menu items, gadgets, etc.) and took too much time.  I
  362. also found that, since I don't tend to re-boot too frequently in a single
  363. day, the storing of such reminders in a file was an unnecessary waste of
  364. space.  Furthermore, I wanted certain messages to be issued on the first day
  365. of each month, others on certain days of the week, etc., and found no
  366. provision for this sort of thing.  Worst of all, without the source for these
  367. programs, I was unable to alter their operation to suit my taste.  The
  368. special handling of messages beginning with 'CMD' was an afterthought, and
  369. required the addition of only five simple lines to NotifyTimer.  I find that
  370. NOTIFY satisfies all my requirements; I hope it satisfies yours.
  371.  
  372. You are free use NOTIFY for as long as you like and to modify it in any way
  373. that suits your needs, but please do not distribute a modified version.
  374. I do not ask for any remuneration, but if you would like to send me something
  375. (a postcard, a diskette, a cheque in Australian dollars, whatever), I would
  376. be delighted to receive it.  I will make a sincere effort to answer any
  377. questions you may have about NOTIFY.  My address is:
  378.  
  379.     Michael Tanzer
  380.     P.O. Box 289
  381.     Carlton North, VIC 3054
  382.     Australia
  383.  
  384.     Telephone:  +61 3 387 6589
  385.     Facsimile:  +61 3 388 1863
  386.