OS/2 Shareware BBS: InfoMgt

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: InfoMgt / InfoMgt.zip / remin310.zip / remind.man < prev

Wrap

Text File | 1993-11-04 | 177KB | 4,159 lines

REMIND(1) REMIND(1) NNAAMMEE remind - a sophisticated reminder service SSYYNNOOPPSSIISS rreemmiinndd [[_o_p_t_i_o_n_s] _f_i_l_e_n_a_m_e [_d_a_t_e] DDEESSCCRRIIPPTTIIOONN RReemmiinndd reads the supplied _f_i_l_e_n_a_m_e and executes the com- mands found in it. The commands are used to issue reminders and alarms. Each reminder or alarm can consist of a message sent to standard output, or a program to be executed. If _f_i_l_e_n_a_m_e is specified as a single dash '-', then RReemmiinndd takes its input from standard input. This also implicitly enables the --oo option, described below. OOPPTTIIOONNSS --nn The --nn option causes RReemmiinndd to print the nneexxtt occurrence of each reminder in a simple calendar format. You can sort this by date by piping the output through ssoorrtt((11)). --rr The --rr option disables RRUUNN directives and the sshheellll(()) function --cc_n The --cc option causes RReemmiinndd to produce a calendar which is sent to standard output. If you supply a number _n, then a calendar will be generated for _n months, starting with the current month. By default, a calendar for only the current month is produced. If _n starts with '+', then a calendar for _n weeks is produced. --ww_c_o_l[,_p_a_d[,_s_p_c]]] The --ww option specifies the output width, padding and spacing of the formatted calendar output. _C_o_l specifies the number of columns in the output device, and defaults to 80. _P_a_d specifies how many lines to use to "pad" empty calendar boxes. This defaults to 5. If you have many reminders on cer- tain days, which make your calendar too large to fit on a page, you can try reducing _p_a_d to make the empty boxes smaller. _S_p_c specifies how many blank lines to leave between the day number and the first reminder entry. It defaults to 1. Any of _c_o_l, _p_a_d or _s_p_c can be omitted, providing you provide the correct number of commas. Don't use any spaces in the option. --ss_n The --ss option is very similar to the --cc option, except that the output calendar is not formatted. It is listed in a "simple format" which can be used 13 October 1993 1 REMIND(1) REMIND(1) as input for more sophisticated calendar-drawing programs. If _n starts with "+", then it is inter- preted as a number of weeks. --pp_n The --pp option is very similar to the --ss option, except that the output contains additional informa- tion for use by the rreemm22ppss program, which creates a PostScript calendar. For this option, _n cannot start with "+"; it must specify a number of months. --mm The --mm option causes the --cc option to produce a calendar whose first column is Monday rather than Sunday. (This conforms to the international stan- dard.) It does _n_o_t, however, affect the --pp or --ss options. --vv The --vv option makes the output of RReemmiinndd slightly more verbose. --oo The --oo option causes RReemmiinndd to ignore all OONNCCEE directives. --tt The --tt option causes RReemmiinndd to trigger all non- expired reminders, regardless of the _d_e_l_t_a supplied for each reminder. --hh The --hh option ("hush...") suppresses certain warn- ing and information messages. In particular, if no reminders are triggered, this mode produces no out- put. --aa The --aa option causes RReemmiinndd not to immediately trigger timed reminders which would also be queued. It also causes RReemmiinndd not to place timed reminders in a calendar. --qq The --qq option causes RReemmiinndd not to queue timed reminders for later execution. --ff The --ff option causes RReemmiinndd to remain in the fore- ground when processing queued reminders, rather than forking off a background process to handle them. --ee The --ee option diverts error messages (normally sent to the standard error stream) to the standard out- put stream. --dd_c_h_a_r_s The --dd option enables certain debugging modes. The _c_h_a_r_s specify which modes to enable: ee Echo all input lines 13 October 1993 2 REMIND(1) REMIND(1) xx Trace all expression evaluation tt Display all trigger date computation vv Dump the variable table after execution of the reminder script ll Echo lines when displaying error messages --gg[aa||dd[aa||dd[aa||dd]]] Normally, reminders are issued in the order in which they are encountered in the reminder script. The --gg option cause RReemmiinndd to sort reminders by date and time prior to issuing them. The optional aa and dd characters specify the sort order (ascend- ing or descending) for the date, time and priority fields. See the section "Sorting Reminders" for more information. --bb[_n] Set the time format for the calendar and simple- calendar outputs. _N can range from 0 to 2, with the default 0. A value of 0 causes times to be inserted in 12-hour (am/pm) format. 1 causes times to be inserted in 24-hour format, and 2 inhibits the automatic insertion of times in the calendar output. --xx[_n] Sets the iteration limit for the SSAATTIISSFFYY clause of a RREEMM command. Defaults to 150. --kk_c_m_d Instead of simply printing MMSSGG-type reminders, this causes them to be passed to the specific _c_m_d. You must use '%s' where you want the body to appear, and may need to enclose this option in quotes. Also, because _c_m_d is run using the ssyysstteemm(()) library function, shell quotes in the body of the message may cause problems. Note that this option oovveerr-- rriiddeess the --rr option and the RRUUNN OOFFFF command. As an example, suppose you have an X Window program called xmessage, which pops up a window and dis- plays its invocation arguments. You could use: remind '-kxmessage %s &' ... to have all of your MMSSGG-type reminders processed using xmessage. A word of warning: It is very easy to spawn dozens of xmessage processes with the above technique. So be very careful. Also, the _c_m_d is passed as an argument to sspprriinnttff(()). If you use formatting directives other than %s, or use more than one %s directive, there's a good chance that you'll crash 13 October 1993 3 REMIND(1) REMIND(1) RReemmiinndd. Finally, because _c_m_d is executed using the ssyysstteemm(()) library function, shell delimiters in MMSSGG- type reminders could cause problems. _I_n _p_a_r_t_i_c_u_- _l_a_r_, _n_e_v_e_r _r_u_n _u_n_t_r_u_s_t_e_d _r_e_m_i_n_d_e_r_s _u_s_i_n_g _t_h_e --kk _o_p_t_i_o_n. A reminder like: REM msg foo ; rm -Rf . would cause havoc if run with the --kk option. --zz[_n] Runs RReemmiinndd in the daemon mode. If _n is supplied, it specifies how often (in minutes) RReemmiinndd should wake up to check if the reminder script has been changed. _N defaults to 5, and can range from 5 to 60. Note that the use of the --zz option also enables the --ff option. --uu_n_a_m_e Runs RReemmiinndd with the uid and gid of the user speci- fied by _n_a_m_e. The option changes the uid and gid as described, and sets the environment variables HOME, SHELL and USER to the home directory, shell, and user name, respectively, of the specified user. LOGNAME is also set to the specified user name. This option is meant for use in shell scripts which mail reminders to all users. Non-root users can also use the --uu option. How- ever, in this case, it only changes the environment variables as described above. It does not change the effective uid or gid. --ii_v_a_r==_e_x_p_r Sets the value of the specified _v_a_r to _e_x_p_r, and pprreesseerrvveess _v_a_r. _E_x_p_r can be any valid RReemmiinndd expression. See the section "Initializing Vari- ables on the Command Line" for more details. If you supply a _d_a_t_e on the command line, it must consist of _d_a_y _m_o_n_t_h _y_e_a_r, where _d_a_y is the day of the month, _m_o_n_t_h is at least the first three letters of the English name of the month, and _y_e_a_r is a year (all 4 digits) from 1990 to about 2075. You can leave out the _d_a_y, which then defaults to 1. If you do supply a _d_a_t_e on the command line, then RReemmiinndd uses it, rather than the actual system date, as its notion of "today." This lets you create calendars for future months, or test to see how your reminders will be trig- gered in the future. In addition, as part of the _d_a_t_e component, you can supply a _r_e_p_e_a_t parameter, which has the form *_n_u_m. This causes RReemmiinndd to be run _n_u_m times, with the date incrementing on each iteration. You may have to enclose the parameter in 13 October 1993 4 REMIND(1) REMIND(1) quotes to avoid shell expansion. See the subsection "Repeated Execution" in the section "Calendar Mode" for more information. RREEMMIINNDDEERR FFIILLEESS RReemmiinndd uses scripts to control its operation. The com- mands inside a script can range from the very simple and almost immediately understandable: REM 6 Jan MSG David's birthday to the baroque and obscure: REM [trigger(date(thisyear, 1, 1) + 180)] ++5 OMIT \ sat sun BEFORE MSG [ord(thisyear-1980)] payment due %b! A reminder file consists of commands, with one command per line. Several lines can be continued using the backslash character, as in the above example. In this case, all of the concatenated lines are treated as a single line by RReemmiinndd. Note that if an error occurs, RReemmiinndd reports the line number of the last line of a continued line. RReemmiinndd ignores blank lines, and lines beginning with the '#' or ';' characters. You can use the semicolon as a comment character if you wish to pass a RReemmiinndd script through the C pre-processor, which interprets the '#' character as the start of a pre-processing directive. RReemmiinndd is not case sensitive; you can generally use any mixture of upper- or lower-case for commands, parameters, invocation options, etc. TTHHEE RREEMM CCOOMMMMAANNDD The most powerful command in a RReemmiinndd script is the RREEMM command. This command is responsible for issuing reminders. Its syntax is: RREEMM [OONNCCEE] [_d_a_t_e___s_p_e_c] [_b_a_c_k] [_d_e_l_t_a] [_r_e_p_e_a_t] [PPRRIIOORRIITTYY _p_r_i_o] [SSKKIIPP | BBEEFFOORREE | AAFFTTEERR] [OOMMIITT _o_m_i_t___l_i_s_t] [AATT _t_i_m_e [_t_d_e_l_t_a] [_t_r_e_p_e_a_t]] [SSCCHHEEDD _s_c_h_e_d___f_u_n_c_t_i_o_n] [UUNNTTIILL _e_x_p_i_r_y___d_a_t_e] [SSCCAANNFFRROOMM _s_c_a_n___d_a_t_e] MMSSGG | MMSSFF | RRUUNN | CCAALL | SSAATTIISSFFYY | PPSS | PPSSFFIILLEE _b_o_d_y The parts of the RREEMM command can be specified in any order, except that the _b_o_d_y must come immediately after the MMSSGG, RRUUNN, CCAALL, PPSS, PPSSFFIILLEE or SSAATTIISSFFYY keyword. The RREEMM token is optional, providing that the remainder of the command cannot be mistaken for another RReemmiinndd command such as OOMMIITT or RRUUNN. The portion of the RREEMM command before the MMSSGG, MMSSFF RRUUNN, CCAALL or SSAATTIISSFFYY clause is called a _t_r_i_g_g_e_r. 13 October 1993 5 REMIND(1) REMIND(1) MMSSGG,, MMSSFF,, RRUUNN,, CCAALL,, PPSS aanndd PPSSFFIILLEE These keywords denote the _t_y_p_e of the reminder. (SSAATTIISSFFYY is more complicated and will be explained later.) A MMSSGG- type reminder normally prints a message to the standard output, after passing the _b_o_d_y through a special substitu- tion filter, described in the section "The Substitution Filter." However, if you have used the --kk command-line option, then MMSSGG-type reminders are passed to the appro- priate program. Note that the options --cc, --ss, --pp and --nn disable the --kk option. The MMSSFF keyword is almost the same as the MMSSGG keyword, except that the reminder is formatted to fit into a para- graph-like format. Three system variables control the formatting of MMSSFF-type reminders - they are $$FFiirrssttIInnddeenntt, $$SSuubbssIInnddeenntt and $$FFoorrmmWWiiddtthh. They are discussed in the section "System Variables." The MMSSFF keyword causes the spacing of your reminder to be altered - extra spaces are discarded, and two spaces are placed after periods and other characters, as specified by the system variables $$EEnnddSSeenntt and $$EEnnddSSeennttIIgg. Note that if the body of the reminder includes newline characters (placed there with the %_ sequence), then the newlines are treated as the beginnings of new paragraphs, and the $$FFiirrssttIInnddeenntt inden- tation is used for the next line. You can use two consec- utive newlines to have spaced paragraphs emitted from a single reminder body. A RRUUNN-type reminder also passes the _b_o_d_y through the sub- stitution filter, but then executes the result as a system command. A CCAALL-type reminder is used only to place entries in the calendar produced when RReemmiinndd is run with the --cc, --ss or --pp options. A PPSS or PPSSFFIILLEE-type reminder is used to pass PostScript code directly to the printer when producing PostScript calendars. This can be used to shade certain calendar entries (see the psshade() function), include graphics in the calendar, or almost any other purpose you can think of. You should not use these types of reminders unless you are an expert PostScript programmer. The PPSS and PPSSFFIILLEE reminders are ignored unless RReemmiinndd is run with the --pp option. See the section "More about PostScript" for more details. DDAATTEE SSPPEECCIIFFIICCAATTIIOONNSS A _d_a_t_e___s_p_e_c consists of zero to four parts. These parts are _d_a_y (day of month), _m_o_n_t_h (month name), _y_e_a_r and _w_e_e_k_- _d_a_y_. _M_o_n_t_h and _w_e_e_k_d_a_y are the English names of months and weekdays. At least the first three characters must be used. The following are examples of the various parts of a _d_a_t_e___s_p_e_c_: 13 October 1993 6 REMIND(1) REMIND(1) _d_a_y_: 1, 22, 31, 14, 3 _m_o_n_t_h_: JANUARY, feb, March, ApR, may, Aug _y_e_a_r_: 1990, 1993, 2030, 95 (interpreted as 1995). The year can range from 1990 to 2075. _w_e_e_k_d_a_y_: Monday, tue, Wed, THU, Friday, saturday, sundAy Note that there can be several _w_e_e_k_d_a_y components sepa- rated by spaces in a _d_a_t_e___s_p_e_c_. IINNTTEERRPPRREETTAATTIIOONN OOFF DDAATTEE SSPPEECCIIFFIICCAATTIIOONNSS The following examples show how date specifications are interpreted. 1. Null date specification - the reminder is triggered every day. The trigger date for a specific run is simply the current system date. 2. Only _d_a_y present. The reminder is triggered on the specified day of each month. The trigger date for a par- ticular run is the closest such day to the current system date. For example: REM 1 MSG First of every month. REM 31 MSG 31st of every month that has 31 days. 3. Only _m_o_n_t_h present. The reminder is triggered every day of the specified month. Example: REM Feb MSG Every day in February 4. _d_a_y and _m_o_n_t_h present. Examples: REM 6 Jan MSG Every 6th of January REM Feb 29 MSG Every 29th of February 5. Only _y_e_a_r present. Example: REM 1991 MSG Every day in 1991 6. _y_e_a_r and _d_a_y present. Examples: REM 1 1990 MSG 1st of every month in 1990 REM 1992 23 MSG 23rd of every month in 1992 7. _y_e_a_r and _m_o_n_t_h present. Examples: REM Feb 1991 MSG Every day in Feb 1991 REM 1992 September MSG Every day in Sept 1992 8. _y_e_a_r_, _m_o_n_t_h and _d_a_y present. Examples: REM 8 Jan 1991 MSG 8th January 1991. REM 1992 March 9 MSG 9th March 1992. 9. _w_e_e_k_d_a_y only. Examples: REM Sat MSG Every Saturday 13 October 1993 7 REMIND(1) REMIND(1) REM Mon Tue Wed Thu Fri MSG Every working day REM Monday Wednesday MSG Every Monday and Wednesday 10. _w_e_e_k_d_a_y and _d_a_y present. Examples: REM Sat 1 MSG First Saturday of every month REM Mon Tue Wed Thu Fri 15 \ MSG 1st working day after 15th of every month 11. _w_e_e_k_d_a_y and _m_o_n_t_h present. Examples: REM Mon March MSG Every Monday in March REM Mon Tue Wed Thu Fri Feb MSG Every working day in February 12. _w_e_e_k_d_a_y_, _m_o_n_t_h and _d_a_y present. Examples: REM Mon 1 March MSG First Monday in March REM Sat Sun 15 July MSG First Sat or Sun on or after 15 July 13. _w_e_e_k_d_a_y and _y_e_a_r present. Example: REM Sat Sun 1991 MSG Every Saturday and Sunday in 1991 14. _w_e_e_k_d_a_y_, _d_a_y and _y_e_a_r present. Examples: REM Mon 15 1990 MSG 1st Mon after 15th of every month in 1990 REM Mon Tue Wed Thu Fri 1 1990 \ MSG 1st working day of every month in 1990 15. _w_e_e_k_d_a_y_, _m_o_n_t_h and _y_e_a_r present. Example: REM Mon Wed 1991 Feb MSG Every Mon and Wed in Feb 1991. 16. _w_e_e_k_d_a_y_, _d_a_y_, _m_o_n_t_h and _y_e_a_r present. Example: REM Mon Tue Wed Thu Fri 28 Oct 1990 \ MSG 1st working day on or after 28 October 1990. Note that when both _w_e_e_k_d_a_y and _d_a_y are specified, RReemmiinndd chooses the first date on or after the specified _d_a_y which also satisfies the _w_e_e_k_d_a_y constraint. It does this by picking the first date on or after the specified _d_a_y which is listed in the list of _w_e_e_k_d_a_y_s_. Thus, a reminder like: REM Mon Tue 28 Oct 1990 MSG Hi would be issued only on Monday, 29 October, 1990. It would not be issued on Tuesday, 30 October, 1990, since the 29th is the first date to satisfy the _w_e_e_k_d_a_y con- straints. BBAACCKKWWAARRDD SSCCAANNNNIINNGG Sometimes, it is necessary to specify a date as being a set amount of time before another date. For example, the last Monday in a given month is computed as the first Mon- day in the next month, minus 7 days. The _b_a_c_k specifica- tion in the reminder is used in this case: REM Mon 1 -7 MSG Last Monday of every month. 13 October 1993 8 REMIND(1) REMIND(1) A _b_a_c_k is specified with one or two dashes followed by an integer. This causes RReemmiinndd to move "backwards" from what would normally be the trigger date. The difference between --7 and -7 will be explained when the OOMMIITT keyword is described. AADDVVAANNCCEE WWAARRNNIINNGG For some reminders, it is appropriate to receive advance warning of the event. For example, you may wish to be reminded of someone's birthday several days in advance. The _d_e_l_t_a portion of the RREEMM command achieves this. It is specified as one or two "+" signs followed by a number _n. Again, the difference between the "+" and "++" forms will be explained under the OOMMIITT keyword. RReemmiinndd will trigger the reminder on computed trigger date, as well as on each of the _n days before the event. Here are some examples: REM 6 Jan +5 MSG Remind me of birthday 5 days in advance. The above example would be triggered every 6th of January, as well as the 1st through 5th of January. PPEERRIIOODDIICC RREEMMIINNDDEERRSS We have already seen some built-in mechanisms for certain types of periodic reminders. For example, an event occur- ring every Wednesday could be specified as: REM Wed MSG Event! However, events which do not repeat daily, weekly, monthly or yearly require another approach. The _r_e_p_e_a_t component of the RREEMM command fills this need. To use it, you must completely specify a date (year, month and day, and optionally weekday.) The _r_e_p_e_a_t component is an asterisk followed by a number specifying the repetition period in days. For example, suppose you get paid every second Wednesday, and your last payday was Wednesday, 28 October, 1992. You can use: REM 28 Oct 1992 *14 MSG Payday This issues the reminder every 14 days, starting from the calculated trigger date. You can use _d_e_l_t_a and _b_a_c_k with _r_e_p_e_a_t_. Note, however, that the _b_a_c_k is used only to com- pute the initial trigger date; thereafter, the reminder repeats with the specified period. Similarly, if you specify a weekday, it is used only to calculate the ini- tial date, and does not affect the repetition period. SSCCAANNFFRROOMM 13 October 1993 9 REMIND(1) REMIND(1) The SSCCAANNFFRROOMM keyword is for advanced RReemmiinndd programmers only, and will be explained in the section "Details about Trigger Computation" near the end of this manual. Note that SSCCAANNFFRROOMM is available only in versions of RReemmiinndd from 03.00.04 up. PPRRIIOORRIITTYY The PPRRIIOORRIITTYY keyword must be followed by a number from 0 to 9999. It is used in calendar mode and when sorting reminders. If two reminders have the same trigger date and time, then they are sorted by priority. If the PPRRIIOORR-- IITTYY keyword is not supplied, a default priority of 5000 is used. EEXXPPIIRRYY DDAATTEESS Some reminders should be issued periodically for a certain time, but then expire. For example, suppose you have a class every Friday, and that your last class is on 11 December 1992. You can use: REM Fri UNTIL 11 Dec 1992 MSG Class today. Another example: Suppose you have jury duty from 30 November 1992 until 4 December 1992. The following reminder will issue the message every day of your jury duty, as well as 2 days ahead of time: REM 30 Nov 1992 *1 +2 UNTIL 4 Dec 1992 MSG Jury duty Note that the _r_e_p_e_a_t of *1 is necessary; without it, the reminder would be issued only on 30 November (and the two days preceding.) TTHHEE OONNCCEE KKEEYYWWOORRDD Sometimes, it is necessary to ensure that reminders are run only once on a given day. For example, if you have a reminder which makes a backup of your files every Friday: REM Fri RUN do_backup (Here, _d_o___b_a_c_k_u_p is assumed to be a program or shell script which does the work.) If you run RReemmiinndd from your .login script, for example, and log in several times per day, the _d_o___b_a_c_k_u_p program will be run each time you log in. If, however, you use the OONNCCEE keyword in the reminder, the RReemmiinndd checks the last access date of the reminder script. If it is the same as the current date, RReemmiinndd assumes that it has already been run, and will not issue reminders containing the OONNCCEE keyword. Note that if you view or edit your reminder script, the 13 October 1993 10 REMIND(1) REMIND(1) last access date will be updated, and the OONNCCEE keyword will not operate properly. If you start RReemmiinndd with the --oo option, then the OONNCCEE keyword will be ignored. LLOOCCAALLLLYY OOMMIITTTTIINNGG WWEEEEKKDDAAYYSS The OOMMIITT portion of the RREEMM command is used to "omit" cer- tain days when counting the _d_e_l_t_a or _b_a_c_k. It is speci- fied using the keyword OOMMIITT followed by a list of week- days. Its action is best illustrated with examples: REM 1 +1 OMIT Sat Sun MSG Important Event This reminder is normally triggered on the first of every month, as well as the day preceding it. However, if the first of the month falls on a Sunday or Monday, then the reminder is triggered starting from the previous Friday. This is because the _d_e_l_t_a of +1 does not count Saturday or Sunday when it counts backwards from the trigger date to determine how much advance warning to give. Contrast this with the use of "++1" in the above command. In this case, the reminder is triggered on the first of each month, as well as the day preceding it. The omitted days are counted. REM 1 -1 OMIT Sat Sun MSG Last working day of month Again, in the above example, the _b_a_c_k of -1 normally causes the trigger date to be the last day of the month. However, because of the OOMMIITT clause, if the first of the month falls on a Sunday or Monday, the trigger date is moved backwards past the weekend to Friday. (If you have globally omitted holidays, the reminder will be moved back past them, also. See "The OMIT command" for more details.) By comparison, if we had used "--1", the reminder would be triggered on the last day of the month, regardless of the OOMMIITT. TTIIMMEEDD RREEMMIINNDDEERRSS Timed reminders are those which have an AATT keyword fol- lowed by a _t_i_m_e and optional _t_d_e_l_t_a and _t_r_e_p_e_a_t. The _t_i_m_e must be specified in 24-hour format, with 0:00 represent- ing midnight, 12:00 representing noon, and 23:59 repre- senting one minute to midnight. You can use either a colon or a period to separate the hours from the minutes. That is, 13:39 and 13.39 are equivalent. RReemmiinndd treats timed reminders specially. If the trigger date for a timed reminder is the same as the current sys- tem date, the reminder is queued for later activation. 13 October 1993 11 REMIND(1) REMIND(1) When RReemmiinndd has finished processing the reminder file, it puts itself in the background, and activates timed reminders when the system time reached the specified time. If the trigger date is _n_o_t the same as the system date, the reminder is not queued. For example, the following reminder, triggered every work- ing day, will emit a message telling you to leave at 5:00pm: REM Mon Tue Wed Thu Fri AT 17:00 MSG Time to leave! The following reminder will be triggered on Thursdays and Fridays, but will only be queued on Fridays: REM Fri ++1 AT 13:00 MSG Lunch at 1pm Friday. The _t_d_e_l_t_a and _t_r_e_p_e_a_t have the same form as a _r_e_p_e_a_t and _d_e_l_t_a, but are specified in minutes. For example, this reminder will be triggered at 12:00pm as well as 45 min- utes before: REM AT 12:00 +45 MSG Example The following will be issued starting at 10:45, every half hour until 11:45, and again at noon. REM AT 12:00 +75 *30 MSG Example2 The "+75" means that the reminder is issued starting 75 minutes before noon; in other words, at 10:45. The *30 specifies that the reminder is subsequently to be issued every 30 minutes. Note that the reminder is always issued at the specified time, even if the _t_d_e_l_t_a is not a multi- ple of the _t_r_e_p_e_a_t. So the above example is issued at 10:45am, 11:15am, 11:45am, and 12:00pm. Note that in the time specification, there is no distinction between the "+" and "++" forms of _t_d_e_l_t_a. Normally, RReemmiinndd will issue timed reminders as it pro- cesses the reminder script, as well as queuing them for later. If you do not want RReemmiinndd to issue the reminders when processing the script, but only to queue them for later, use the --aa command-line option. If you do not want reminders to be queued for later, use the --qq command-line option. Normally, RReemmiinndd forks a background process to handle queued reminders. If you want RReemmiinndd to remain in the foreground, use the --ff command-line option. This is use- ful, for example, in .xinitrc scripts, where you can use the command: 13 October 1993 12 REMIND(1) REMIND(1) remind -fa myreminders & This ensures that when you exit X-Windows, the RReemmiinndd pro- cess is killed. WWAARRNNIINNGG AABBOOUUTT TTIIMMEEDD RREEMMIINNDDEERRSS Note: If you use user-defined functions or variables (described later) in the bodies of timed reminders, then when the timed reminders are activated, the variables and functions have the definitions which were in effect at the end of the reminder script. These definitions may _n_o_t necessarily be those which were in effect at the time the reminder was queued. TTHHEE SSCCHHEEDD KKEEYYWWOORRDD The SSCCHHEEDD keyword allows more precise control over the triggering of timed reminders. However, discussion must be deferred until after expressions and user-defined func- tions are explained. See the subsection "Precise Schedul- ing" further on. TTHHEE SSUUBBSSTTIITTUUTTIIOONN FFIILLTTEERR Before being processed, the body of a RREEMM command is passed through a substitution filter. The filter scans for sequences "%x" (where "x" is any letter and certain other characters) and performs substitutions as shown below. (All dates refer to the trigger date of the reminder.) %%aa is replaced with "on _w_e_e_k_d_a_y_, _d_a_y _m_o_n_t_h_, _y_e_a_r" For example, consider the reminder: REM 18 Oct 1990 +4 MSG Meeting with Bob %a. On 16 October 1990, it would print "Meeting with Bob on Thursday, 18 October, 1990." On 17 October 1990, it would print "Meeting with Bob tomorrow." On 18 October 1990, it would print "Meeting with Bob today." %%bb is replaced with "in _d_i_f_f day's time" where _d_i_f_f is the aaccttuuaall number of days between the current date and the trigger date. (OOMMIITTss have no effect.) For example, consider: REM 18 Oct 1990 +4 MSG Meeting with Bob %b. On 16 October 1990, it would print "Meeting with 13 October 1993 13 REMIND(1) REMIND(1) Bob in 2 days' time." On 17 October 1990, it would print "Meeting with Bob tomorrow." On 18 October 1990, it would print "Meeting with Bob today." %%cc is replaced with "on _w_e_e_k_d_a_y" Example: REM 18 Oct 1990 +4 MSG Meeting with Bob %c. On 16 October 1990, it would print "Meeting with Bob on Thursday." On 17 October 1990, it would print "Meeting with Bob tomorrow." On 18 October 1990, it would print "Meeting with Bob today." %%dd is replaced with "_d_a_y", the day of the month. %%ee is replaced with "on _d_d_/_m_m_/_y_y_y_y" %%ff is replaced with "on _m_m_/_d_d_/_y_y_y_y" %%gg is replaced with "on _w_e_e_k_d_a_y_, _d_a_y _m_o_n_t_h" %%hh is replaced with "on _d_d_/_m_m" %%ii is replaced with "on _m_m_/_d_d" %%jj is replaced with "on _w_e_e_k_d_a_y_, _m_o_n_t_h _d_a_y_-_t_h_, _y_e_a_r" This form appends the characters "st", "nd", "rd" or "th" to the day of the month, as appropriate. %%kk is replaced with "on _w_e_e_k_d_a_y_, _m_o_n_t_h _d_a_y_-_t_h" %%ll is replaced with "on _y_y_y_y_/_m_m_/_d_d" %%mm is replaced with "_m_o_n_t_h", the name of the month. %%nn is replaced with the number (1 to 12) of the month. %%oo is replaced with " (today)" if and only if the cur- rent system date is the same as the date being used by RReemmiinndd as the current date. Recall that you can specify a date for RReemmiinndd to use on the command line. This substitution is not generally useful in a RREEMM command, but is useful in a BBAANNNNEERR command. (See "The BANNER Command.") %%pp is replaced with "s" if the _d_i_f_f between the 13 October 1993 14 REMIND(1) REMIND(1) current date and the trigger date is not 1. You can use this to construct reminders like: REM 1 Jan +4 MSG %x day%p to go before New Year! %%qq is replaced with "'s" if the _d_i_f_f between the trig- ger date and the current date is 1. Otherwise, it is replaced with "s'" This can be used as follows: REM 1 Jan +4 MSG New Year in %x day%q time! %%rr is replaced with the day of the month (01 to 31) padded with a leading zero if needed to pad to two digits. %%ss is replaced with "st", "nd", "rd" or "th" depending on the day of the month. %%tt is replaced with the number of the month (01 to 12) padded to two digits with a leading zero. %%uu is replaced with "on _w_e_e_k_d_a_y_, _d_a_y_-_t_h _m_o_n_t_h_, _y_e_a_r" This is similar to %%aa except that "st", "nd", "rd" or "th" is added to the _d_a_y as appropriate. %%vv is replaced with "on _w_e_e_k_d_a_y_, _d_a_y_-_t_h _m_o_n_t_h" %%ww is replaced with "_w_e_e_k_d_a_y", the name of the day of the week. %%xx is replaced with the _d_i_f_f between the current date and the trigger date. The _d_i_f_f is defined as the actual number of days between these two dates; OOMMIITTss are not counted. (Strict date subtraction is performed.) %%yy is replaced with "_y_e_a_r", the year of the trigger date. %%zz is replaced with "_y_y", the last two digits of the year. %%__ (percent-underscore) is replaced with a newline. You can use this to achieve multi-line reminders. %%11 is replaced with "now", "_m minutes from now", "_m minutes ago", "_h hours from now", "_h hours ago", "_h hours and _m minutes from now" or "_h hours and _m minutes ago", as appropriate for a timed reminder. Note that unless you specify the --aa option, timed reminders will be triggered like normal reminders, and thus a timed reminder which occurred earlier in the day may be triggered. This causes the need for the "...ago" forms. %%22 is replaced with "at _h_h:_m_mam" or "..pm" depending 13 October 1993 15 REMIND(1) REMIND(1) on the AATT time of the reminder. %%33 is replaced with "at _h_h:_m_m" in 24-hour format. %%44 is replaced with "_m_m" where _m_m is the number of minutes between "now" and the time specified by AATT. If the AATT time is earlier than the current time, then the result is negative. %%55 is replaced with "_m_a" where _m_a is the absolute value of the number produced by %%44. %%66 is replaced with "ago" or "from now", depending on the relationship between the AATT time and the cur- rent time. %%77 is replaced with the number of hours between the AATT time and the current time. It is always non- negative. %%88 is replaced with the number of minutes between the AATT time and the current time, after the hours (%%77) have been subtracted out. This is a number ranging from 0 to 59. %%99 is replaced with "s" if the value produced by %%88 is not 1. %%00 is replaced with "s" if the value produced by %%77 is not 1. %%!! is replaced with "is" if the current time is before the AATT time, or "was" if it is after. %%@@ is similar to %%22 but displays the current time. %%## is similar to %%33 but displays the current time. %%"" (percent-doublequote) is removed. This sequence is not used by the substitution filter, but is used to tell RReemmiinndd which text to include in a calendar entry when the --cc, --ss or --pp option is chosen. See "Calendar Mode" Notes: o RReemmiinndd normally prints a blank line after each reminder; if the last character of the body is "%", the blank line will not be printed. o Substitutions a, b, c, e, f, g, h, i, j, k, l, u and v all are replaced with "today" if the current date equals the trigger date, or "tomorrow" if the trigger date is one day after the current date. 13 October 1993 16 REMIND(1) REMIND(1) Thus, they are nnoott the same as substitutions built up from the simpler %w, %y, etc. sequences. o Any of the substitutions dealing with time (0 through 9 and '!') produce undefined results if used in a reminder which does not have an AATT key- word. Also, if a reminder has a _d_e_l_t_a and may be triggered on several days, the time substitutions ignore the date. Thus, the %%11 substitution may report that a meeting is in 15 minutes, for exam- ple, even though it may only be in 2 days time, because a _d_e_l_t_a has triggered the reminder. It is recommended that you use the time substitutions only in timed reminders with no _d_e_l_t_a which are designed to be queued for timed activation. o Capital letters can be used in the substitution sequence, in which case the first character of the substituted string is capitalized (if it is nor- mally a lower-case letter.) o All other characters following a "%" sign are sim- ply copied. In particular, to get a "%" sign out, use "%%" in the body. To start the body of a reminder with a space, use "% ", since RReemmiinndd nor- mally scans for the first non-space character after a MMSSGG,, CCAALL or RRUUNN token. TTHHEE OOMMIITT CCOOMMMMAANNDD In addition to being a keyword in the RREEMM command, OOMMIITT is a command in its own right. Its syntax is: OOMMIITT _d_a_y _m_o_n_t_h [_y_e_a_r] The OOMMIITT command is used to "globally" omit certain days, which are usually holidays. These globally-omitted days are skipped by the "-" and "+" forms of _b_a_c_k and _d_e_l_t_a. Some examples: OMIT 1 Jan OMIT 7 Sep 1992 The first example specifies a holiday which occurs on the same date each year - New Year's Day. The second example specifies a holiday which changes each year - Labour Day. For these types of holidays, you must create an OOMMIITT com- mand for each year. (Later, in the description of expres- sions and some of the more advanced features of RReemmiinndd, you will see how to automate this for some cases.) For convenience, you can use a _d_e_l_t_a and MMSSGG or RRUUNN key- word in the OOMMIITT command. The following sequences are exactly equivalent: 13 October 1993 17 REMIND(1) REMIND(1) OMIT 1 Jan REM 1 Jan +4 MSG New year's day is %b! and OMIT 1 Jan +4 MSG New year's day is %b! TTHHEE BBEEFFOORREE,, AAFFTTEERR AANNDD SSKKIIPP KKEEYYWWOORRDDSS Normally, days which are omitted, whether by a global OOMMIITT command or the local OOMMIITT keyword in a RREEMM statement, only affect the counting of the -_b_a_c_k or the +_d_e_l_t_a. For exam- ple, suppose you have a meeting every Wednesday. Suppose, too, that you have indicated 11 Nov as a holiday: OMIT 11 Nov +4 MSG Remembrance Day REM Wed +1 MSG Code meeting %b. The above sequence will issue a reminder about a meeting for 11 November 1992, which is a Wednesday. This is prob- ably incorrect. There are three options: BBEEFFOORREE This keyword moves the reminder to before any omit- ted days. Thus, in the above example, use of BBEEFFOORREE would cause the meeting reminder to be trig- gered on Tuesday, 10 November 1992. AAFFTTEERR This keyword moves the reminder to after any omit- ted days. In the above example, the meeting reminder would be triggered on Thursday, 12 Novem- ber 1992. SSKKIIPP This keyword causes the reminder to be skipped com- pletely on any omitted days. Thus, in the above example, the reminder would not be triggered on 11 November 1992. However, it would be triggered as usual on the following Wednesday, 18 November 1992. The BBEEFFOORREE and AAFFTTEERR keywords move the trigger date of a reminder to before or after a block of omitted days, respectively. Suppose you normally run a backup on the first day of the month. However, if the first day of the month is a weekend or holiday, you run the backup on the first working day following the weekend or holiday. You could use: REM 1 OMIT Sat Sun AFTER RUN do_backup Let's examine how the trigger date is computed. The 11 specifies the first day of the month. The local OOMMIITT key- word causes the AAFFTTEERR keyword to move the reminder forward past weekends. Finally, the AAFFTTEERR keyword will keep mov- ing the reminder forward until it has passed any holidays specified with global OOMMIITT commands. 13 October 1993 18 REMIND(1) REMIND(1) TTHHEE IINNCCLLUUDDEE CCOOMMMMAANNDD RReemmiinndd allows you to include other files in your reminder script, similar to the C preprocessor #include directive. For example, your system administrator may maintain a file of holidays or system-wide reminders. You can include these in your reminder script as follows: INCLUDE /usr/share/remind/holidays INCLUDE /usr/share/remind/reminders (The actual pathnames vary from system to system - ask your system administrator.) IINNCCLLUUDDEE files can be nested up to a depth of 8. If you specify a filename of "-" in the IINNCCLLUUDDEE command, RReemmiinndd will begin reading from standard input. TTHHEE RRUUNN CCOOMMMMAANNDD If you include other files in your reminder script, you may not always entirely "trust" the contents of the other files. For example, they may contain RRUUNN-type reminders which could be used to access your files or perform unde- sired actions. The RRUUNN command can restrict this: If you include the command RRUUNN OOFFFF in your top-level reminder script, any reminder or expression which would normally execute a system command is disabled. RRUUNN OONN will re- enable the execution of system commands. Note that the RRUUNN OONN command can _o_n_l_y be used in your top-level reminder script; it will _n_o_t work in any files accessed by the IINNCCLLUUDDEE command. This is to protect you from someone placing a RRUUNN OONN command in an included file. However, the RRUUNN OOFFFF command can be used at top level or in an included file. If you run RReemmiinndd with the --rr command-line option, RRUUNN- type reminders and the sshheellll(()) function will be disabled, regardless of any RRUUNN commands in the reminder script. However, any command supplied with the --kk option will still be executed. One use of the RRUUNN command is to provide a secure inter- face between RReemmiinndd and the EEllmm mail system. The EEllmm sys- tem can automatically scan incoming mail for reminder or calendar entries, and place them in your calendar file. To use this feature, you should set the calendar filename option under EEllmm to be something like "~/.reminders.in", _n_o_t your main reminder file! This is so that any RRUUNN OONN commands mailed to you can never be activated. Then, you can use the EEllmm _s_c_a_n _m_e_s_s_a_g_e _f_o_r _c_a_l_e_n_d_a_r _e_n_t_r_i_e_s command to place reminders prefaced by "->" into .reminders.in. In your main .reminders file, include the following lines: 13 October 1993 19 REMIND(1) REMIND(1) RUN OFF # Disable RUN INCLUDE .reminders.in RUN ON # Re-enable RUN TTHHEE BBAANNNNEERR CCOOMMMMAANNDD When RReemmiinndd first issues a reminder, it prints a message like this: Reminders for Friday, 30th October, 1992 (today): (The banner is not printed if any of the calendar- producing options is used, or if the --kk option is used.) The BBAANNNNEERR command lets you change the format. It should appear before any RREEMM commands. The format is: BBAANNNNEERR _f_o_r_m_a_t The _f_o_r_m_a_t is similar to the _b_o_d_y of a RREEMM command. It is passed through the substitution filter, with an implicit trigger of the current system date. Thus, the default banner is equivalent to: BANNER Reminders for %w, %d%s %m, %y%o: You can disable the banner completely with BANNER %. Or you can create a custom banner: BANNER Hi - here are your reminders for %y/%t/%r: CCOONNTTRROOLLLLIINNGG TTHHEE OOMMIITT CCOONNTTEEXXTT Sometimes, it is necessary to temporarily change the global OOMMIITTss which are in force for a few reminders. Three commands allow you to do this: PPUUSSHH--OOMMIITT--CCOONNTTEEXXTT This command saves the current global OOMMIITTss on an internal stack. CCLLEEAARR--OOMMIITT--CCOONNTTEEXXTT This command clears all of the global OOMMIITTss, start- ing you off with a "clean slate." PPOOPP--OOMMIITT--CCOONNTTEEXXTT This command restores the global OOMMIITTss which were saved by the most recent PPUUSSHH--OOMMIITT--CCOONNTTEEXXTT. For example, suppose you have a block of reminders which require a clear OOMMIITT context, and that they also introduce unwanted global OOMMIITTss which could interfere with later reminders. You could use the following fragment: PUSH-OMIT-CONTEXT # Save the current context 13 October 1993 20 REMIND(1) REMIND(1) CLEAR-OMIT-CONTEXT # Clean the slate # Block of reminders goes here POP-OMIT-CONTEXT # Restore the saved omit context EEXXPPRREESSSSIIOONNSS In certain contexts, to be described later, RReemmiinndd will accept expressions for evaluation. RReemmiinndd expressions resemble C expressions, but operate on different types of objects. DDAATTAA TTYYPPEESS RReemmiinndd expressions understand four types of objects: IINNTT The IINNTT data type consists of the integers repre- sentable in one machine word. The IINNTT data type corresponds to the C "int" type. SSTTRRIINNGG The SSTTRRIINNGG data type consists of strings of charac- ters. It is somewhat comparable to a C character array, but more closely resembles the string type in BASIC. TTIIMMEE The TTIIMMEE data type consists of times of the day. The TTIIMMEE data type is internally stored as an inte- ger representing the number of minutes since mid- night. DDAATTEE The DDAATTEE data type consists of dates (later than 1 January 1990.) Internally, DDAATTEE objects are stored as the number of days since 1 January 1990. CCOONNSSTTAANNTTSS The following examples illustrate constants in RReemmiinndd expressions: IINNTT ccoonnssttaannttss 12, 36, -10, 0, 1209 SSTTRRIINNGG ccoonnssttaannttss "Hello there", "This is a test", "\n\gosd\w", "" Note that the empty string is represented by "", and that backslashes in a string are _n_o_t inter- preted specially, as in they are in C. TTIIMMEE ccoonnssttaannttss 12:33, 0:01, 14:15, 16:42, 12.16, 13.00, 1.11 Note that TTIIMMEE constants are written in 24-hour format. Either the period or colon can be used to separate the minutes from the hours. However, Remind will consistently output times using only 13 October 1993 21 REMIND(1) REMIND(1) one separator character. (The output separator character is chosen at compile-time.) DDAATTEE ccoonnssttaannttss DDAATTEE constants are expressed as 'yyyy/mm/dd' or 'yyyy-mm-dd', and the single quotes _m_u_s_t be sup- plied. This distinguishes date constants from division or subtraction of integers. Examples: '1993/02/22', '1992-12-25', '1999/01/01' Note that DDAATTEE constants are _p_r_i_n_t_e_d without the quotes. Although either '-' or '/' is accepted as a date separator on input, when dates are printed, only one will be used. The choice of whether to use '-' or '/' is made at compile-time. Note also that versions of RReemmiinndd prior to 03.00.01 did not support date constants. In those versions, you must create dates using the ddaattee(()) function. Also, versions prior to 03.00.02 did not support the '-' date separator. OOPPEERRAATTOORRSS RReemmiinndd has the following operators. Operators on the same line have equal precedence, while operators on lower lines have lower precedence than those on higher lines. The operators approximately correspond to C operators. ! - (unary logical negation and arithmetic negation) * / % + - < <= > >= == != && || DDEESSCCRRIIPPTTIIOONN OOFF OOPPEERRAATTOORRSS !! Logical negation. Can be applied to an IINNTT type. If the operand is non-zero, returns zero. Other- wise, returns 1. -- Unary minus. Can be applied to an IINNTT. Returns the negative of the operand. ** Multiplication. Returns the product of two IINNTTs. // Integer division. Returns the quotient of two IINNTTs, discarding the remainder. %% Modulus. Returns the remainder upon dividing one IINNTT by another. 13 October 1993 22 REMIND(1) REMIND(1) ++ Has several uses. These are: IINNTT + IINNTT - returns the sum of two IINNTTs. IINNTT + TTIIMMEE or TTIIMMEE + IINNTT - returns a TTIIMMEE obtained by adding IINNTT minutes to the original TTIIMMEE. IINNTT + DDAATTEE or DDAATTEE + IINNTT - returns a DDAATTEE obtained by adding IINNTT days to the original DDAATTEE. SSTTRRIINNGG + SSTTRRIINNGG - returns a SSTTRRIINNGG which is the concatenation of the two original SSTTRRIINNGGs. SSTTRRIINNGG + anything or anything + SSTTRRIINNGG - converts the non-SSTTRRIINNGG argument to a SSTTRRIINNGG, and then per- forms concatenation. See the ccooeerrccee(()) function. -- Has several uses. These are: IINNTT - IINNTT - returns the difference of two IINNTTs. DDAATTEE - DDAATTEE - returns (as an IINNTT) the difference in days between two DDAATTEEs. TTIIMMEE - TTIIMMEE - returns (as an IINNTT) the difference in minutes between two TTIIMMEEs. DDAATTEE - IINNTT - returns a DDAATTEE which is IINNTT days ear- lier than the original DDAATTEE. TTIIMMEE - IINNTT - returns a TTIIMMEE which is IINNTT minutes earlier than the original TTIIMMEE. <<,, <<==,, >>,, aanndd >>== These are the comparison operators. They can take operands of any type, but both operands must be of the same type. The comparison operators return 1 if the comparison is true, or 0 if it is false. Note that string comparison is done following the lexical ordering of characters on your system, and that upper and lower case _a_r_e distinct for these operators. ====,, !!== == tests for equality, returning 1 if its operands are equal, and 0 if they are not. != tests for inequality. If the operands are not of the same type, == returns 0 and != returns 1. Again, string compar- isons are case-sensitive. &&&& This is the logical AND operator. Both of its operands must be of type IINNTT. It returns 1 if both operands are non-zero, and 0 otherwise. 13 October 1993 23 REMIND(1) REMIND(1) |||| This is the logical OR operator. Both of its operands must be of type IINNTT. It returns 1 if either operand is non-zero, and 0 otherwise. NNOOTTEESS Operators of equal precedence are _a_l_w_a_y_s evaluated from left to right, except where parentheses dictate otherwise. This is important, because the enhanced "+" and "-" opera- tors are not necessarily associative. For example: 1 + 2 + "string" + 3 + 4 yields "3string34" 1 + (2 + "string") + (3 + 4) yields "12string7" 12:59 + 1 + "test" yields "13:00test" 12:59 + (1 + "test") yields "12:591test" The logical operators are _n_o_t so-called short-circuit operators, as they are in C. Both operands are always evaluated. Thus, an expression such as: (f!=0) && (100/f <= 3) will cause an error if f is zero. VVAARRIIAABBLLEESS RReemmiinndd allows you to assign values to variables. The SSEETT command is used as follows: SSEETT _v_a_r _e_x_p_r _V_a_r is the name of a variable. It must start with a let- ter or underscore, and consist only of letters, digits and underscores. Only the first 12 characters of a variable name are significant. Variable names are _n_o_t case sensi- tive; thus, "Afoo" and "afOo" are the same variable. Examples: SET a 10 + (9*8) SET b "This is a test" SET mydir getenv("HOME") SET time 12:15 SET date today() Note that variables themselves have no type. They take on the type of whatever you store in them. To delete a variable, use the UUNNSSEETT command: UUNNSSEETT _v_a_r [_v_a_r...] For example, to delete all the variables declared above, use: 13 October 1993 24 REMIND(1) REMIND(1) UNSET a b mydir time date SSYYSSTTEEMM VVAARRIIAABBLLEESS In addition to the regular user variables, RReemmiinndd has sev- eral "system variables" which are used to query or control the operating state of RReemmiinndd. System variables are available starting from version 03.00.07 of RReemmiinndd. All system variables begin with a dollar sign '$'. They can be used in SSEETT commands and expressions just as regu- lar variables can. All system variables always hold val- ues of a specified type. In addition, some system vari- ables cannot be modified, and you cannot create new system variables. System variables can be initialized on the command line with the --ii option, but you may need to quote them to avoid having the shell interpret the dollar sign. System variable names are not case-sensitive. The following system variables are defined. Those marked "read-only" cannot be changed with the SSEETT command. All system variables hold values of type IINNTT, unless otherwise specified. $$CCaallccUUTTCC If 1 (the default), then RReemmiinndd uses C library functions to calculate the number of minutes between local and Universal Time Coordinated. This affects astronomical calculations (ssuunnrriissee(()) for example.) If 0, then you must supply the number of minutes between local and Universal Time Coordi- nated in the $$MMiinnssFFrroommUUTTCC system variable. $$CCaallMMooddee ((rreeaadd--oonnllyy)) If non-zero, then the --cc option was supplied on the command line. $$DDaaeemmoonn ((rreeaadd--oonnllyy)) If the daemon mode --zz was invoked, contains the number of minutes between wakeups. If not running in daemon mode, contains 0. For the MS-DOS ver- sion, always contains 0. $$DDoonnttFFoorrkk ((rreeaadd--oonnllyy)) If non-zero, then the --cc option was supplied on the command line. For the MS-DOS version, always con- tains 1. $$DDoonnttTTrriiggAAttss ((rreeaadd--oonnllyy)) If non-zero, then the --aa option was supplied on the command line. For the MS-DOS version, always con- tains 0. 13 October 1993 25 REMIND(1) REMIND(1) $$DDoonnttQQuueeuuee ((rreeaadd--oonnllyy)) If non-zero, then the --qq option was supplied on the command line. For the MS-DOS version, always con- tains 1. $$EEnnddSSeenntt ((SSTTRRIINNGG ttyyppee)) Contains a list of characters which end a sentence. The MMSSFF keyword inserts two spaces after these characters. Initially, $$EEnnddSSeenntt is set to ".!?" (period, exclamation mark, and question mark.) $$EEnnddSSeennttIIgg ((SSTTRRIINNGG ttyyppee)) Contains a list of characters which should be ignored when MMSSFF decides whether or not to place two spaces after a sentence. Initially, is set to "'>)]}"+CHAR(34) (single-quote, greater-than, right parenthesis, right bracket, right brace, and dou- ble-quote.) For example, the default values work as follows: MSF He said, "Huh! (Two spaces will follow this.)" Yup. because the final parenthesis and quote are ignored (for the purposes of spacing) when they follow a period. $$FFiirrssttIInnddeenntt The number of spaces by which to indent the first line of a MMSSFF-type reminder. The default is 0. $$FFoollddYYeeaarr The standard Unix library functions may have diffi- culty dealing with dates later than 2037. If this variable is set to 1, then the UTC calculations "fold back" years later than 2037 before using the Unix library functions. For example, to find out whether or not daylight savings time is in effect in June, 2077, the year is "folded back" to 2010, because both years begin on a Monday, and both are non-leapyears. The rules for daylight savings time are thus presumed to be identical for both years, and the Unix library functions can handle 2010. By default, this variable is 0. Set it to 1 if the sun or UTC functions misbehave for years greater than 2037. $$FFoorrmmWWiiddtthh The maximum width of each line of text for format- ting MMSSFF-type reminders. The default is 72. If an MMSSFF-type reminder contains a word too long to fit in this width, it will not be truncated - the width limit will be ignored. 13 October 1993 26 REMIND(1) REMIND(1) $$HHuusshhMMooddee ((rreeaadd--oonnllyy)) If non-zero, then the --hh option was supplied on the command line. $$IIggnnoorreeOOnnccee ((rreeaadd--oonnllyy)) If non-zero, then the --oo option was supplied on the command line, or a date different from today's true date was supplied. If non-zero, then OONNCCEE direc- tives will be ignored. $$IInnffDDeellttaa ((rreeaadd--oonnllyy)) If non-zero, then the --tt option was supplied on the command line. $$LLaattDDeegg,, $$LLaattMMiinn,, $$LLaattSSeecc These specify the latitude of your location. $$LLaatt-- DDeegg can range from -90 to 90, and the others from -59 to 59. Northern latitudes are positive; south- ern ones are negative. For southern latitudes, all three components should be negative. $$LLooccaattiioonn ((SSTTRRIINNGG ttyyppee)) This is a string specifying the name of your loca- tion. It is usually the name of your town or city. It can be set to whatever you like, but good style indicates that it should be kept consistent with the latitude and longitude system variables. $$LLoonnggDDeegg,, $$LLoonnggMMiinn,, $$LLoonnggSSeecc These specify the longitude of your location. $$LLoonnggDDeegg can range from -180 to 180. Western lon- gitudes are positive; eastern ones are negative. The latitude and longitude information is required for the functions ssuunnrriissee(()) and ssuunnsseett(()). Default values can be compiled into RReemmiinndd, or you can SSEETT the correct values at the start of your reminder scripts. $$MMaaxxSSaattIItteerr The maximum number of iterations for the SSAATTIISSFFYY clause (described later.) Must be at least 10. $$MMiinnssFFrroommUUTTCC The number of minutes between Universal Time Coor- dinated and local time. If $$CCaallccUUTTCC is non-zero, this is calculated upon startup of RReemmiinndd. Other- wise, you must set it explicitly. If $$CCaallccUUTTCC is zero, then $$MMiinnssFFrroommUUTTCC is used in the astronomical calculations. You must adjust it for daylight sav- ings time yourself. Also, if you want to initial- ize $$MMiinnssFFrroommUUTTCC using the --ii command-line option, you must also set $$CCaallccUUTTCC to 0 with the --ii option. 13 October 1993 27 REMIND(1) REMIND(1) $$NNeexxttMMooddee ((rreeaadd--oonnllyy)) If non-zero, then the --nn option was supplied on the command line. $$NNuummQQuueeuueedd ((rreeaadd--oonnllyy)) Contains the number of reminders queued so far for background timed triggering. For MS-DOS, always returns 0. $$NNuummTTrriigg ((rreeaadd--oonnllyy)) Contains the number of reminders triggered for the current date. One use for this variable is as fol- lows: Suppose you wish to shade in the box of a PostScript calendar whenever a holiday is trig- gered. You could save the value of $$NNuummTTrriigg in a regular variable prior to executing a block of hol- iday reminders. If the value of $$NNuummTTrriigg after the holiday block is greater than the saved value, then at least one holiday was triggered, and you can execute the command to shade in the calendar box. (See the section "Calendar Mode".) Note that $$NNuummTTrriigg is affected _o_n_l_y by RREEMM com- mands; triggers in IIFFTTRRIIGG commands do not affect it. $$PPSSCCaall ((rreeaadd--oonnllyy)) If non-zero, then the --pp option was supplied on the command line. $$RRuunnOOffff ((rreeaadd--oonnllyy)) If non-zero, the RRUUNN directives are disabled. $$SSiimmpplleeCCaall ((rreeaadd--oonnllyy)) Set to a non-zero value if _e_i_t_h_e_r of the --pp or --ss command-line options was supplied. $$SSoorrttBByyDDaattee ((rreeaadd--oonnllyy)) Set to 0 if no --gg option is used, 1 if sorting by date in ascending order, or 2 if sorting by date in descending order. $$SSoorrttBByyPPrriioo ((rreeaadd--oonnllyy)) Set to 0 if no --gg option is used, 1 if sorting by priority in ascending order, or 2 if sorting by priority in descending order. $$SSoorrttBByyTTiimmee ((rreeaadd--oonnllyy)) Set to 0 if no --gg option is used, 1 if sorting by time in ascending order, or 2 if sorting by time in descending order. $$SSuubbssIInnddeenntt The number of spaces by which all lines (except the 13 October 1993 28 REMIND(1) REMIND(1) first) of an MMSSFF-type reminder should be indented. The default is 0. Note: If any of the calendar modes are in effect, then the values of $Daemon, $DontFork, $DontTrigAts, $Don- tQueue, $HushMode, $IgnoreOnce, $InfDelta, and $NextMode are not meaningful. BBUUIILLTT--IINN FFUUNNCCTTIIOONNSS RReemmiinndd has a plethora of built-in functions. The syntax for a function call is the same as in C - the function name, followed a comma-separated list of arguments in parentheses. Function names are not case-sensitive. If a function takes no arguments, it must be followed by "()" in the function call. Otherwise, RReemmiinndd will interpret it as a variable name, and probably not work correctly. In the descriptions below, short forms are used to denote acceptable types for the arguments. The characters "i", "s", "d" and "t" denote IINNTT, SSTTRRIINNGG, DDAATTEE and TTIIMMEE argu- ments, respectively. If an argument can be one of several types, the characters are concatenated. For example, "di_arg" denotes an argument which can be a DDAATTEE or an IINNTT. "x_arg" denotes an argument which can be of any type. The type of the argument is followed by an under- score and an identifier naming the argument, for conve- nience. The built-in functions are: aabbss((ii__nnuumm)) Returns the absolute value of _n_u_m. aacccceessss((ss__ffiillee,, ssii__mmooddee)) Tests the access permissions for the file _f_i_l_e. _M_o_d_e can be a string, containing a mix of the char- acters "rwx" for read, write and execute permission testing. Alternatively, _m_o_d_e can be a number as described in the UNIX aacccceessss(2) system call. The function returns 0 if the file can be accessed with the specified _m_o_d_e, and -1 otherwise. aarrggss((ss__ffnnaammee)) Returns the number of arguments expected by the user-defined function _f_n_a_m_e, or -1 if no such user- defined function exists. Note that this function examines only user-defined functions, not built-in functions. Its main use is to determine whether or not a particular user-defined function has been defined previously. The aarrggss(()) function is avail- able only in versions of RReemmiinndd from 03.00.04 and up. 13 October 1993 29 REMIND(1) REMIND(1) aasscc((ss__ssttrriinngg)) Returns an IINNTT which is the ASCII code of the first character in _s_t_r_i_n_g. As a special case, aasscc(("""")) returns 0. bbaasseeyyrr(()) Returns the "base year" which was compiled into RReemmiinndd (normally 1990.) All dates are stored internally as the number of days since 1 January of bbaasseeyyrr(()). cchhaarr((ii__ii11 [[,,ii__ii22......]])) This function can take any number of IINNTT arguments. It returns a SSTTRRIINNGG consisting of the characters specified by the arguments. Note that none of the arguments can be 0, unless there is only one argu- ment. As a special case, cchhaarr((00)) returns "". Note that because RReemmiinndd does not support escaping of characters in strings, the only way to get a double-quote in a string is to use cchhaarr((3344)). Yes, I know it's not portable - it assumes ASCII coding. cchhoooossee((ii__iinnddeexx,, xx__aarrgg11 [[,,xx__aarrgg22......]])) CChhoooossee must take at least two arguments, the first of which is an IINNTT. If _i_n_d_e_x is _n, then the _nth subsequent argument is returned. If _i_n_d_e_x is less than 1, then _a_r_g_1 is returned. If _i_n_d_e_x is greater than the number of subsequent arguments, then the last argument is returned. Examples: cchhoooossee((00,, ""ffoooo"",, 11::1133,, 11000000)) returns "foo" cchhoooossee((11,, ""ffoooo"",, 11::1133,, 11000000)) returns "foo" cchhoooossee((22,, ""ffoooo"",, 11::1133,, 11000000)) returns 1:13 cchhoooossee((33,, ""ffoooo"",, 11::1133,, 11000000)) returns 1000 cchhoooossee((44,, ""ffoooo"",, 11::1133,, 11000000)) returns 1000 Note that all arguments to cchhoooossee(()) are _a_l_w_a_y_s evaluated. ccooeerrccee((ss__ttyyppee,, xx__aarrgg)) This function converts _a_r_g to the specified _t_y_p_e, if such conversion is possible. _T_y_p_e must be one of "INT", "STRING", "DATE" or "TIME" (case- insensitive). The conversion rules are as follows: If _a_r_g is already of the _t_y_p_e specified, it is returned unchanged. If _t_y_p_e is "STRING", then _a_r_g is converted to a string consisting of its printed representation. If _t_y_p_e is "DATE", then an IINNTT _a_r_g is converted by interpreting it as the number of days since 1 Jan- uary bbaasseeyyrr(()). A SSTTRRIINNGG _a_r_g is converted by 13 October 1993 30 REMIND(1) REMIND(1) attempting to read it as if it were a printed date. A TTIIMMEE _a_r_g cannot be converted to a date. If _t_y_p_e is "TIME", then an IINNTT _a_r_g is converted by interpreting it as the number of minutes since mid- night. A SSTTRRIINNGG _a_r_g is converted by attempting to read it as if it were a printed time. A DDAATTEE _a_r_g cannot be converted to a time. If _t_y_p_e is "INT", then DDAATTEE and TTIIMMEE arguments are converted using the reverse of procedures described above. A SSTTRRIINNGG _a_r_g is converted by parsing it as an integer. ddaattee((ii__yy,, ii__mm,, ii__dd)) The ddaattee(()) function returns a DDAATTEE object with the year, month and day components specified by _y, _m and _d. ddaayy((dd__ddaattee)) This function takes a DDAATTEE as an argument, and returns an IINNTT which is the day-of-month component of _d_a_t_e. ddaayyssiinnmmoonn((ii__mm,, ii__yy)) Returns the number of days in month _m (1-12) of the year _y. ddeeffiinneedd((ss__vvaarr)) Returns 1 if the variable named by _v_a_r is defined, or 0 if it is not. Note that ddeeffiinneedd(()) takes a SSTTRRIINNGG argument; thus, to check if variable X is defined, use: defined("X") and not: defined(X) The second example will attempt to evaluate X, and will return an error if it is undefined or not of type SSTTRRIINNGG. ddoossuubbsstt((ss__ssttrr [[,,dd__ddaattee [[,,tt__ttiimmee]]]])) Returns a SSTTRRIINNGG which is the result of passing _s_t_r through the substitution filter described earlier. The parameters _d_a_t_e and _t_i_m_e establish the effec- tive trigger date and time used by the substitution filter. If _d_a_t_e and _t_i_m_e are omitted, they default to ttooddaayy(()) and nnooww(()). Note that if _s_t_r does not end with "%", a newline character will be added to the end of the result. 13 October 1993 31 REMIND(1) REMIND(1) Also, calling ddoossuubbsstt(()) with a _d_a_t_e which is in the past (i.e., if _d_a_t_e < ttooddaayy(())) will produce unde- fined results. DDoossuubbsstt(()) is only available starting from version 03.00.04 of RReemmiinndd. eeaasstteerrddaattee((ddii__aarrgg)) If _a_r_g is an IINNTT, then returns the date of Easter Sunday for the specified year. If _a_r_g is a DDAATTEE, then returns the date of the next Easter Sunday on or after _a_r_g. ffiilleeddaattee((ss__ffiilleennaammee)) Returns the modification date of _f_i_l_e_n_a_m_e. If _f_i_l_e_n_a_m_e does not exist, or its modification date is before the year bbaasseeyyrr(()), then 1 January of bbaasseeyyrr(()) is returned. ffiilleeddiirr(()) Returns the directory which contains the current file being processed. It may be a relative or absolute pathname, but is guaranteed to be correct for use in an IINNCCLLUUDDEE command as follows: INCLUDE [filedir()]/stuff This includes the file "stuff" in the same direc- tory as the current file being processed. ffiilleennaammee(()) Returns (as a SSTTRRIINNGG) the name of the current file being processed by RReemmiinndd. Inside included files, returns the name of the included file. ggeetteennvv((ss__eennvvvvaarr)) Similar to the ggeetteennvv(2) system call. Returns a string representing the value of the specified environment variable. Returns "" if the environ- ment variable is not defined. Note that the names of environment variables are generally case- sensitive; thus, getenv("HOME") is not the same as getenv("home"). hhoouurr((tt__ttiimmee)) Returns the hour component of _t_i_m_e. iiiiff((ssii__tteesstt11,, xx__aarrgg11,, [[ssii__tteesstt22,, xx__aarrgg22,,......]],, xx__ddeeffaauulltt)) If _t_e_s_t_1 is not zero or the null string, returns _a_r_g_1. Otherwise, if _t_e_s_t_2 is not zero or the null string, returns _a_r_g_2, and so on. If all of the _t_e_s_t arguments are false, returns _d_e_f_a_u_l_t. Note that all arguments are _a_l_w_a_y_s evaluated. This function accepts an odd number of arguments - note 13 October 1993 32 REMIND(1) REMIND(1) that prior to version 03.00.05 of RReemmiinndd, it accepted 3 arguments only. The 3-argument version of iiiiff(()) is compatible with previous versions of RReemmiinndd. iinnddeexx((ss__sseeaarrcchh,, ss__ttaarrggeett [[,,ii__ssttaarrtt)) Returns an IINNTT which is the location of _t_a_r_g_e_t in the string _s_e_a_r_c_h. The first character of a string is numbered 1. If _t_a_r_g_e_t does not exist in _s_e_a_r_c_h, then 0 is returned. The optional parameter _s_t_a_r_t specifies the position in _s_e_a_r_c_h at which to start looking for _t_a_r_g_e_t. iissddsstt(([[dd__ddaattee [[,,tt__ttiimmee]]]])) Returns a positive number if daylight savings time is in effect on the specified date and time. _D_a_t_e defaults to ttooddaayy(()) and _t_i_m_e defaults to midnight. Note that this function is only as reliable as the C run-time library functions. It is available starting with version 03.00.07 of RReemmiinndd. iisslleeaapp((iidd__aarrgg)) Returns 1 if _a_r_g is a leap year, and 0 otherwise. _A_r_g can be either an IINNTT or a DDAATTEE object. If a DDAATTEE is supplied, then the year component is used in the test. iissoommiitttteedd((dd__ddaattee)) Returns 1 if _d_a_t_e is omitted, given the current global OOMMIITT context. Returns 0 otherwise. hheebbddaattee((ii__ddaayy,, ss__hheebbmmoonn [[,,iidd__yyrrssttaarrtt [[,,ii__jjaahhrr [[,,ii__aaffllaagg]]]]]])) Support for Hebrew dates - see the section "The Hebrew Calendar" hheebbddaayy((dd__ddaattee)) Support for Hebrew dates - see the section "The Hebrew Calendar" hheebbmmoonn((dd__ddaattee)) Support for Hebrew dates - see the section "The Hebrew Calendar" hheebbyyeeaarr((dd__ddaattee)) Support for Hebrew dates - see the section "The Hebrew Calendar" llaanngguuaaggee(()) Returns a SSTTRRIINNGG naming the language supported by RReemmiinndd. (See "Foreign Language Support.") By default, RReemmiinndd is compiled to support English 13 October 1993 33 REMIND(1) REMIND(1) messages, so this function returns "English". For other languages, this function will return the English name of the language (e.g. "German") Note that llaanngguuaaggee(()) is not available in versions of RReemmiinndd prior to 03.00.02. lloowweerr((ss__ssttrriinngg)) Returns a SSTTRRIINNGG with all upper-case characters in _s_t_r_i_n_g converted to lower-case. mmaaxx((xx__aarrgg11 [[,,xx__aarrgg22......)) Can take any number of arguments, and returns the maximum. The arguments can be of any type, but must all be of the same type. They are compared as with the > operator. mmiinn((xx__aarrgg11 [[,,xx__aarrgg22......)) Can take any number of arguments, and returns the minimum. The arguments can be of any type, but must all be of the same type. They are compared as with the < operator. mmiinnssffrroommuuttcc(([[dd__ddaattee [[,,tt__ttiimmee]]]])) Returns the number of minutes from Universal Time Coordinated (formerly GMT) to local time on the specified date and time. _D_a_t_e defaults to ttooddaayy(()) and _t_i_m_e defaults to midnight. If local time is before UTC, the result is negative. Otherwise, the result is positive. Note that this function is only as reliable as the C run-time library functions. It is available starting with version 03.00.07 of RReemmiinndd. mmiinnuuttee((tt__ttiimmee)) Returns the minute component of _t_i_m_e. mmoonn((ddii__aarrgg)) If _a_r_g is of DDAATTEE type, returns a string which names the month component of the date. If _a_r_g is an IINNTT from 1 to 12, returns a string which names the month. mmoonnnnuumm((dd__ddaattee)) Returns an IINNTT from 1 to 12, representing the month component of _d_a_t_e. mmoooonnddaattee((ii__pphhaassee [[,,dd__ddaattee [[,,tt__ttiimmee]]]])) This function returns the date of the first occur- rence of the phase _p_h_a_s_e of the moon on or after _d_a_t_e and _t_i_m_e. _P_h_a_s_e can range from 0 to 3, with 0 signifying new moon, 1 first quarter, 2 full moon, and 3 third quarter. If _d_a_t_e is omitted, it defaults to ttooddaayy(()). If _t_i_m_e is omitted, it 13 October 1993 34 REMIND(1) REMIND(1) defaults to midnight. For example, the following returns the date of the next full moon: SET fullmoon moondate(2) mmoooonnttiimmee((ii__pphhaassee [[,,dd__ddaattee [[,,tt__ttiimmee]]]])) This function returns the time of the first occur- rence of the phase _p_h_a_s_e of the moon on or after _d_a_t_e and _t_i_m_e. _P_h_a_s_e can range from 0 to 3, with 0 signifying new moon, 1 first quarter, 2 full moon, and 3 third quarter. If _d_a_t_e is omitted, it defaults to ttooddaayy(()). If _t_i_m_e is omitted, it defaults to midnight. MMoooonnttiimmee(()) is intended to be used in conjunction with mmoooonnddaattee(()). The mmoooonn-- ddaattee(()) and mmoooonnttiimmee(()) functions are accurate to within a couple of minutes of the times in "Old Farmer's Almanac" for Ottawa, Ontario. For example, the following returns the date and time of the next full moon: MSG Next full moon at [moontime(2)] on [moondate(2)] mmoooonnpphhaassee(([[dd__ddaattee [[,,tt__ttiimmee]]]])) This function returns the phase of the moon on _d_a_t_e and _t_i_m_e, which default to ttooddaayy(()) and midnight, respectively. The returned value is an integer from 0 to 359, representing the phase of the moon in degrees. 0 is a new moon, 180 is a full moon, 90 is first-quarter, etc. nnooww(()) Returns the current system time, as a TTIIMMEE type. oorrdd((ii__nnuumm)) Returns a string which is the ordinal number _n_u_m. For example, oorrdd((22)) returns "2nd", and oorrdd((221133)) returns "213th". oossttyyppee(()) Returns "UNIX" on UNIX systems, "MSDOS" on MS-DOS systems, and "OS/2" on OS/2 systems. If you run RReemmiinndd in an MS-DOS box under OS/2, this function returns "MSDOS". pplluurraall((ii__nnuumm [[,,ss__ssttrr11 [[,,ss__ssttrr22]]]])) Can take from one to three arguments. If one argu- ment is supplied, returns "s" if _n_u_m is not 1, and "" if _n_u_m is 1. If two arguments are supplied, returns _s_t_r_1 + "s" 13 October 1993 35 REMIND(1) REMIND(1) if _n_u_m is not 1. Otherwise, returns _s_t_r_1. If three arguments are supplied, returns _s_t_r_1 if _n_u_m is 1, and _s_t_r_2 otherwise. ppssmmoooonn((ii__pphhaassee [[,,ii__ssiizzee]])) Returns a SSTTRRIINNGG consisting of PostScript code to draw a moon in the upper-left hand corner of the calendar box. _P_h_a_s_e specifies the phase of the moon, and is 0 (new moon), 1 (first quarter), 2 (full moon) or 3 (third quarter). If _s_i_z_e is spec- ified, it controls the radius of the moon in PostScript units (1/72 inch.) If it is not speci- fied, the size of the day-number font is used. For example, the following four lines place moon symbols on the PostScript calendar: REM [trigger(moondate(0))] PS [psmoon(0)] REM [trigger(moondate(1))] PS [psmoon(1)] REM [trigger(moondate(2))] PS [psmoon(2)] REM [trigger(moondate(3))] PS [psmoon(3)] ppsssshhaaddee((ii__nnuumm)) Returns a SSTTRRIINNGG which consists of PostScript com- mands to shade a calendar box. _N_u_m can range from 0 (completely black) to 100 (completely white.) Here's an example of how to use this: REM Sat Sun PS [psshade(95)] The above command emits PostScript code to lightly shade the boxes for Saturday and Sunday in a PostScript calendar. rreeaallttooddaayy(()) Returns the date as provided by the operating sys- tem. This is in contrast to RReemmiinndd's concept of "today", which may be changed if it is running in calendar mode, or if a date has been supplied on the command line. ssggnn((ii__nnuumm)) Returns -1 if _n_u_m is negative, 1 if _n_u_m is posi- tive, and 0 if _n_u_m is zero. sshheellll((ss__ccmmdd)) Executes _c_m_d as a system command, and returns the first 511 characters of output resulting from _c_m_d. Any whitespace character in the output is converted to a space. Note that if RRUUNN OOFFFF has been exe- cuted, or the --rr command-line option has been used, sshheellll(()) will result in an error, and _c_m_d will not 13 October 1993 36 REMIND(1) REMIND(1) be executed. ssttrrlleenn((ss__ssttrr)) Returns the length of _s_t_r. ssuubbssttrr((ss__ssttrr,, ii__ssttaarrtt [[,,ii__eenndd]])) Returns a SSTTRRIINNGG consisting of all characters in _s_t_r from _s_t_a_r_t up to and including _e_n_d. Characters are numbered from 1. If _e_n_d is not supplied, then it defaults to the length of _s_t_r. ssuunnrriissee(([[dd__ddaattee]])) Returns a TTIIMMEE indicating the time of sunrise on the specified _d_a_t_e (default ttooddaayy(()).) In high lat- titudes, there may be no sunrise on a particular day, in which case ssuunnrriissee(()) returns the IINNTT 0. ssuunnsseett(([[dd__ddaattee]])) Returns a TTIIMMEE indicating the time of sunset on the specified _d_a_t_e (default ttooddaayy(()).) In high latti- tudes, there may be no sunset on a particular day, in which case ssuunnsseett(()) returns the IINNTT 0. The functions ssuunnrriissee(()) and ssuunnsseett(()) are based on an algorithm in "Almanac for Computers for the year 1978" by L. E. Doggett, Nautical Almanac Office, USNO. They require the latitude and longitude to be specified by setting the appropriate system variables. (See "System Variables".) The sun functions should be accurate to within about 2 min- utes for latitudes lower than 60 degrees. The functions are available starting from version 03.00.07 of RReemmiinndd. ttiimmee((ii__hhrr,, ii__mmiinn)) Creates a TTIIMMEE with the hour and minute components specified by _h_r and _m_i_n. ttooddaayy(()) Returns RReemmiinndd's notion of "today." This may be the actual system date, or a date supplied on the command line, or the date of the calendar entry currently being computed. ttrriiggddaattee(()) Returns the calculated trigger date of the last RREEMM or IIFFTTRRIIGG command. If used in the _b_o_d_y of a RREEMM command, returns that command's trigger date. ttrriiggggeerr((dd__ddaattee [[,,tt__ttiimmee [[,,ii__uuttccffllaagg]]]])) Returns a string suitable for use in a RREEMM command, allowing you to calculate trigger dates in advance. (See the section "Expression pasting" for more information.) Normally, the _d_a_t_e and _t_i_m_e are the 13 October 1993 37 REMIND(1) REMIND(1) local date and time; however, if _u_t_c_f_l_a_g is non- zero, the _d_a_t_e and _t_i_m_e are interpreted as UTC times, and are converted to local time. Examples: trigger('1993/04/01') returns "1 April 1993", trigger('1994/08/09', 12:33) returns "9 August 1994 AT 12:33", and trigger('1994/12/01', 03:00, 1) returns "30 November 1994 AT 22:00" for EST, which is 5 hours behind UTC. The value for your time zone may differ. ttrriiggttiimmee(()) Returns the time of the last RREEMM command with an AATT clause. ttrriiggvvaalliidd(()) Returns 1 if the value returned by ttrriiggddaattee(()) is valid for the most recent RREEMM command, or 0 other- wise. Sometimes RREEMM commands cannot calculate a trigger date. For example, the following RREEMM com- mand can never be triggered: REM Mon OMIT Mon SKIP MSG Impossible! ttyyppeeooff((xx__aarrgg)) Returns "STRING", "INT", "DATE" or "TIME", depend- ing on the type of _a_r_g. uuppppeerr((ss__ssttrriinngg)) Returns a SSTTRRIINNGG with all lower-case characters in _s_t_r_i_n_g converted to upper-case. vvaalluuee((ss__vvaarrnnaammee [[,,xx__ddeeffaauulltt]])) Returns the value of the specified variable. For example, value("X"+"Y") returns the value of vari- able XY, if it is defined. If XY is not defined, an error results. However, if you supply a second argument, it is returned if the _v_a_r_n_a_m_e is not defined. The expression value("XY", 0) will return 0 if XY is not defined, and the value of XY if it is defined. vveerrssiioonn(()) Returns a string specifying the version of RReemmiinndd. For version 03.00.04, returns "03.00.04". It is 13 October 1993 38 REMIND(1) REMIND(1) guaranteed that as new versions of RReemmiinndd are released, the value returned by vveerrssiioonn(()) will strictly increase, according to the rules for string ordering. wwkkddaayy((ddii__aarrgg)) If _a_r_g is a DDAATTEE, returns a string representing the day of the week of the date. If _a_r_g is an IINNTT from 0 to 6, returns the corresponding weekday ("Sunday" to "Saturday"). wwkkddaayynnuumm((dd__ddaattee)) Returns a number from 0 to 6 representing the day- of-week of the specified _d_a_t_e. (0 represents Sun- day, and 6 represents Saturday.) yyeeaarr((dd__ddaattee)) Returns a IINNTT which is the year component of _d_a_t_e. EEXXPPRREESSSSIIOONN PPAASSTTIINNGG An extremely powerful feature of RReemmiinndd is its macro capa- bility, or "expression pasting." In almost any situation where RReemmiinndd is not expecting an expression, you can "paste" an expression in. To do this, surround the expression with square brackets. For exam- ple: REM [trigger(mydate)] MSG foo This evaluates the expression "trigger(mydate)", where "mydate" is presumably some pre-computed variable, and then "pastes" the result into the command-line for the parser to process. A formal description of this is: When RReemmiinndd encounters a "pasted-in" expression, it evaluates the expression, and coerces the result to a SSTTRRIINNGG. It then substitutes the string for the pasted-in expression, and continues pars- ing. Note, however, that expressions are evaluated only once, not recursively. Thus, writing: ["[a+b]"] causes RReemmiinndd to read the token "[a+b]". It does not interpret this as a pasted-in expression. In fact, the only way to get a literal left-bracket into a reminder is to use ["["]. You can use expression pasting almost anywhere. However, there are a few exceptions: o If RReemmiinndd is expecting an expression, as in the SSEETT command, or the IIFF command, then no expression 13 October 1993 39 REMIND(1) REMIND(1) pasting takes place. The expression is simply evaluated as if the square brackets were not there. o You cannot use expression pasting for the first token on a line. For example, the following will not work: ["SET"] a 1 This restriction is because RReemmiinndd must be able to unambiguously determine the first token of a line for the flow-control commands (to be discussed later.) In fact, if RReemmiinndd cannot determine the first token on a line, it assumes that it is a RREEMM command. If expression-pasting is used, RReemmiinndd assumes it is a RREEMM command. Thus, the following three commands are equivalent: REM 12 Nov 1993 AT 13:05 MSG BOO! 12 Nov 1993 AT 13:05 MSG BOO! [12] ["Nov " + 1993] AT [12:05+60] MSG BOO! o You cannot use expression-pasting to determine the type (MMSSGG, CCAALL, etc.) of a RREEMM command. You can paste expressions before and after the MMSSGG, etc keywords, but cannot do something like this: REM ["12 Nov 1993 AT 13:05 " + "MSG" + " BOO!"] CCOOMMMMOONN PPIITTFFAALLLLSS IINN EEXXPPRREESSSSIIOONN PPAASSTTIINNGG Remember, when pasting in expressions, that extra spaces are not inserted. Thus, something like: REM[expr]MSG[expr] will probably fail. If you use an expression to calculate a _d_e_l_t_a or _b_a_c_k, ensure that the result is a positive number. Something like: REM +[mydelta] Nov 12 1993 MSG foo will fail if _m_y_d_e_l_t_a happens to be negative. FFLLOOWW CCOONNTTRROOLL CCOOMMMMAANNDDSS RReemmiinndd has commands which control the flow of a reminder script. Normally, reminder scripts are processed sequen- tially. However, IIFF and related commands allow you to process files conditionally, and skip sections which you 13 October 1993 40 REMIND(1) REMIND(1) don't want interpreted. TTHHEE IIFF CCOOMMMMAANNDD The IIFF command has the following form: IF expr t-command t-command... ELSE f-command f-command... ENDIF Note that the commands are shown indented for clarity. Also, the EELLSSEE portion can be omitted. IIFF commands can be nested up to a small limit, probably around 8 or 16 levels of nesting, depending on your system. If the _e_x_p_r evaluates to a non-zero IINNTT, or a non-null SSTTRRIINNGG, then the IIFF portion is considered true, and the _t_- _c_o_m_m_a_n_d_s are executed. If _e_x_p_r evaluates to zero or null, then the _f_-_c_o_m_m_a_n_d_s (if the EELLSSEE portion is present) are executed. If _e_x_p_r is not of type IINNTT or SSTTRRIINNGG, then it is an error. Examples: IF defined("want_hols") INCLUDE /usr/share/remind/holidays ENDIF IF today() > '1992/2/10' set missed_ap "You missed it!" ELSE set missed_ap "Still have time..." ENDIF TTHHEE IIFFTTRRIIGG CCOOMMMMAANNDD The IIFFTTRRIIGG command is similar to an IIFF command, except that it computes a trigger (as in the RREEMM command), and evaluates to true if a corresponding RREEMM command would trigger. Examples: IFTRIG 1 Nov ; Executed on 1 Nov ELSE ; Executed except on 1 Nov ENDIF IFTRIG 1 -1 OMIT Sat Sun +4 ; Executed on last working day of month, ; and the 4 working days preceding it 13 October 1993 41 REMIND(1) REMIND(1) ELSE ; Executed except on above days ENDIF Note that the IIFFTTRRIIGG command computes a trigger date, which can be retrieved with the ttrriiggddaattee(()) function. You can use all of the normal trigger components, such as UUNNTTIILL, _d_e_l_t_a, etc in the IIFFTTRRIIGG command. UUSSEERR--DDEEFFIINNEEDD FFUUNNCCTTIIOONNSS In addition to the built-in functions, RReemmiinndd allows you to define your own functions. The FFSSEETT command does this for you: FFSSEETT _f_n_a_m_e(_a_r_g_s) _e_x_p_r _F_n_a_m_e is the name of the function, and follows the conven- tion for naming variables. _A_r_g_s is a comma-separated list of arguments, and _e_x_p_r is an expression. _A_r_g_s can be empty, in which case you define a function taking no parameters. Here are some examples: FSET double(x) 2*x FSET yeardiff(date1, date2) year(date1) - year(date2) FSET since(x) ord(year(trigdate())-x) The last function is useful in birthday reminders. For example: REM 1 Nov +12 MSG Dean's [since(1984)] birthday is %b. Dean was born in 1984. The above example, on 1 November 1992, would print: Dean's 8th birthday is today. Notes: o If you access a variable in _e_x_p_r which is not in the list of arguments, the "global" value (if any) is used. o Function and parameter names are significant only to 12 characters. o The vvaalluuee(()) function _a_l_w_a_y_s accesses the "global" value of a variable, even if it has the same name as an argument. For example: fset func(x) value("x") set x 1 set y func(5) 13 October 1993 42 REMIND(1) REMIND(1) The above sequence sets y to 1, which is the global value of x. o User-defined functions may call other functions, including other user-defined functions. However, recursive calls are not allowed. o User-defined functions are not syntax-checked when they are defined; parsing occurs only when they are called. o If a user-defined function has the same name as a built-in function, it is ignored and the built-in function is used. To prevent conflicts with future versions of RReemmiinndd (which may define more built-in functions), you may wish to name all user-defined functions beginning with an underscore. PPRREECCIISSEE SSCCHHEEDDUULLIINNGG The SSCCHHEEDD keyword allows precise control over the schedul- ing of timed reminders. It should be followed by the name of a user-defined function, _s_c_h_e_d___f_u_n_c_t_i_o_n. If a scheduling function is supplied, then it must take one argument of type IINNTT. Rather than using the AATT time, time _d_e_l_t_a, and time _r_e_p_e_a_t, RReemmiinndd calls the scheduling function to determine when to trigger the reminder. The first time the reminder is queued, the scheduling function is called with an argument of 1. Each time the reminder is triggered, it is re-scheduled by calling the scheduling function again. On each call, the argument is incremented by one. The return value of the scheduling function must be an IINNTT or a TTIIMMEE. If the return value is a TTIIMMEE, then the reminder is re-queued to trigger at that time. If it is a positive integer _n, then the reminder is re-queued to trigger at the previous trigger time plus _n minutes. Finally, if it is a negative integer or zero, then the reminder is re-queued to trigger _n minutes before the AATT time. Note that there must be an AATT clause for the SSCCHHEEDD clause to do anything. Here's an example: FSET _sfun(x) choose(x, -60, 30, 15, 10, 3, 1, 1, 1, 1, 0) REM AT 13:00 SCHED _sfun MSG foo The reminder would first be triggered at 13:00-60 minutes, or at 12:00. It would next be triggered 30 minutes later, at 12:30. Then, it would be triggered at 12:45, 12:55, 12:58, 12:59, 13:00, 13:01 and 13:02. 13 October 1993 43 REMIND(1) REMIND(1) NNOOTTEESS 1 If an error occurs during the evaluation of _s_c_h_e_d___f_u_n_c, then RReemmiinndd reverts to using the AATT time and the _d_e_l_t_a and _r_e_p_e_a_t values, and never calls _s_c_h_e_d___f_u_n_c again. 2 If processing _s_c_h_e_d___f_u_n_c yields a time earlier than the current system time, it is repeatedly called with increasing argument until it yields a value greater than or equal to the current time. How- ever, if the sequence of values calculated during the repetition is not strictly increasing, then RReemmiinndd reverts to the default behaviour and never calls _s_c_h_e_d___f_u_n_c again. 3 It is quite possible using _s_c_h_e_d___f_u_n_c to keep trig- gering a reminder even after the AATT-time. However, it is not possible to reschedule a reminder past midnight - no crossing of date boundaries is allowed. Also, it is quite possible to nnoott trigger a reminder on the AATT time when you use a scheduling function. However, if your scheduling function is terminated (for reasons 1 and 2) before the AATT time of the reminder, it _w_i_l_l be triggered at the AATT time, because normal processing takes over. 4 Your scheduling functions should (as a matter of good style) return 0 when no more scheduling is required. See the example. 5 All scheduling functions are evaluated _a_f_t_e_r the entire Remind script has been read in. So whatever function definitions are in effect at the end of the script are used. TTHHEE SSAATTIISSFFYY CCLLAAUUSSEE The form of RREEMM which uses SSAATTIISSFFYY is as follows: RREEMM _t_r_i_g_g_e_r SSAATTIISSFFYY _e_x_p_r The way this works is as follows: RReemmiinndd first calculates a trigger date, in the normal fashion. Next, it sets ttrriiggddaattee(()) to the calculated trigger date. It then evalu- ates _e_x_p_r. If the result is not the null string or zero, processing ends. Otherwise, RReemmiinndd computes the next trigger date, and re-tests _e_x_p_r. This iteration continues until _e_x_p_r evaluates to non-zero or non-null, or until the iteration limit specified with the --xx command-line option is reached. If _e_x_p_r is not satisfied, then ttrriiggvvaalliidd(()) is set to 0. Otherwise, ttrriiggvvaalliidd(()) is set to 1. In any event, no 13 October 1993 44 REMIND(1) REMIND(1) error message is issued. This is really useful only if _e_x_p_r involves a call to the ttrriiggddaattee(()) function; otherwise, _e_x_p_r will not change as RReemmiinndd iterates. An example of the usefulness of SSAATTIISSFFYY: Suppose you wish to be warned of every Friday the 13th. Your first attempt may be: # WRONG! REM Fri 13 +2 MSG Friday the 13th is %b. But this won't work. This reminder triggers on the first Friday on or after the 13th of each month. The way to do it is with a more complicated sequence: REM 13 SATISFY wkdaynum(trigdate()) == 5 IF trigvalid() REM [trigger(trigdate())] +2 MSG \ Friday the 13th is %b. ENDIF Let's see how this works. The SSAATTIISSFFYY clause iterates through all the 13ths of successive months, until a trig- ger date is found whose day-of-week is Friday (== 5). If a valid date was found, we use the calculated trigger date (converted into a trigger format with the ttrriiggggeerr(()) func- tion) to set up the next reminder. We could also have written: REM Fri SATISFY day(trigdate()) == 13 but this would result in more iterations, since "Fridays" occur more often than "13ths of the month." This technique of using one RREEMM command to calculate a trigger date to be used by another command is quite power- ful. For example, suppose you wanted to OMIT Labour day, which is the first Monday in September. You could use: # Note: SATISFY 1 is an idiom for "do nothing" REM Mon 1 Sept SATISFY 1 OMIT [trigger(trigdate())] CCAAVVEEAATT:: This _o_n_l_y omits the _n_e_x_t Labour Day, not all Labour Days in the future. This could cause strange results, as the OOMMIITT context can change depending on the current date. For example, if you use the following com- mand after the above commands: REM Mon AFTER msg hello 13 October 1993 45 REMIND(1) REMIND(1) the result will not be as you expect. Consider producing a calendar for September, 1992. Labour Day was on Monday, 7 September, 1992. However, when RReemmiinndd gets around to calculating the trigger for Tuesday, 8 September, 1992, the OOMMIITT command will now be omitting Labour Day for 1993, and the "Mon AFTER" command will not be triggered. (But see the description of SSCCAANNFFRROOMM in the section "Details about Trigger Computation.") It is probably best to stay away from computing OOMMIITT trig- ger dates unless you keep these pitfalls in mind. For versions of RReemmiinndd starting from 03.00.07, you can include a MMSSGG, RRUUNN, etc. clause in a SSAATTIISSFFYY clause as follows: REM trigger_stuff SATISFY [expr] MSG body Note that for this case only, the _e_x_p_r after SSAATTIISSFFYY _m_u_s_t be enclosed in braces. It must come after all the other components of the trigger, and immediately before the MMSSGG, RRUUNN, etc. keyword. If _e_x_p_r cannot be satisfied, then the reminder is not triggered. Thus, the "Friday the 13th" example can be expressed more compactly as: REM 13 +2 SATISFY [wkdaynum(trigdate()) == 5] \ MSG Friday the 13th is %b. And you can trigger a reminder on Mondays, Wednesdays and Thursdays occurring on odd-numbered days of the month with the following: REM Mon Wed Thu SATISFY [day(trigdate())%2] \ MSG Here it is!!! DDEEBBUUGGGGIINNGG RREEMMIINNDDEERR SSCCRRIIPPTTSS Although the command-line --dd option is useful for debug- ging, it is often overkill. For example, if you turn on the --ddxx option for a reminder file with many complex expressions, you'll get a huge amount of output. The DDEEBBUUGG command allows you to control the debugging flags under program control. The format is: DDEEBBUUGG [+_f_l_a_g_s_o_n] [-_f_l_a_g_s_o_f_f] _F_l_a_g_s_o_n and _f_l_a_g_s_o_f_f consist of strings of the characters "extvl" which correspond to the debugging options dis- cussed in the command-line options section. If preceded with a "+", the corresponding group of debugging options is switched on. Otherwise, they are switched off. For example, you could use this sequence to debug a 13 October 1993 46 REMIND(1) REMIND(1) complicated expression: DEBUG +x set a very_complex_expression(many_args) DEBUG -x TTHHEE DDUUMMPPVVAARRSS CCOOMMMMAANNDD The command DDUUMMPPVVAARRSS displays the values of variables in memory. Its format is: DDUUMMPPVVAARRSS [_v_a_r...] If you supply a space-separated list of variable names, the corresponding variables are displayed. If you do not supply a list of variables, then all variables in memory are displayed. To dump a system variable, put its name in the list of variables to dump. If you put a lone dollar sign in the list of variables to dump, then all system variables will be dumped. TTHHEE EERRRRMMSSGG CCOOMMMMAANNDD The EERRRRMMSSGG command has the following format: EERRRRMMSSGG _b_o_d_y The _b_o_d_y is passed through the substitution filter (with an implicit trigger date of ttooddaayy(())) and printed to the error output stream. Example: IF !defined("critical_var") ERRMSG You must supply a value for "critical_var" EXIT ENDIF TTHHEE EEXXIITT CCOOMMMMAANNDD The above example also shows the use of the EEXXIITT command. This causes an unconditional exit from script processing. Any queued timed reminders are discarded. If you are in calendar mode (described next), then the calendar process- ing is aborted. If you supply an IINNTT-type expression after the EEXXIITT com- mand, it is returned to the calling program as the exit status. Otherwise, an exit status of 99 is returned. TTHHEE FFLLUUSSHH CCOOMMMMAANNDD This command simply consists of the word FFLLUUSSHH on a line by itself. The command flushes the standard output and standard error streams used by RReemmiinndd. This is not terri- bly useful to most people, but may be useful if you run 13 October 1993 47 REMIND(1) REMIND(1) RReemmiinndd as a subprocess of another program, and want to use pipes for communication. CCAALLEENNDDAARR MMOODDEE If you supply the --cc, --ss or --pp command-line option, then RReemmiinndd runs in "calendar mode." In this mode, RReemmiinndd interprets the script repeatedly, performing one iteration through the whole file for each day in the calendar. Reminders which trigger are saved in internal buffers, and then inserted into the calendar in the appropriate places. If you also supply the --aa option, then RReemmiinndd will not include timed reminders in the calendar. The --pp option is used in conjunction with the rreemm22ppss pro- gram to produce a calendar in PostScript format. For example, the following command will send PostScript code to standard output: remind -p .reminders | rem2ps You can print a PostScript calendar by piping this to the llpprr command. If you have a reminder script called ".reminders", and you execute this command: remind -c .reminders jan 1993 then RReemmiinndd executes the script 31 times, once for each day in January. Each time it executes the script, it increments the value of ttooddaayy(()). Any reminders whose trigger date matches ttooddaayy(()) are entered into the calen- dar. MMSSGG and CCAALL-type reminders, by default, have their entire body inserted into the calendar. RRUUNN-type reminders are not normally inserted into the calendar. However, if you enclose a portion of the body in the %"...%" sequence, only that portion is inserted. For example, consider the following: REM 6 Jan MSG %"David's birthday%" is %b In the normal mode, RReemmiinndd would print "David's birthday is today" on 6 January. However, in the calendar mode, only the text "David's birthday" is inserted into the box for 6 January. If you explicitly use the %"...%" sequence in a RRUUNN-type reminder, then the text between the delimiters is inserted into the calendar. If you use the sequence %"%" in a MMSSGG or CCAALL-type reminder, then no calendar entry is produced 13 October 1993 48 REMIND(1) REMIND(1) for that reminder. PPRREESSEERRVVIINNGG VVAARRIIAABBLLEESS Because RReemmiinndd iterates through the script for each day in the calendar, slow operations may severely reduce the speed of producing a calendar. For example, suppose you set the variables "me" and "host- name" as follows: SET me shell("whoami") SET hostname shell("hostname") Normally, RReemmiinndd clears all variables between iterations in calendar mode. However, if certain variables are slow to compute, and will not change between iterations, you can "preserve" their values with the PPRREESSEERRVVEE command. Also, since function definitions are preserved between calendar iterations, there is no need to redefine them on each iteration. Thus, you could use the following sequence: IF ! defined("initialized") set initialized 1 set me shell("whoami") set hostname shell("hostname") fset func(x) complex_expr preserve initialized me hostname ENDIF The operation is as follows: On the first iteration through the script, "initialized" is not defined. Thus, the commands between IIFF and EENNDDIIFF are executed. The PPRREE-- SSEERRVVEE command ensures that the values of initialized, me and hostname are preserved for subsequent iterations. On the next iteration, the commands are skipped, since ini- tialized has remained defined. Thus, time-consuming oper- ations which do not depend on the value of ttooddaayy(()) are done only once. System variables (those whose names start with '$') are automatically preserved between calendar iterations. Note that for efficiency, RReemmiinndd caches the reminder script (and any IINNCCLLUUDDEEd files) in memory when producing a calendar. Timed reminders are sorted and placed into the calendar in time order. These are followed by non-timed reminders. RReemmiinndd automatically places the time of timed reminders in the calendar according to the --bb command-line option. Reminders in calendar mode are sorted as if the --gg option had been used; you can change the sort order in calendar 13 October 1993 49 REMIND(1) REMIND(1) mode by explicitly using the --gg option to specify a dif- ferent order from the default. RREEPPEEAATTEEDD EEXXEECCUUTTIIOONN If you supply a _r_e_p_e_a_t parameter on the command line, and do not use the --cc, --pp, or --ss options, RReemmiinndd operates in a similar manner to calendar mode. It repeatedly executes the reminder script, incrementing ttooddaayy(()) with each itera- tion. The same rules about preserving variables and func- tion definitions apply. Note that using _r_e_p_e_a_t on the command line also enables the --qq option and disables any --zz option. As an example, if you want to see how RReemmiinndd will behave for the next week, you can type: remind .reminders '*7' If you want to print the dates of the next 1000 days, use: (echo 'banner %'; echo 'msg [today()]%') | remind - '*1000' IINNIITTIIAALLIIZZIINNGG VVAARRIIAABBLLEESS OONN TTHHEE CCOOMMMMAANNDD LLIINNEE The --ii option is used to initialize variables on the RReemmiinndd command line. The format is --ii_v_a_r==_e_x_p_r, where _e_x_p_r is any valid expression. Note that you may have to use quotes or escapes to prevent the shell from interpreting special characters in _e_x_p_r. You can have as many --ii options as you want on the command line, and they are pro- cessed in order. Thus, if a variable is defined in one --ii option, it can be referred to by subsequent --ii options. Note that if you supply a date on the command line, it is not parsed until all options have been processed. Thus, if you use ttooddaayy(()) in any of the --ii expressions, it will return the same value as rreeaallttooddaayy(()) and not the date sup- plied on the command line. Any variables defined on the command line are pprreesseerrvveedd as with the PPRREESSEERRVVEE command. You should not have any spaces between the --ii option and the equal sign; otherwise, strange variable names are cre- ated which can only be accessed with the vvaalluuee(()) or ddeeffiinneedd(()) functions. If your site uses the RReemmiinndd--aallll shell script to mail reminders to users, the script will initialize the vari- able _r_e_m_i_n_d___a_l_l to 1 using the --ii option. Thus, you can detect when your reminder script is being processed by RReemmiinndd--aallll and can use this information to control which reminders you want mailed to you. 13 October 1993 50 REMIND(1) REMIND(1) MMOORREE AABBOOUUTT PPOOSSTTSSCCRRIIPPTT The PPSS and PPSSFFIILLEE reminders pass PostScript code directly to the printer. They differ in that the PPSS-type reminder passes its body directly to the PostScript output (after processing by the substitution filter) while the PPSSFFIILLEE- type's body should simply consist of a filename. The RReemm22ppss program will open the file named in the PPSSFFIILLEE-type reminder, and include its contents in the PostScript out- put. The PostScript-type reminders for a particular day are included in the PostScript output in sorted order of pri- ority. Note that the order of PostScript commands has a _m_a_j_o_r impact on the appearance of the calendars. For example, PostScript code to shade a calendar box will obliterate code to draw a moon symbol if the moon symbol code is placed in the calendar first. For this reason, you should not provide PPSS or PPSSFFIILLEE-type reminders with priorities; instead, you should ensure that they appear in the reminder script in the correct order. PostScript code should draw objects working from the background to the foreground, so that foreground objects properly overlay background ones. If you prioritize these reminders and run the script using descending sort order for priorities, the PostScript output will not work. All of the PostScript code for a particular date is enclosed in a ssaavvee-rreessttoorree pair. However, if several PostScript-type reminders are triggered for a single day, each section of PostScript is not enclosed in a ssaavvee- rreessttoorree pair - instead, the entire body of included PostScript is enclosed. PostScript-type reminders are executed by the PostScript printer before any regular calendar entries. Thus, regu- lar calendar entries will overlay the PostScript-type reminders, allowing you to create shaded or graphical backgrounds for particular days. Before executing your PostScript code, the origin of the PostScript coordinate system is positioned to the bottom left-hand corner of the "box" in the calendar representing ttooddaayy(()). This location is exactly in the middle of the intersection of the bottom and left black lines delineat- ing the box - you may have to account for the thickness of these lines when calculating positions. Several PostScript variables are available to the PostScript code you supply. All distance and size vari- ables are in PostScript units (1/72 inch.) The variables are: LineWidth The width of the black grid lines making up the 13 October 1993 51 REMIND(1) REMIND(1) calendar. Border The border between the center of the grid lines and the space used to print calendar entries. This border is normally blank space. BoxWidth and BoxHeight The width and height of the calendar box, from cen- ter-to-center of the black gridlines. InBoxHeight The height from the center of the bottom black gridline to the top of the regular calendar entry area. The space from here to the top of the box is used only to draw the day number. /DayFont, /EntryFont, /SmallFont, /TitleFont and /HeadFont The fonts used to draw the day numbers, the calen- dar entries, the small calendars, the calendar title (month, year) and the day-of-the-week head- ings, respectively. DaySize, EntrySize, TitleSize and HeadSize The sizes of the above fonts. (The size of the small calendar font is _n_o_t defined here.) For example, if you wanted to print the Hebrew date next to the regular day number in the calendar, use: REM PS Border BoxHeight Border sub DaySize sub moveto \ /DayFont findfont DaySize scalefont setfont \ ([hebday(today())] [hebmon(today())]) show Note how /DayFont and DaySize are used. Note that if you supply PostScript code, it is possible to produce invalid PostScript files. Always test your PostScript thoroughly with a PostScript viewer before sending it to the printer. You should not use any docu- ment structuring comments in your PostScript code. DDAAEEMMOONN MMOODDEE If you use the --zz command-line option, RReemmiinndd runs in the "daemon" mode. In this mode, no "normal" reminders are issued. Instead, only timed reminders are collected and queued, and are then issued whenever they reach their trigger time. In addition, RReemmiinndd wakes up every few minutes to check the modification date on the reminder script (the filename supplied on the command line.) If RReemmiinndd detects that the script has changed, it re-executes itself in daemon mode, and interprets the changed script. 13 October 1993 52 REMIND(1) REMIND(1) In daemon mode, RReemmiinndd also re-reads the remind script when it detects that the system date has changed. In daemon mode, RReemmiinndd acts as if the --ff option had been used, so to run in the daemon mode in the background, use: remind -z .reminders & If you use sshh or bbaasshh, you may have to use the "nohup" command to ensure that the daemon is not killed when you log out. SSOORRTTIINNGG RREEMMIINNDDEERRSS The --gg option causes RReemmiinndd to sort reminders by trigger date, time and priority before issuing them. Note that reminders are still calculated in the order encountered in the script. However, rather than being issued immedi- ately, they are saved in an internal buffer. When RReemmiinndd has finished processing the script, it issues the saved reminders in sorted order. The --gg option can be followed by up to three characters, which must be "a" or "d". The first character specifies the sort order by trigger date (ascending or descending), the second specifies the sort order by trigger time and the third specifies the sort order by priority. The default is to sort all fields in ascending order. In ascending order, reminders are issued with the most imminent first. Descending order is the reverse. Reminders are always sorted by trigger date, and reminders with the same trigger date are then sorted by trigger time. Non-timed reminders are always issued after timed reminders in this mode. If two reminders have the same date and time, then the priority is used to break ties. Reminders with the same date, time and priority are issued in the order they were encountered. You can define a user-defined function called SORTBANNER which takes one DDAATTEE-type argument. In sort mode, the following sequence happens: If RReemmiinndd notices that the next reminder to issue has a different trigger date from the previous one (or if it is the first one to be issued), then SORTBANNER is called with the trigger date as its argument. The result is coerced to a string, and passed through the substitution filter with the appropriate trigger date. The result is then displayed. Here's an example - consider the following fragment: # Switch off the normal banner BANNER % 13 October 1993 53 REMIND(1) REMIND(1) REM 11 March 1993 ++1 MSG Not so important REM 17 March 1993 ++7 MSG Way in the future REM 10 March 1993 MSG Important Reminder REM 11 March 1993 ++1 MSG Not so important - B FSET sortbanner(x) iif(x == today(), \ "***** THINGS TO DO TODAY *****", \ "----- Things to do %b -----") Running this with the --ggaaaa option on 10 March 1993 pro- duces the following output: ***** THINGS TO DO TODAY ***** Important Reminder ----- Things to do tomorrow ----- Not so important Not so important - B ----- Things to do in 7 days' time ----- Way in the future You can use the aarrggss(()) built-in function to determine whether or not SORTBANNER has been defined. (This could be used, for example, to provide a default definition for SORTBANNER in a system-wide file included at the end of the user's file.) Here's an example: # Create a default sortbanner function if it hasn't already # been defined if args("sortbanner") != 1 fset sortbanner(x) "--- Things to do %b ---" endif MMSSGGPPRREEFFIIXX(()) AANNDD MMSSGGSSUUFFFFIIXX(()) You can define two functions in your script called mmssggpprree-- ffiixx(()) and mmssggssuuffffiixx(()). They should each accept one argu- ment, a number from 0 to 9999. In normal mode, for MMSSGG- and MMSSFF-type reminders, the fol- lowing sequence occurs when RReemmiinndd triggers a reminder: o If mmssggpprreeffiixx(()) is defined, it is evaluated with the priority of the reminder as its argument. The result is printed. It is _n_o_t passed through the substitution filter. o The body of the reminder is printed. o If mmssggssuuffffiixx(()) is defined, it is evaluated with the 13 October 1993 54 REMIND(1) REMIND(1) priority of the reminder as its argument. The result is printed. It is _n_o_t passed through the substitution filter. Here's an example: The following definition causes prior- ity-0 reminders to be preceded by "URGENT", and prior- ity-6000 reminders to be preceded by "(not important)". fset msgprefix(x) iif(x==0, "URGENT: ", \ x==6000, "(not important) ", "") In Calendar Mode (with the --cc, --ss or --pp options), an analagous pair of functions named ccaallpprreeffiixx(()) and ccaallssuuff-- ffiixx(()) can be defined. They work with all reminders which produce an entry in the calendar (i.e., CCAALL- and possibly RRUUNN-type reminders as well as MMSSGG-type reminders.) NNOOTTEESS Normally, the body of a reminder is followed by a carriage return. Thus, the results of mmssggssuuffffiixx(()) will appear on the next line. If you don't want this, end the body of the reminder with a percentage sign, "%". If you want a space between your reminders, simply include a carriage return (cchhaarr((1133))) as part of the mmssggssuuffffiixx(()) return value. If RReemmiinndd has problems evaluating mmssggpprreeffiixx(()), mmssggssuuffffiixx(()) or ssoorrttbbaannnneerr(()), you will see a lot of error messages. For an example of this, define the following: fset msgprefix(x) x/0 FFOORREEIIGGNN LLAANNGGUUAAGGEE SSUUPPPPOORRTT Your version of RReemmiinndd may have been compiled to support a language other than English. This support may or may not be complete - for example, all error and usage messages may still be in English. However, at a minimum, foreign- language versions of RReemmiinndd will output names of months and weekdays in the foreign language. Also, the substitu- tion mechanism will substitute constructs suitable for the foreign language rather than for English. A foreign-language version of RReemmiinndd will accept either the English or foreign-language names of weekdays and months in a reminder script. However, for compatibility between versions of RReemmiinndd, you should use only the English names in your scripts. TTHHEE HHEEBBRREEWW CCAALLEENNDDAARR RReemmiinndd has support for the Hebrew calendar, which is a luni-solar calendar. This allows you to create reminders for Jewish holidays, jahrzeits (anniversaries of deaths) 13 October 1993 55 REMIND(1) REMIND(1) and smachot (joyous occasions.) TTHHEE HHEEBBRREEWW YYEEAARR The Hebrew year has 12 months, alternately 30 and 29 days long. The months are: Tishrey, Heshvan, Kislev, Tevet, Shvat, Adar, Nisan, Iyar, Sivan, Tamuz, Av and Elul. In Biblical times, the year started in Nisan, but Rosh Hashana (Jewish New Year) is now celebrated on the 1st and 2nd of Tishrey. In a cycle of 19 years, there are 7 leap years, being years 3, 6, 8, 11, 14, 17 and 19 of the cycle. In a leap year, an extra month of 30 days is added before Adar. The two Adars are called Adar A and Adar B. For certain religious reasons, the year cannot start on a Sunday, Wednesday or Friday. To adjust for this, a day is taken off Kislev or added to Heshvan. Thus, a regular year can have from 353 to 355 days, and a leap year from 383 to 385. When Kislev or Heshvan is short, it is called "chaser", or lacking. When it is long, it is called "shalem", or full. The Jewish date changes at sunset. However, RReemmiinndd will change the date at midnight, not sunset. So in the period between sunset and midnight, Remind will be a day earlier than the true Jewish date. This should not be much of a problem in practice. The computations for the Jewish calendar were based on the program "hdate" written by Amos Shapir of the Hebrew Uni- versity of Jerusalem, Israel. He also supplied the pre- ceding explanation of the calendar. HHEEBBRREEWW DDAATTEE FFUUNNCCTTIIOONNSS hheebbddaayy((dd__ddaattee)) Returns the day of the Hebrew month corresponding to the _d_a_t_e parameter. For example, 12 April 1993 corresponds to 21 Nisan 5753. Thus, heb- day('1993/04/12') returns 21. hheebbmmoonn((dd__ddaattee)) Returns the name of the Hebrew month corresponding to _d_a_t_e. For example, hebmon('1993/04/12') returns "Nisan". hheebbyyeeaarr((dd__ddaattee)) Returns the Hebrew year corresponding to _d_a_t_e. For example, hebyear('1993/04/12') returns 5753. 13 October 1993 56 REMIND(1) REMIND(1) hheebbddaattee((ii__ddaayy,, ss__hheebbmmoonn [[,,iidd__yyrrssttaarrtt [[,,ii__jjaahhrr [[,,ii__aaffllaagg]]]]]])) The hheebbddaattee(()) function is the most complex of the Hebrew support functions. It can take from 2 to 5 arguments. It returns a DDAATTEE corresponding to the Hebrew date. The _d_a_y parameter can range from 1 to 30, and spec- ifies the day of the Hebrew month. The _h_e_b_m_o_n parameter is a string which must name one of the Hebrew months specified above. Note that the month must be spelled out in full, and use the English transliteration shown previously. You can also specify "Adar A" and "Adar B." Month names are not case-sensitive. The _y_r_s_t_a_r_t parameter can either be a DDAATTEE or an IINNTT. If it is a DDAATTEE, then the hheebbddaattee(()) scans for the first Hebrew date on or after that date. For example: hebdate(15, "Nisan", '1990/01/01') returns 1990/03/30, because that is the first occurrence of 15 Nisan on or after 1 January 1990. If _y_r_s_t_a_r_t is an IINNTT, it is interpreted as a Hebrew year. Thus: hebdate(22, "Kislev", 5756) returns 1995/12/15, because that date corresponds to 22 Kislev, 5756. Note that none of the Hebrew date functions will work with dates outside RReemmiinndd''ss normal range for dates. If _y_r_s_t_a_r_t is not supplied, it defaults to ttooddaayy(()). The _j_a_h_r modifies the behaviour of hheebbddaattee(()) as follows: If _j_a_h_r is 0 (the default), then hheebbddaattee(()) keeps scanning until it finds a date which exactly satis- fies the other parameters. For example: hebdate(30, "Adar A", 1993/01/01) returns 1995/03/02, corresponding to 30 Adar A, 5755, because that is the next occurrence of 30 Adar A after 1 January, 1993. This behaviour is appropriate for Purim Katan, which only appears in leap years. If _j_a_h_r is 1, then the date is modified as follows: 13 October 1993 57 REMIND(1) REMIND(1) o 30 Heshvan is converted to 1 Kislev in years when Heshvan is chaser o 30 Kislev is converted to 1 Tevet in years when Kislev is chaser o 30 Adar A is converted to 1 Nisan in non- leapyears o Other dates in Adar A are moved to the cor- responding day in Adar in non-leapyears This behaviour is appropriate for smachot (joyous occasions) and for some jahrzeits - see "JAHRZEITS." if _j_a_h_r is 2, then the date is modified as follows: o 30 Kislev and 30 Heshvan are converted to 29 Kislev and 29 Heshvan, respectively, if the month is chaser o 30 Adar A is converted to 30 Shvat in non- leapyears o Other dates in Adar A are moved to the cor- responding day in Adar in non-leapyears if _j_a_h_r is not 0, 1, or 2, it is interpreted as a Hebrew year, and the behaviour is calculated as described in the next section, "JAHRZEITS." The _a_f_l_a_g parameter modifies the behaviour of the function for dates in Adar during leap years. The _a_f_l_a_g is _o_n_l_y used if _y_r_s_t_a_r_t is a DDAATTEE type (or is omitted, defaulting to ttooddaayy(()).) The _a_f_l_a_g only affects date calculations if _h_e_b_m_o_n is specified as "Adar". In leap years, the follow- ing algorithm is followed: o If _a_f_l_a_g is 0, then the date is triggered in Adar B. This is the default. o If _a_f_l_a_g is 1, then the date is triggered in Adar A. This may be appropriate for jahrzeits in the Ashkenazi tradition; con- sult a rabbi. o If _a_f_l_a_g is 2, then the date is triggered in both Adar A and Adar B of a leap year. Some Ashkenazim perform jahrzeit in both Adar A and Adar B. 13 October 1993 58 REMIND(1) REMIND(1) JJAAHHRRZZEEIITTSS A jahrzeit is a yearly commemoration of someone's death. It normally takes place on the anniversary of the death, but may be delayed if burial is delayed - consult a rabbi. In addition, because some months change length, it is not obvious which day the anniversary of a death is. The fol- lowing rules are used: o If the death occurred on 30 Heshvan, and Heshvan in the year after the death is chaser, then the jahrzeit is observed on 29 Heshvan in years when Heshvan is chaser. Otherwise, the yahrzeit is observed on 1 Kislev when Heshvan is chaser. o If the death occurred on 30 Kislev, and Kislev in the year after the death is chaser, then the jahrzeit is observed on 29 Kislev in years when Kislev is chaser. Otherwise, the yahrzeit is observed on 1 Tevet when Kislev is chaser. o If the death occurred on 1-29 Adar A, it is observed on 1-29 Adar in non-leapyears. o If the death occurred on 30 Adar A, it is observed on 30 Shvat in a non-leapyear. Specifying a Hebrew year for the _j_a_h_r parameter causes the correct behaviour to be selected for a death in that year. You may also have to specify _a_f_l_a_g, depending on your tra- dition. The jahrzeit information was supplied by Frank Yellin, who quoted "The Comprehensive Hebrew Calendar" by Arthur Spier, and "Calendrical Calculations" by E. M. Reingold and Nachum Dershowitz. MMIISSCCEELLLLAANNEEOOUUSS CCOOMMMMAANNDD AABBBBRREEVVIIAATTIIOONNSS The following tokens can be abbreviated: o RREEMM can be omitted - it is implied if no other valid command is present. o CCLLEEAARR--OOMMIITT--CCOONNTTEEXXTT --> CCLLEEAARR o PPUUSSHH--OOMMIITT--CCOONNTTEEXXTT --> PPUUSSHH o PPOOPP--OOMMIITT--CCOONNTTEEXXTT --> PPOOPP o DDUUMMPPVVAARRSS --> DDUUMMPP 13 October 1993 59 REMIND(1) REMIND(1) o BBAANNNNEERR --> BBAANN o IINNCCLLUUDDEE --> IINNCC o SSCCAANNFFRROOMM --> SSCCAANN NNIIFFTTYY EEXXAAMMPPLLEESS This section is a sampling of what you can do with RReemmiinndd. REM 5 Feb 1991 AT 14:00 +45 *30 \ RUN mail -s "Meeting at %2" $LOGNAME </dev/null & On 5 February, 1991, this reminder will mail you reminders of a 2:00pm meeting at 1:15, 1:45 and 2:00. The subject of the mail message will be "Meeting at 2:00pm" and the body of the message will be blank. REM AT 17:00 RUN echo "5:00pm - GO HOME!" | xless -g +0+0 & This reminder will pop up an xless window at 5:00pm every day. The xless window will contain the line "5:00pm - GO HOME!" REM AT 23:59 RUN (sleep 120; remind -a [filename()]) & This reminder will run at one minute to midnight. It will cause a new RReemmiinndd process to start at one minute past midnight. This allows you to have a continuous reminder service so you can work through the night and still get timed reminders for early in the morning. Note that this trick is no longer necessary, providing you run RReemmiinndd in daemon mode. remind -c12 /dev/null Jan 1993 This invocation of RReemmiinndd will cause it to print a calen- dar for 1993, with all entries left blank. REM CAL [trigdate()-date(year(trigdate()), 1, 1)+1] This example puts an entry in each box of a calendar show- ing the number (1-365 or 366) of the day of the year. REM Tue 2 Nov SATISFY (year(trigdate())%4) == 0 IF trigvalid() REM [trigger(trigdate())] ++5 MSG \ U.S. Presidential Election!! ENDIF This example warns you 5 days ahead of each American pres- idential election. The first RREEMM command calculates the first Tuesday after the first Monday in November. (This is equivalent to the first Tuesday on or after 2 13 October 1993 60 REMIND(1) REMIND(1) November.) The SSAATTIISSFFYY clause ensures that the trigger date is issued only in election years, which are multiples of 4. The second RREEMM command actually issues the reminder. DDEETTAAIILLSS AABBOOUUTT TTRRIIGGGGEERR CCOOMMPPUUTTAATTIIOONN Here is a _c_o_n_c_e_p_t_u_a_l description of how triggers are cal- culated. Note that RReemmiinndd actually uses a much more effi- cient procedure, but the results are the same as if the conceptual procedure had been followed. RReemmiinndd starts from the current date (that is, the value of ttooddaayy(())) and scans forward, examining each day one at a time until it finds a date which satisfies the trigger, or can prove that no such dates (on or later than ttooddaayy(())) exist. If RReemmiinndd is executing a SSAATTIISSFFYY-type reminder, it evalu- ates the expression with ttrriiggddaattee(()) set to the date found above. If the expression evaluates to zero or the null string, RReemmiinndd continues the scanning procedure described above, starting with the day after the trigger found above. The SSCCAANNFFRROOMM clause (having a syntax similar to UUNNTTIILL) can modify the search strategy used. In this case, RReemmiinndd begins the scanning procedure at _s_c_a_n___d_a_t_e, which is the date specified in the SSCCAANNFFRROOMM clause. For example: REM Mon 1 SCANFROM 17 Jan 1992 MSG Foo The example above will always have a trigger date of Mon- day, 3 February 1992. That is because RReemmiinndd starts scan- ning from 17 January 1992, and stops scanning as soon as it hits a date which satisfies "Mon 1." The main use of SSCCAANNFFRROOMM is in situations where you want to calculate the positions of floating holidays. Consider the Labour Day example shown much earlier. Labour Day is the first Monday in September. It can move over a range of 7 days. Consider the following sequence: REM Mon 1 Sept SCANFROM [trigger(today()-7)] SATISFY 1 OMIT [trigger(trigdate())] REM Mon AFTER MSG Hello The SSCCAANNFFRROOMM clause makes sure that RReemmiinndd begins scanning from 7 days before the current date. This ensures that Labour Day for the current year will continue to be trig- gered until 7 days after it has occurred. This allows you to safely use the AFTER keyword as shown. 13 October 1993 61 REMIND(1) REMIND(1) In general, use SSCCAANNFFRROOMM as shown for safe movable OOMMIITTss. The amount you should scan back by (7 days in the example above) depends on the number of possible consecutive OOMMIITT-- tteedd days which may occur, and on the range of the movable holiday. Generally, a value of 7 is safe. Note that if you use one RREEMM command to calculate a trig- ger date, perform date calculations (addition or subtrac- tion, for example) and then use the modified date in a subsequent RREEMM command, the results _m_a_y _n_o_t _b_e _w_h_a_t _y_o_u _i_n_t_e_n_d_e_d_. This is because you have circumvented the nor- mal scanning mechanism. You should try to write RREEMM com- mands which compute trigger dates that can be used unmodi- fied in subsequent RREEMM commands. The file "defs.rem" which comes with the RReemmiinndd distribution contains exam- ples. DDEETTAAIILLSS AABBOOUUTT TTRRIIGGVVAALLIIDD(()) The ttrriiggvvaalliidd(()) function returns 1 if RReemmiinndd could find a trigger date for the previous RREEMM or IIFFTTRRIIGG command. More specifically, it returns 1 if RReemmiinndd finds a date _n_o_t _b_e_f_o_r_e _t_h_e _s_t_a_r_t_i_n_g _d_a_t_e _o_f _t_h_e _s_c_a_n_n_i_n_g which satisfies the trigger. In addition, there is one special case in which ttrriiggvvaalliidd(()) returns 1 and ttrriiggddaattee(()) returns a mean- ingful result: If the RREEMM or IIFFTTRRIIGG command did not contain an UUNNTTIILL clause, and contained all of the _d_a_y, _m_o_n_t_h and _y_e_a_r com- ponents, then RReemmiinndd will correctly compute a trigger date, even if it happens to be before the start of scan- ning. Note that this behaviour is not true for versions of RReemmiinndd prior to 03.00.01. AAUUTTHHOORR David F. Skoll wrote RReemmiinndd. The moon code was copied largely unmodified from "moontool" by John Walker. The Hebrew calendar support was taken from "hdate" by Amos Shapir. The authors of the language files are listed in the header file "lang.h" which comes with RReemmiinndd. OS/2 support was provided initially by Darrel Hankerson; more complete OS/2 support was done by Russ Herman. BBUUGGSS There's no good reason why read-only system variables are not implemented as functions, or why functions like vveerr-- ssiioonn(()), etc. are not implemented as read-only system variables. Hebrew dates change at midnight, not sunset. The UTC functions are not reliable under MS-DOS. The MS-DOS version of RReemmiinndd does not support queuing or 13 October 1993 62 REMIND(1) REMIND(1) timed activation of reminders. RReemmiinndd has some built-in limits on total line length, sub- stitution buffer length, number of global OOMMIITTs, etc. SSEEEE AALLSSOO rem, elm, kall, rem2ps 13 October 1993 63