REMIND(1) REMIND(1)
NAME
remind - a sophisticated reminder service
SYNOPSIS
remind [options] filename [date] [*rep] [time(1,2,n)]
DESCRIPTION
Remind reads the supplied filename and executes the commands found in(1,8)
it. The commands are used to issue reminders and alarms. Each
reminder or alarm(1,2) can consist of a message sent to standard output, or
a program to be executed.
If filename is specified as a single dash '-', then Remind takes its
input from standard input. This also implicitly enables the -o option,
described below.
OPTIONS
Remind has a slew of options. If you're new to the program, ignore
them for now and skip to the section "Reminder Files".
-n The -n option causes Remind to print the next occurrence of each
reminder in(1,8) a simple calendar format. You can sort(1,3) this by date
by piping the output through sort(1,3)(1).
-r The -r option disables RUN directives and the shell() function
-cn The -c option causes Remind 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.
-wcol[,pad[,spc]]]
The -w option specifies the output width, padding and spacing of
the formatted calendar output. Col specifies the number of col-
umns in(1,8) the output device, and defaults to 80. Pad specifies
how many lines to use to "pad" empty calendar boxes. This
defaults to 5. If you have many reminders on certain days,
which make your calendar too large to fit on a page, you can try
reducing pad to make the empty boxes smaller. Spc specifies how
many blank lines to leave between the day number and the first
reminder entry. It defaults to 1.
Any of col, pad or spc can be omitted, providing you provide the
correct number of commas. Don't use any spaces in(1,8) the option.
-sn The -s option is very similar to the -c option, except that the
output calendar is not formatted. It is listed in(1,8) a "simple
format" which can be used as input for more sophisticated calen-
dar-drawing programs. If n starts with "+", then it is inter-
preted as a number of weeks.
-pn The -p option is very similar to the -s option, except that the
output contains additional information for use by the Rem2PS
program, which creates a PostScript calendar. For this option,
n cannot start with "+"; it must specify a number of months.
The format of the -p output is described in(1,8) the rem2ps(1) man(1,5,7)
page.
-m The -m option causes the -c or -p options to produce a calendar
whose first column is Monday rather than Sunday. (This conforms
to the international standard.)
-v The -v option makes the output of Remind slightly more verbose.
Currently, this causes Remind to echo(1,3x,1 builtins) a bad line in(1,8) case of an
error(8,n), and to print a security message if(3,n) a script tests the
$RunOff system variable.
-o The -o option causes Remind to ignore all ONCE directives.
-t The -t option causes Remind to trigger all non-expired
reminders, regardless of the delta supplied for each reminder.
-h The -h option ("hush...") suppresses certain warning and infor-
mation messages. In particular, if(3,n) no reminders are triggered,
this mode produces no output.
-a (UNIX and OS/2 only)
The -a option causes Remind not to immediately trigger timed
reminders which would also be queued. It also causes Remind not
to place timed reminders in(1,8) a calendar.
-q (UNIX and OS/2 only)
The -q option causes Remind not to queue(1,3) timed reminders for
later execution.
-f (UNIX and OS/2 only)
The -f option causes Remind to remain in(1,8) the foreground when
processing queued reminders, rather than forking off a back-
ground process to handle them.
-e The -e option diverts error(8,n) messages (normally sent to the stan-
dard error(8,n) stream) to the standard output stream.
-dchars
The -d option enables certain debugging modes. The chars spec-
ify which modes to enable:
e Echo all input lines
x Trace all expression evaluation
t Display all trigger date computation
v Dump the variable table after execution of the reminder script
l Echo lines when displaying error(8,n) messages
-g[a|d[a|d[a|d]]]
Normally, reminders are issued in(1,8) the order in(1,8) which they are
encountered in(1,8) the reminder script. The -g option cause Remind
to sort(1,3) reminders by date and time(1,2,n) prior to issuing them. The
optional a and d characters specify the sort(1,3) order (ascending or
descending) for the date, time(1,2,n) and priority fields. See the
section "Sorting Reminders" for more information.
-b[n] Set the time(1,2,n) format for the calendar and simple-calendar out-
puts. N can range from 0 to 2, with the default 0. A value of
0 causes times to be inserted in(1,8) 12-hour (am/pm) format. 1
causes times to be inserted in(1,8) 24-hour format, and 2 inhibits
the automatic insertion of times in(1,8) the calendar output.
-x[n] Sets the iteration limit for the SATISFY clause of a REM com-
mand. Defaults to 150.
-kcmd Instead of simply printing MSG-type reminders, this causes them
to be passed to the specific cmd. You must use '%s' where you
want the body to appear, and may need to enclose this option in(1,8)
quotes. Note that all shell characters in(1,8) the body of the
reminder are escaped with a backslash, and the entire body of
the reminder is passed as a single argument. Note that this
option overrides the -r option and the RUN OFF command.
As an example, suppose you have an X Window program called xmes-
sage, which pops up a window and displays its invocation argu-
ments. You could use:
remind '-kxmessage %s &' ...
to have all of your MSG-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 cmd is passed as an argument to sprintf(). If you use for-
matting directives other than %s, or use more than one %s direc-
tive, there's a good chance that you'll crash Remind. Finally,
because all shell and whitespace characters are escaped, the
program you execute with the -k option must be prepared to han-
dle the entire message as a single argument.
-z[n] (UNIX and OS/2 only)
Runs Remind in(1,8) the daemon mode. If n is supplied, it specifies
how often (in(1,8) minutes) Remind should wake up to check if(3,n) the
reminder script has been changed. N defaults to 5, and can
range from 5 to 60. Note that the use of the -z option also
enables the -f option.
If you supply the option -z0, Remind runs in(1,8) a special mode
called server mode. This is documented in(1,8) the tkremind man(1,5,7)
page; see tkremind(1).
-uname (UNIX version(1,3,5) only)
Runs Remind with the uid and gid of the user specified by name.
The option changes the uid and gid as described, and sets the
environment variables HOME, SHELL and USER to the home direc-
tory, shell, and user name, respectively, of the specified user.
LOGNAME is also set(7,n,1 builtins) to the specified user name. This option is
meant for use in(1,8) shell scripts which mail(1,8) reminders to all
users. Note that as of Remind 3.0.17, using -u implies -r --
the RUN directive and shell() functions are disabled.
Non-root users(1,5) can also use the -u option. However, in(1,8) this
case, it only changes the environment variables as described
above. It does not change the effective uid or gid.
-ivar=expr(1,3,n)
Sets the value of the specified var to expr(1,3,n), and preserves var.
Expr can be any valid Remind expression. See the section "Ini-
tializing Variables on the Command Line" for more details.
If you supply a date on the command line, it must consist of day month
year, where day is the day of the month, month is at least the first
three letters of the English name of the month, and year is a year (all
4 digits) from 1990 to about 2075. You can leave out the day, which
then defaults to 1.
If you do supply a date on the command line, then Remind 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 triggered in(1,8) the future. Similarly, you can supply a
time(1,2,n) (in(1,8) 24-hour format -- for example, 17:15) to set(7,n,1 builtins) Remind's notion
of "now" to a particular time. Supplying a time(1,2,n) on the command line
also implicitly enables the -q option and disables the -z option.
In addition, you can supply a repeat parameter, which has the form
*num. This causes Remind to be run num times, with the date increment-
ing on each iteration. You may have to enclose the parameter in(1,8) quotes
to avoid shell expansion. See the subsection "Repeated Execution" in(1,8)
the section "Calendar Mode" for more information.
REMINDER FILES
Remind uses scripts to control its operation. You can use any text
editor capable of creating plain ASCII files to create a Remind script.
The commands 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(1,n) consists of commands, with one command per line. Sev-
eral lines can be continued using the backslash character, as in(1,8) the
above example. In this case, all of the concatenated lines are treated
as a single line by Remind. Note that if(3,n) an error(8,n) occurs, Remind
reports the line number of the last line of a continued line.
Remind ignores blank lines, and lines beginning with the '#' or ';'
characters. You can use the semicolon as a comment character if(3,n) you
wish to pass a Remind script through the C pre-processor, which inter-
prets the '#' character as the start of a pre-processing directive.
Remind is not case sensitive; you can generally use any mixture of
upper- or lower-case for commands, parameters, invocation options, etc.
THE REM COMMAND
The most powerful command in(1,8) a Remind script is the REM command. This
command is responsible for issuing reminders. Its syntax is:
REM [ONCE] [date_spec] [back] [delta] [repeat] [PRIORITY prio]
[SKIP | BEFORE | AFTER] [OMIT omit_list] [AT time(1,2,n) [tdelta] [tre-
peat]] [SCHED sched_function] [WARN warn_function] [UNTIL
expiry_date] [SCANFROM scan_date] [DURATION duration] [TAG tag]
<MSG | MSF | RUN | CAL | SATISFY | SPECIAL special | PS |
PSFILE> body
The parts of the REM command can be specified in(1,8) any order, except that
the body must come immediately after the MSG, RUN, CAL, PS, PSFILE or
SATISFY keyword.
The REM token is optional, providing that the remainder of the command
cannot be mistaken for another Remind command such as OMIT or RUN. The
portion of the REM command before the MSG, MSF RUN, CAL or SATISFY
clause is called a trigger.
MSG, MSF, RUN, CAL, SPECIAL, PS and PSFILE
These keywords denote the type of the reminder. (SATISFY is more com-
plicated and will be explained later.) A MSG-type reminder normally
prints a message to the standard output, after passing the body through
a special substitution filter(1,3x,3x curs_util), described in(1,8) the section "The Substitu-
tion Filter." However, if(3,n) you have used the -k command-line option,
then MSG-type reminders are passed to the appropriate program. Note
that the options -c, -s, -p and -n disable the -k option.
Note that you can omit the reminder type, in(1,8) which case it defaults to
MSG. So you can write:
6 January David's Birthday
although this is not recommended.
The MSF keyword is almost the same as the MSG keyword, except that the
reminder is formatted to fit into a paragraph-like format. Three sys-
tem variables control the formatting of MSF-type reminders - they are
$FirstIndent, $SubsIndent and $FormWidth. They are discussed in(1,8) the
section "System Variables." The MSF 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 $EndSent and $EndSentIg. Note that if(3,n) the body of the
reminder includes newline characters (placed there with the %_
sequence), then the newlines are treated as the beginnings of new para-
graphs, and the $FirstIndent indentation is used for the next line.
You can use two consecutive newlines to have spaced paragraphs emitted
from a single reminder body.
A RUN-type reminder also passes the body through the substitution fil-
ter(1,3x,3x curs_util), but then executes the result as a system command. A CAL-type
reminder is used only to place entries in(1,8) the calendar produced when
Remind is run with the -c, -s or -p options.
A PS or PSFILE-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(1,8) 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 PS and PSFILE reminders are ignored unless
Remind is run with the -p option. See the section "More about Post-
Script" for more details.
A SPECIAL-type reminder is used to pass "out-of-band" information from
Remind to a calendar-producing back-end. It should be followed by a
word indicating the type of special data being passed. The type of a
special reminder depends on the back-end. For the Rem2PS back-end,
SPECIAL PostScript is equivalent to a PS-type reminder, and SPECIAL
PSFile is equivalent to a PSFILE-type reminder. The body of a SPECIAL
reminder is obviously dependent upon the back-end.
DATE SPECIFICATIONS
A date_spec consists of zero to four parts. These parts are day (day
of month), month (month name), year and weekday. Month and weekday 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 date_spec:
day: 1, 22, 31, 14, 3
month: JANUARY, feb, March, ApR, may, Aug
year: 1990, 1993, 2030, 95 (interpreted as 1995). The year can range
from 1990 to 2075.
weekday:
Monday, tue, Wed, THU, Friday, saturday, sundAy
Note that there can be several weekday components separated by spaces
in(1,8) a date_spec.
INTERPRETATION OF DATE SPECIFICATIONS
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 day present. The reminder is triggered on the specified day of
each month. The trigger date for a particular 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 month present. The reminder is triggered every day of the
specified month. Example:
REM Feb MSG Every day in(1,8) February
4. day and month present. Examples:
REM 6 Jan MSG Every 6th of January
REM Feb 29 MSG Every 29th of February
5. Only year present. Example:
REM 1991 MSG Every day in(1,8) 1991
6. year and day present. Examples:
REM 1 1990 MSG 1st of every month in(1,8) 1990
REM 1992 23 MSG 23rd of every month in(1,8) 1992
7. year and month present. Examples:
REM Feb 1991 MSG Every day in(1,8) Feb 1991
REM 1992 September MSG Every day in(1,8) Sept 1992
8. year, month and day present. Examples:
REM 8 Jan 1991 MSG 8th January 1991.
REM 1992 March 9 MSG 9th March 1992.
9. weekday only. Examples:
REM Sat MSG Every Saturday
REM Mon Tue Wed Thu Fri MSG Every working day
REM Monday Wednesday MSG Every Monday and Wednesday
10. weekday and day 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. weekday and month present. Examples:
REM Mon March MSG Every Monday in(1,8) March
REM Mon Tue Wed Thu Fri Feb MSG Every working day in(1,8) February
12. weekday, month and day present. Examples:
REM Mon 1 March MSG First Monday in(1,8) March
REM Sat Sun 15 July MSG First Sat or Sun on or after 15 July
13. weekday and year present. Example:
REM Sat Sun 1991 MSG Every Saturday and Sunday in(1,8) 1991
14. weekday, day and year present. Examples:
REM Mon 15 1990 MSG 1st Mon after 15th of every month in(1,8) 1990
REM Mon Tue Wed Thu Fri 1 1990 \
MSG 1st working day of every month in(1,8) 1990
15. weekday, month and year present. Example:
REM Mon Wed 1991 Feb MSG Every Mon and Wed in(1,8) Feb 1991.
16. weekday, day, month and year 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 weekday and day are specified, Remind chooses the
first date on or after the specified day which also satisfies the week-
day constraint. It does this by picking the first date on or after the
specified day which is listed in(1,8) the list of weekdays. 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 weekday constraints.
BACKWARD SCANNING
Sometimes, it is necessary to specify a date as being a set(7,n,1 builtins) amount of
time(1,2,n) before another date. For example, the last Monday in(1,8) a given
month is computed as the first Monday in(1,8) the next month, minus 7 days.
The back specification in(1,8) the reminder is used in(1,8) this case:
REM Mon 1 -7 MSG Last Monday of every month.
A back is specified with one or two dashes followed by an integer.
This causes Remind to move(3x,7,3x curs_move) "backwards" from what would normally be the
trigger date. The difference between --7 and -7 will be explained when
the OMIT keyword is described.
ADVANCE WARNING
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(1,8) advance. The delta portion of the REM 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 OMIT keyword. Remind 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(1,8) advance.
The above example would be triggered every 6th of January, as well as
the 1st through 5th of January.
PERIODIC REMINDERS
We have already seen some built-in mechanisms for certain types of
periodic reminders. For example, an event occurring 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 repeat component of the REM command
fills this need. To use it, you must completely specify a date (year,
month and day, and optionally weekday.) The repeat component is an
asterisk followed by a number specifying the repetition period in(1,8) 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 delta and back with repeat. Note, however,
that the back is used only to compute the initial trigger date; there-
after, the reminder repeats with the specified period. Similarly, if(3,n)
you specify a weekday, it is used only to calculate the initial date,
and does not affect the repetition period.
SCANFROM
The SCANFROM keyword is for advanced Remind programmers only, and will
be explained in(1,8) the section "Details about Trigger Computation" near
the end of this manual. Note that SCANFROM is available only in(1,8) ver-
sions of Remind from 03.00.04 up.
PRIORITY
The PRIORITY keyword must be followed by a number from 0 to 9999. It
is used in(1,8) calendar mode and when sorting reminders. If two reminders
have the same trigger date and time(1,2,n), then they are sorted by priority.
If the PRIORITY keyword is not supplied, a default priority of 5000 is
used. (This default can be changed by adjusting the system variable
$DefaultPrio. See the section "System Variables" for more informa-
tion.)
EXPIRY DATES
Some reminders should be issued periodically for a certain time(1,2,n), 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 repeat of *1 is necessary; without it, the reminder would
be issued only on 30 November (and the two days preceding.)
THE ONCE KEYWORD
Sometimes, it is necessary to ensure that reminders are run only once
on a given day. For example, if(3,n) you have a reminder which makes a
backup of your files every Friday:
REM Fri RUN do_backup
(Here, do_backup is assumed to be a program or shell script which does
the work.) If you run Remind from your .login script, for example, and
log in(1,8) several times per day, the do_backup program will be run each
time(1,2,n) you log in. If, however, you use the ONCE keyword in(1,8) the
reminder, the Remind checks the last access(2,5) date of the reminder
script. If it is the same as the current date, Remind assumes that it
has already been run, and will not issue reminders containing the ONCE
keyword.
Note that if(3,n) you view or edit your reminder script, the last access(2,5)
date will be updated, and the ONCE keyword will not operate properly.
If you start Remind with the -o option, then the ONCE keyword will be
ignored.
LOCALLY OMITTING WEEKDAYS
The OMIT portion of the REM command is used to "omit" certain days when
counting the delta or back. It is specified using the keyword OMIT
followed by a list of weekdays. 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(3,n) 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 delta of +1 does not count Satur-
day or Sunday when it counts backwards from the trigger date to deter-
mine how much advance warning to give.
Contrast this with the use of "++1" in(1,8) 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(1,8) the above example, the back of -1 normally causes the trigger
date to be the last day of the month. However, because of the OMIT
clause, if(3,n) 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(3,n) we had used "--1", the reminder would be triggered on
the last day of the month, regardless of the OMIT.
TIMED REMINDERS
Timed reminders are those which have an AT keyword followed by a time(1,2,n)
and optional tdelta and trepeat. The time(1,2,n) must be specified in(1,8) 24-hour
format, with 0:00 representing midnight, 12:00 representing noon, and
23:59 representing 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.
Remind treats timed reminders specially. If the trigger date for a
timed reminder is the same as the current system date, the reminder is
queued for later activation. When Remind has finished processing the
reminder file(1,n), it puts(3,n) itself in(1,8) the background, and activates timed
reminders when the system time(1,2,n) reached the specified time. (Unfortu-
nately, the MS-DOS version(1,3,5) does not have this ability -- most of this
section applies only to the UNIX and OS/2 versions.)
If the trigger date is not the same as the system date, the reminder is
not queued.
For example, the following reminder, triggered every working 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 tdelta and trepeat have the same form as a repeat and delta, but
are specified in(1,8) minutes. For example, this reminder will be triggered
at 12:00pm as well as 45 minutes 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(1,8) 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(1,2,n), even if(3,n) the tdelta is not a multi-
ple of the trepeat. So the above example is issued at 10:45am,
11:15am, 11:45am, and 12:00pm. Note that in(1,8) the time(1,2,n) specification,
there is no distinction between the "+" and "++" forms of tdelta.
Normally, Remind will issue timed reminders as it processes the
reminder script, as well as queuing them for later. If you do not want
Remind to issue the reminders when processing the script, but only to
queue(1,3) them for later, use the -a command-line option. If you do not
want reminders to be queued for later, use the -q command-line option.
Normally, Remind forks a background process to handle queued reminders.
If you want Remind to remain in(1,8) the foreground, use the -f command-line
option. This is useful, for example, in(1,8) .xinitrc scripts, where you
can use the command:
remind -fa myreminders &
This ensures that when you exit(3,n,1 builtins) X-Windows, the Remind process is
killed.
WARNING ABOUT TIMED REMINDERS
Note: If you use user-defined functions or variables (described later)
in(1,8) the bodies of timed reminders, then when the timed reminders are
activated, the variables and functions have the definitions which were
in(1,8) effect at the end of the reminder script. These definitions may not
necessarily be those which were in(1,8) effect at the time(1,2,n) the reminder was
queued.
THE SCHED AND WARN KEYWORDS
The SCHED keyword allows more precise control over the triggering of
timed reminders, and the WARN keyword allows precise control over the
advance triggering of all types of reminders. However, discussion must
be deferred until after expressions and user-defined functions are
explained. See the subsection "Precise Scheduling" further on.
TAG AND DURATION
The TAG keyword lets you "tag" certain reminders. This facility is
used by certain back-ends or systems built around Remind, such as TkRe-
mind. These back-ends have specific rules about tags; you should not
use the TAG keyword yourself, or your script will interact badly with
back-ends.
The TAG keyword is followed by a tag consisting of up to 32 characters.
The DURATION keyword makes sense only for timed reminders; it specifies
the duration of an event. Currently, this is not used, but it may be
used in(1,8) future by back-ends or scheduling systems built around Remind.
For example, if(3,n) you have a 90-minute meeting starting at 1:00pm, you
could use:
REM 5 March 1999 AT 13:00 DURATION 1:30 MSG Meeting
Note that duration is specified in(1,8) hours and minutes.
THE SUBSTITUTION FILTER
Before being processed, the body of a REM command is passed through a
substitution filter. The filter(1,3x,3x curs_util) 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.)
%a is replaced with "on weekday, day month, year"
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 Thurs-
day, 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."
%b is replaced with "in(1,8) diff day's time(1,2,n)" where diff is the actual
number of days between the current date and the trigger date.
(OMITs 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 Bob in(1,8) 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."
%c is replaced with "on weekday"
Example: REM 18 Oct 1990 +4 MSG Meeting with Bob %c.
On 16 October 1990, it would print "Meeting with Bob on Thurs-
day."
On 17 October 1990, it would print "Meeting with Bob tomorrow."
On 18 October 1990, it would print "Meeting with Bob today."
%d is replaced with "day", the day of the month.
%e is replaced with "on dd/mm/yyyy"
%f is replaced with "on mm/dd/yyyy"
%g is replaced with "on weekday, day month"
%h is replaced with "on dd/mm"
%i is replaced with "on mm/dd"
%j is replaced with "on weekday, month day-th, year" This form
appends the characters "st", "nd", "rd" or "th" to the day of
the month, as appropriate.
%k is replaced with "on weekday, month day-th"
%l is replaced with "on yyyy/mm/dd"
%m is replaced with "month", the name of the month.
%n is replaced with the number (1 to 12) of the month.
%o is replaced with " (today)" if(3,n) and only if(3,n) the current system
date is the same as the date being used by Remind as the current
date. Recall that you can specify a date for Remind to use on
the command line. This substitution is not generally useful in(1,8)
a REM command, but is useful in(1,8) a BANNER command. (See "The
BANNER Command.")
%p is replaced with "s" if(3,n) the diff between the 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!
%q is replaced with "'s" if(3,n) the diff between the trigger 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(1,8) %x day%q time(1,2,n)!
%r is replaced with the day of the month (01 to 31) padded with a
leading zero if(3,n) needed to pad to two digits.
%s is replaced with "st", "nd", "rd" or "th" depending on the day
of the month.
%t is replaced with the number of the month (01 to 12) padded to
two digits with a leading zero.
%u is replaced with "on weekday, day-th month, year" This is simi-
lar to %a except that "st", "nd", "rd" or "th" is added to the
day as appropriate.
%v is replaced with "on weekday, day-th month"
%w is replaced with "weekday", the name of the day of the week.
%x is replaced with the diff between the current date and the trig-
ger date. The diff is defined as the actual number of days
between these two dates; OMITs are not counted. (Strict date
subtraction is performed.)
%y is replaced with "year", the year of the trigger date.
%z is replaced with "yy", the last two digits of the year.
%_ (percent-underscore) is replaced with a newline. You can use
this to achieve multi-line reminders.
%1 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 -a option, timed
reminders will be triggered like normal reminders, and thus a
timed reminder which occurred earlier in(1,8) the day may be trig-
gered. This causes the need for the "...ago" forms.
%2 is replaced with "at hh:mmam" or "..pm" depending on the AT time(1,2,n)
of the reminder.
%3 is replaced with "at hh:mm" in(1,8) 24-hour format.
%4 is replaced with "mm" where mm is the number of minutes between
"now" and the time(1,2,n) specified by AT. If the AT time(1,2,n) is earlier
than the current time(1,2,n), then the result is negative.
%5 is replaced with "ma" where ma is the absolute value of the num-
ber produced by %4.
%6 is replaced with "ago" or "from now", depending on the relation-
ship between the AT time(1,2,n) and the current time.
%7 is replaced with the number of hours between the AT time(1,2,n) and the
current time. It is always non-negative.
%8 is replaced with the number of minutes between the AT time(1,2,n) and
the current time(1,2,n), after the hours (%7) have been subtracted out.
This is a number ranging from 0 to 59.
%9 is replaced with "s" if(3,n) the value produced by %8 is not 1.
%0 is replaced with "s" if(3,n) the value produced by %7 is not 1.
%! is replaced with "is" if(3,n) the current time(1,2,n) is before the AT time(1,2,n),
or "was" if(3,n) it is after.
%@ is similar to %2 but displays the current time.
%# is similar to %3 but displays the current time.
%" (percent-doublequote - ") is removed. This sequence is not used
by the substitution filter(1,3x,3x curs_util), but is used to tell Remind which
text to include in(1,8) a calendar entry when the -c, -s or -p option
is chosen. See "Calendar Mode"
Notes:
o Remind normally prints a blank line after each reminder; if(3,n) 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(3,n) the current date equals the trigger
date, or "tomorrow" if(3,n) the trigger date is one day after the
current date. Thus, they are not the same as substitutions
built up from the simpler %w, %y, etc. sequences.
o Any of the substitutions dealing with time(1,2,n) (0 through 9 and '!')
produce undefined results if(3,n) used in(1,8) a reminder which does not
have an AT keyword. Also, if(3,n) a reminder has a delta and may be
triggered on several days, the time(1,2,n) substitutions ignore the
date. Thus, the %1 substitution may report that a meeting is in(1,8)
15 minutes, for example, even though it may only be in(1,8) 2 days
time(1,2,n), because a delta has triggered the reminder. It is recom-
mended that you use the time(1,2,n) substitutions only in(1,8) timed
reminders with no delta which are designed to be queued for
timed activation.
o Capital letters can be used in(1,8) the substitution sequence, in(1,8)
which case the first character of the substituted string(3,n) is cap-
italized (if(3,n) it is normally a lower-case letter.)
o All other characters following a "%" sign are simply copied. In
particular, to get a "%" sign out, use "%%" in(1,8) the body. To
start the body of a reminder with a space, use "% ", since
Remind normally scans for the first non-space character after a
MSG, CAL or RUN token.
THE OMIT COMMAND
In addition to being a keyword in(1,8) the REM command, OMIT is a command in(1,8)
its own right. Its syntax is:
OMIT day month [year]
The OMIT command is used to "globally" omit certain days, which are
usually holidays. These globally-omitted days are skipped by the "-"
and "+" forms of back and delta. 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 OMIT command for each year. (Later, in(1,8) the description
of expressions and some of the more advanced features of Remind, you
will see how to automate this for some cases.)
For convenience, you can use a delta and MSG or RUN keyword in(1,8) the OMIT
command. The following sequences are exactly equivalent:
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!
THE BEFORE, AFTER AND SKIP KEYWORDS
Normally, days which are omitted, whether by a global OMIT command or
the local OMIT keyword in(1,8) a REM statement, only affect the counting of
the -back or the +delta. For example, 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 Novem-
ber 1992, which is a Wednesday. This is probably incorrect. There are
three options:
BEFORE This keyword moves the reminder to before any omitted days.
Thus, in(1,8) the above example, use of BEFORE would cause the meet-
ing reminder to be triggered on Tuesday, 10 November 1992.
AFTER This keyword moves the reminder to after any omitted days. In
the above example, the meeting reminder would be triggered on
Thursday, 12 November 1992.
SKIP This keyword causes the reminder to be skipped completely on any
omitted days. Thus, in(1,8) 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 BEFORE and AFTER keywords move(3x,7,3x curs_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(3,n) 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 1 specifies the
first day of the month. The local OMIT keyword causes the AFTER key-
word to move(3x,7,3x curs_move) the reminder forward past weekends. Finally, the AFTER
keyword will keep moving the reminder forward until it has passed any
holidays specified with global OMIT commands.
THE INCLUDE COMMAND
Remind allows you to include other files in(1,8) your reminder script, simi-
lar to the C preprocessor #include directive. For example, your system
administrator may maintain a file(1,n) of holidays or system-wide reminders.
You can include these in(1,8) 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.)
INCLUDE files can be nested up to a depth of 8.
If you specify a filename of "-" in(1,8) the INCLUDE command, Remind will
begin reading from standard input.
THE RUN COMMAND
If you include other files in(1,8) your reminder script, you may not always
entirely trust the contents of the other files. For example, they may
contain RUN-type reminders which could be used to access(2,5) your files or
perform undesired actions. The RUN command can restrict this: If you
include the command RUN OFF in(1,8) your top-level reminder script, any
reminder or expression which would normally execute a system command is
disabled. RUN ON will re-enable the execution of system commands.
Note that the RUN ON command can only be used in(1,8) your top-level
reminder script; it will not work in(1,8) any files accessed by the INCLUDE
command. This is to protect you from someone placing a RUN ON command
in(1,8) an included file. However, the RUN OFF command can be used at top
level or in(1,8) an included file.
If you run Remind with the -r command-line option, RUN-type reminders
and the shell() function will be disabled, regardless of any RUN com-
mands in(1,8) the reminder script. However, any command supplied with the
-k option will still be executed.
One use of the RUN command is to provide a secure interface between
Remind and the Elm mail(1,8) system. The Elm system can automatically scan
incoming mail(1,8) for reminder or calendar entries, and place them in(1,8) your
calendar file. To use this feature, you should set(7,n,1 builtins) the calendar file-
name option under Elm to be something like "~/.reminders.in", not your
main reminder file(1,n)! This is so that any RUN ON commands mailed to you
can never be activated.
Then, you can use the Elm scan message for calendar entries command to
place reminders prefaced by "->" into .reminders.in. In your main
.reminders file(1,n), include the following lines:
RUN OFF # Disable RUN
INCLUDE .reminders.in
RUN ON # Re-enable RUN
In addition, Remind on UNIX contains a few other security features. It
will not read(2,n,1 builtins) a file(1,n) which is group- or world-writable. It will not
run set-uid. If it reads a file(1,n) you don't own, it will disable RUN and
the shell() function. And if(3,n) it is run as root, it will only read(2,n,1 builtins)
files owned by root.
THE BANNER COMMAND
When Remind first issues a reminder, it prints a message like this:
Reminders for Friday, 30th October, 1992 (today):
(The banner is not printed if(3,n) any of the calendar-producing options is
used, or if(3,n) the -k option is used.)
The BANNER command lets you change the format. It should appear before
any REM commands. The format is:
BANNER format
The format is similar to the body of a REM command. It is passed
through the substitution filter(1,3x,3x curs_util), with an implicit trigger of the cur-
rent 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:
CONTROLLING THE OMIT CONTEXT
Sometimes, it is necessary to temporarily change the global OMITs which
are in(1,8) force for a few reminders. Three commands allow you to do this:
PUSH-OMIT-CONTEXT
This command saves the current global OMITs on an internal
stack.
CLEAR-OMIT-CONTEXT
This command clears all of the global OMITs, starting you off
with a "clean slate."
POP-OMIT-CONTEXT
This command restores the global OMITs which were saved by the
most recent PUSH-OMIT-CONTEXT.
For example, suppose you have a block of reminders which require a
clear(1,3x,3x clrtobot) OMIT context, and that they also introduce unwanted global OMITs
which could interfere with later reminders. You could use the follow-
ing fragment:
PUSH-OMIT-CONTEXT # Save the current context
CLEAR-OMIT-CONTEXT # Clean the slate
# Block of reminders goes here
POP-OMIT-CONTEXT # Restore the saved omit context
EXPRESSIONS
In certain contexts, to be described later, Remind will accept(2,8) expres-
sions for evaluation. Remind expressions resemble C expressions, but
operate on different types of objects.
DATA TYPES
Remind expressions understand four types of objects:
INT The INT data type consists of the integers representable in(1,8) one
machine word. The INT data type corresponds to the C "int"
type.
STRING The STRING data type consists of strings of characters. It is
somewhat comparable to a C character array, but more closely
resembles the string(3,n) type in(1,8) BASIC.
TIME The TIME data type consists of times of the day. The TIME data
type is internally stored as an integer representing the number
of minutes since midnight.
DATE The DATE data type consists of dates (later than 1 January
1990.) Internally, DATE objects are stored as the number of
days since 1 January 1990.
CONSTANTS
The following examples illustrate constants in(1,8) Remind expressions:
INT constants
12, 36, -10, 0, 1209
STRING constants
"Hello there", "This is a test", "\n\gosd\w", ""
Note that the empty string(3,n) is represented by "", and that back-
slashes in(1,8) a string(3,n) are not interpreted specially, as in(1,8) they
are in(1,8) C.
TIME constants
12:33, 0:01, 14:15, 16:42, 12.16, 13.00, 1.11
Note that TIME constants are written in(1,8) 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 one separator character. (The output separator character
is chosen at compile-time.)
DATE constants
DATE constants are expressed as 'yyyy/mm/dd' or 'yyyy-mm-dd',
and the single quotes must be supplied. This distinguishes date
constants from division or subtraction of integers. Examples:
1993/02/22', '1992-12-25', '1999/01/01'
Note that DATE constants are printed 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 Remind prior to 03.00.01 did not sup-
port date constants. In those versions, you must create dates
using the date() function. Also, versions prior to 03.00.02 did
not support the '-' date separator.
OPERATORS
Remind 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)
* / %
+ -
< <= > >=
== !=
&&
||
DESCRIPTION OF OPERATORS
! Logical negation. Can be applied to an INT type. If the oper-
and is non-zero, returns zero. Otherwise, returns 1.
- Unary minus. Can be applied to an INT. Returns the negative of
the operand.
* Multiplication. Returns the product of two INTs.
/ Integer division. Returns the quotient of two INTs, discarding
the remainder.
% Modulus. Returns the remainder upon dividing one INT by
another.
+ Has several uses. These are:
INT + INT - returns the sum of two INTs.
INT + TIME or TIME + INT - returns a TIME obtained by adding INT
minutes to the original TIME.
INT + DATE or DATE + INT - returns a DATE obtained by adding INT
days to the original DATE.
STRING + STRING - returns a STRING which is the concatenation of
the two original STRINGs.
STRING + anything or anything + STRING - converts the non-STRING
argument to a STRING, and then performs concatenation. See the
coerce() function.
- Has several uses. These are:
INT - INT - returns the difference of two INTs.
DATE - DATE - returns (as an INT) the difference in(1,8) days between
two DATEs.
TIME - TIME - returns (as an INT) the difference in(1,8) minutes
between two TIMEs.
DATE - INT - returns a DATE which is INT days earlier than the
original DATE.
TIME - INT - returns a TIME which is INT minutes earlier than
the original TIME.
<, <=, >, and >=
These are the comparison operators. They can take operands of
any type, but both operands must be of the same type. The com-
parison operators return 1 if(3,n) the comparison is true, or 0 if(3,n) it
is false. Note that string(3,n) comparison is done following the
lexical ordering of characters on your system, and that upper
and lower case are distinct for these operators.
==, != == tests for equality, returning 1 if(3,n) its operands are equal,
and 0 if(3,n) they are not. != tests for inequality.
If the operands are not of the same type, == returns 0 and !=
returns 1. Again, string(3,n) comparisons are case-sensitive.
&& This is the logical AND operator. Both of its operands must be
of type INT. It returns 1 if(3,n) both operands are non-zero, and 0
otherwise.
|| This is the logical OR operator. Both of its operands must be
of type INT. It returns 1 if(3,n) either operand is non-zero, and 0
otherwise.
NOTES
Operators of equal precedence are always evaluated from left to right,
except where parentheses dictate otherwise. This is important, because
the enhanced "+" and "-" operators are not necessarily associative.
For example:
1 + 2 + "string(3,n)" + 3 + 4 yields "3string34"
1 + (2 + "string(3,n)") + (3 + 4) yields "12string7"
12:59 + 1 + "test" yields "13:00test"
12:59 + (1 + "test") yields "12:591test"
The logical operators are not so-called short-circuit operators, as
they are in(1,8) C. Both operands are always evaluated. Thus, an expres-
sion such as:
(f!=0) && (100/f <= 3)
will cause an error(8,n) if(3,n) f is zero.
VARIABLES
Remind allows you to assign values to variables. The SET command is
used as follows:
SET var expr(1,3,n)
Var is the name of a variable. It must start with a letter or under-
score, and consist only of letters, digits and underscores. Only the
first 12 characters of a variable name are significant. Variable names
are not case sensitive; 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(1,2,n) 12:15
SET date today()
Note that variables themselves have no type. They take on the type of
whatever you store in(1,8) them.
To delete a variable, use the UNSET command:
UNSET var [var...]
For example, to delete all the variables declared above, use:
UNSET a b mydir time(1,2,n) date
SYSTEM VARIABLES
In addition to the regular user variables, Remind has several "system
variables" which are used to query or control the operating state of
Remind. System variables are available starting from version(1,3,5) 03.00.07
of Remind.
All system variables begin with a dollar sign '$'. They can be used in(1,8)
SET commands and expressions just as regular variables can. All system
variables always hold values of a specified type. In addition, some
system variables cannot be modified, and you cannot create new system
variables. System variables can be initialized on the command line
with the -i 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 SET command. All system variables hold val-
ues of type INT, unless otherwise specified.
$CalcUTC
If 1 (the default), then Remind uses C library functions to cal-
culate the number of minutes between local and Universal Time
Coordinated. This affects astronomical calculations (sunrise()
for example.) If 0, then you must supply the number of minutes
between local and Universal Time Coordinated in(1,8) the $MinsFromUTC
system variable.
$CalMode (read-only)
If non-zero, then the -c option was supplied on the command
line.
$Daemon (read-only)
If the daemon mode -z was invoked, contains the number of min-
utes between wakeups. If not running in(1,8) daemon mode, contains
0. For the MS-DOS version(1,3,5), always contains 0.
$DefaultPrio
The default priority assigned to reminders without a PRIORITY
clause. You can set(7,n,1 builtins) this as required to adjust the priorities
of blocks of reminders without having to type priorities for
individual reminders. At startup, $DefaultPrio is set(7,n,1 builtins) to 5000;
it can range from 0 to 9999.
$DontFork (read-only)
If non-zero, then the -c option was supplied on the command
line. For the MS-DOS version(1,3,5), always contains 1.
$DontTrigAts (read-only)
If non-zero, then the -a option was supplied on the command
line. For the MS-DOS version(1,3,5), always contains 0.
$DontQueue (read-only)
If non-zero, then the -q option was supplied on the command
line. For the MS-DOS version(1,3,5), always contains 1.
$EndSent (STRING type)
Contains a list of characters which end a sentence. The MSF
keyword inserts two spaces after these characters. Initially,
$EndSent is set(7,n,1 builtins) to ".!?" (period, exclamation mark, and question
mark.)
$EndSentIg (STRING type)
Contains a list of characters which should be ignored when MSF
decides whether or not to place two spaces after a sentence.
Initially, is set(7,n,1 builtins) to "'>)]}"+CHAR(34) (single-quote, greater-
than, right parenthesis, right bracket, right brace, and double-
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.
$FirstIndent
The number of spaces by which to indent the first line of a MSF-
type reminder. The default is 0.
$FoldYear
The standard Unix library functions may have difficulty dealing
with dates later than 2037. If this variable is set(7,n,1 builtins) 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(1,2,n) is in(1,8) effect in(1,8) 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 sav-
ings time(1,2,n) 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(3,n) the sun or UTC functions misbe-
have for years greater than 2037.
$FormWidth
The maximum width of each line of text for formatting MSF-type
reminders. The default is 72. If an MSF-type reminder contains
a word too long to fit in(1,8) this width, it will not be truncated -
the width limit will be ignored.
$HushMode (read-only)
If non-zero, then the -h option was supplied on the command
line.
$IgnoreOnce (read-only)
If non-zero, then the -o option was supplied on the command
line, or a date different from today's true date was supplied.
If non-zero, then ONCE directives will be ignored.
$InfDelta (read-only)
If non-zero, then the -t option was supplied on the command
line.
$LatDeg, $LatMin, $LatSec
These specify the latitude of your location. $LatDeg can range
from -90 to 90, and the others from -59 to 59. Northern lati-
tudes are positive; southern ones are negative. For southern
latitudes, all three components should be negative.
$Location (STRING type)
This is a string(3,n) specifying the name of your location. It is
usually the name of your town or city. It can be set(7,n,1 builtins) to what-
ever you like, but good style indicates that it should be kept
consistent with the latitude and longitude system variables.
$LongDeg, $LongMin, $LongSec
These specify the longitude of your location. $LongDeg can
range from -180 to 180. Western longitudes are positive; east-
ern ones are negative.
The latitude and longitude information is required for the func-
tions sunrise() and sunset(). Default values can be compiled
into Remind, or you can SET the correct values at the start of
your reminder scripts.
$MaxSatIter
The maximum number of iterations for the SATISFY clause
(described later.) Must be at least 10.
$MinsFromUTC
The number of minutes between Universal Time Coordinated and
local time. If $CalcUTC is non-zero, this is calculated upon
startup of Remind. Otherwise, you must set(7,n,1 builtins) it explicitly. If
$CalcUTC is zero, then $MinsFromUTC is used in(1,8) the astronomical
calculations. You must adjust it for daylight savings time(1,2,n)
yourself. Also, if(3,n) you want to initialize $MinsFromUTC using
the -i command-line option, you must also set(7,n,1 builtins) $CalcUTC to 0 with
the -i option.
$NextMode (read-only)
If non-zero, then the -n option was supplied on the command
line.
$NumQueued (read-only)
Contains the number of reminders queued so far for background
timed triggering. For MS-DOS, always returns 0.
$NumTrig (read-only)
Contains the number of reminders triggered for the current date.
One use for this variable is as follows: Suppose you wish to
shade in(1,8) the box of a PostScript calendar whenever a holiday is
triggered. You could save the value of $NumTrig in(1,8) a regular
variable prior to executing a block of holiday reminders. If
the value of $NumTrig 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(1,8) the calendar box. (See
the section "Calendar Mode".)
Note that $NumTrig is affected only by REM commands; triggers in(1,8)
IFTRIG commands do not affect it.
$PSCal (read-only)
If non-zero, then the -p option was supplied on the command
line.
$RunOff (read-only)
If non-zero, the RUN directives are disabled.
$SimpleCal (read-only)
Set to a non-zero value if(3,n) either of the -p or -s command-line
options was supplied.
$SortByDate (read-only)
Set to 0 if(3,n) no -g option is used, 1 if(3,n) sorting by date in(1,8)
ascending order, or 2 if(3,n) sorting by date in(1,8) descending order.
$SortByPrio (read-only)
Set to 0 if(3,n) no -g option is used, 1 if(3,n) sorting by priority in(1,8)
ascending order, or 2 if(3,n) sorting by priority in(1,8) descending
order.
$SortByTime (read-only)
Set to 0 if(3,n) no -g option is used, 1 if(3,n) sorting by time(1,2,n) in(1,8)
ascending order, or 2 if(3,n) sorting by time(1,2,n) in(1,8) descending order.
$SubsIndent
The number of spaces by which all lines (except the first) of an
MSF-type reminder should be indented. The default is 0.
Note: If any of the calendar modes are in(1,8) effect, then the values of
$Daemon, $DontFork, $DontTrigAts, $DontQueue, $HushMode, $IgnoreOnce,
$InfDelta, and $NextMode are not meaningful.
BUILT-IN FUNCTIONS
Remind has a plethora of built-in functions. The syntax for a function
call is the same as in(1,8) C - the function name, followed a comma-sepa-
rated list of arguments in(1,8) parentheses. Function names are not case-
sensitive. If a function takes no arguments, it must be followed by
"()" in(1,8) the function call. Otherwise, Remind 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
INT, STRING, DATE and TIME arguments, 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 DATE or an INT. "x_arg"
denotes an argument which can be of any type. The type of the argument
is followed by an underscore and an identifier naming the argument, for
convenience.
The built-in functions are:
abs(i_num)
Returns the absolute value of num.
access(2,5)(s_file, si_mode)
Tests the access(2,5) permissions for the file(1,n) file(1,n). Mode can be a
string(3,n), containing a mix of the characters "rwx" for read(2,n,1 builtins), write(1,2)
and execute permission testing. Alternatively, mode can be a
number as described in(1,8) the UNIX access(2,5)(2) system call. The
function returns 0 if(3,n) the file(1,n) can be accessed with the speci-
fied mode, and -1 otherwise.
args(s_fname)
Returns the number of arguments expected by the user-defined
function fname, or -1 if(3,n) 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 previ-
ously. The args() function is available only in(1,8) versions of
Remind from 03.00.04 and up.
asc(s_string)
Returns an INT which is the ASCII code of the first character in(1,8)
string(3,n). As a special case, asc("") returns 0.
baseyr()
Returns the "base year" which was compiled into Remind (normally
1990.) All dates are stored internally as the number of days
since 1 January of baseyr().
char(i_i1 [,i_i2...])
This function can take any number of INT arguments. It returns
a STRING consisting of the characters specified by the argu-
ments. Note that none of the arguments can be 0, unless there
is only one argument. As a special case, char(0) returns "".
Note that because Remind does not support escaping of characters
in(1,8) strings, the only way to get a double-quote in(1,8) a string(3,n) is to
use char(34). Yes, I know it's not portable - it assumes ASCII
coding.
choose(i_index, x_arg1 [,x_arg2...])
Choose must take at least two arguments, the first of which is
an INT. If index is n, then the nth subsequent argument is
returned. If index is less(1,3) than 1, then arg1 is returned. If
index is greater than the number of subsequent arguments, then
the last argument is returned. Examples:
choose(0, "foo", 1:13, 1000) returns "foo"
choose(1, "foo", 1:13, 1000) returns "foo"
choose(2, "foo", 1:13, 1000) returns 1:13
choose(3, "foo", 1:13, 1000) returns 1000
choose(4, "foo", 1:13, 1000) returns 1000
Note that all arguments to choose() are always evaluated.
coerce(s_type, x_arg)
This function converts arg to the specified type, if(3,n) such con-
version(1,3,5) is possible. Type must be one of "INT", "STRING",
"DATE" or "TIME" (case-insensitive). The conversion rules are
as follows:
If arg is already of the type specified, it is returned
unchanged.
If type is "STRING", then arg is converted to a string(3,n) consist-
ing of its printed representation.
If type is "DATE", then an INT arg is converted by interpreting
it as the number of days since 1 January baseyr(). A STRING arg
is converted by attempting to read(2,n,1 builtins) it as if(3,n) it were a printed
date. A TIME arg cannot be converted to a date.
If type is "TIME", then an INT arg is converted by interpreting
it as the number of minutes since midnight. A STRING arg is
converted by attempting to read(2,n,1 builtins) it as if(3,n) it were a printed time.
A DATE arg cannot be converted to a time.
If type is "INT", then DATE and TIME arguments are converted
using the reverse of procedures described above. A STRING arg
is converted by parsing it as an integer.
date(i_y, i_m, i_d)
The date() function returns a DATE object with the year, month
and day components specified by y, m and d.
dawn([d_date])
Returns the time(1,2,n) of "civil dawn" on the specified date. If date
is omitted, defaults to today().
day(d_date)
This function takes a DATE as an argument, and returns an INT
which is the day-of-month component of date.
daysinmon(i_m, i_y)
Returns the number of days in(1,8) month m (1-12) of the year y.
defined(s_var)
Returns 1 if(3,n) the variable named(5,8) by var is defined, or 0 if(3,n) it is
not.
Note that defined() takes a STRING argument; thus, to check if(3,n)
variable X is defined, use:
defined("X")
and not:
defined(X)
The second example will attempt to evaluate X, and will return
an error(8,n) if(3,n) it is undefined or not of type STRING.
dosubst(s_str [,d_date [,t_time]])
Returns a STRING which is the result of passing str through the
substitution filter(1,3x,3x curs_util) described earlier. The parameters date and
time(1,2,n) establish the effective trigger date and time(1,2,n) used by the
substitution filter. If date and time(1,2,n) are omitted, they default
to today() and now().
Note that if(3,n) str does not end with "%", a newline character will
be added to the end of the result. Also, calling dosubst() with
a date which is in(1,8) the past (i.e., if(3,n) date < today()) will pro-
duce undefined results.
Dosubst() is only available starting from version(1,3,5) 03.00.04 of
Remind.
dusk([d_date])
Returns the time(1,2,n) of "civil twilight" on the specified date. If
date is omitted, defaults to today().
easterdate(di_arg)
If arg is an INT, then returns the date of Easter Sunday for the
specified year. If arg is a DATE, then returns the date of the
next Easter Sunday on or after arg.
filedate(s_filename)
Returns the modification date of filename. If filename does not
exist, or its modification date is before the year baseyr(),
then 1 January of baseyr() is returned.
filedir()
Returns the directory which contains the current file(1,n) being pro-
cessed. It may be a relative or absolute pathname, but is guar-
anteed to be correct for use in(1,8) an INCLUDE command as follows:
INCLUDE [filedir()]/stuff
This includes the file(1,n) "stuff" in(1,8) the same directory as the cur-
rent file(1,n) being processed.
filename()
Returns (as a STRING) the name of the current file(1,n) being pro-
cessed by Remind. Inside included files, returns the name of
the included file.
getenv(s_envvar)
Similar to the getenv(2) system call. Returns a string(3,n) repre-
senting the value of the specified environment variable.
Returns "" if(3,n) the environment variable is not defined. Note
that the names of environment variables are generally case-sen-
sitive; thus, getenv("HOME") is not the same as getenv("home").
hour(t_time)
Returns the hour component of time(1,2,n).
iif(si_test1, x_arg1, [si_test2, x_arg2,...], x_default)
If test1 is not zero or the null string(3,n), returns arg1. Other-
wise, if(3,n) test2 is not zero or the null string(3,n), returns arg2, and
so on. If all of the test arguments are false, returns default.
Note that all arguments are always evaluated. This function
accepts an odd number of arguments - note that prior to version(1,3,5)
03.00.05 of Remind, it accepted 3 arguments only. The 3-argu-
ment version(1,3,5) of iif() is compatible with previous versions of
Remind.
index(s_search, s_target [,i_start)
Returns an INT which is the location of target in(1,8) the string(3,n)
search. The first character of a string(3,n) is numbered 1. If tar-
get does not exist in(1,8) search, then 0 is returned.
The optional parameter start specifies the position in(1,8) search at
which to start looking for target.
isdst([d_date [,t_time]])
Returns a positive number if(3,n) daylight savings time(1,2,n) is in(1,8) effect
on the specified date and time. Date defaults to today() and
time(1,2,n) defaults to midnight.
Note that this function is only as reliable as the C run-time
library functions. It is available starting with version(1,3,5)
03.00.07 of Remind.
isleap(id_arg)
Returns 1 if(3,n) arg is a leap year, and 0 otherwise. Arg can be
either an INT or a DATE object. If a DATE is supplied, then the
year component is used in(1,8) the test.
isomitted(d_date)
Returns 1 if(3,n) date is omitted, given the current global OMIT con-
text. Returns 0 otherwise.
hebdate(i_day, s_hebmon [,id_yrstart [,i_jahr [,i_aflag]]])
Support for Hebrew dates - see the section "The Hebrew Calendar"
hebday(d_date)
Support for Hebrew dates - see the section "The Hebrew Calendar"
hebmon(d_date)
Support for Hebrew dates - see the section "The Hebrew Calendar"
hebyear(d_date)
Support for Hebrew dates - see the section "The Hebrew Calendar"
language()
Returns a STRING naming the language supported by Remind. (See
"Foreign Language Support.") By default, Remind is compiled to
support English messages, so this function returns "English".
For other languages, this function will return the English name
of the language (e.g. "German") Note that language() is not
available in(1,8) versions of Remind prior to 03.00.02.
lower(s_string)
Returns a STRING with all upper-case characters in(1,8) string(3,n) con-
verted to lower-case.
max(x_arg1 [,x_arg2...)
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.
min(x_arg1 [,x_arg2...)
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.
minsfromutc([d_date [,t_time]])
Returns the number of minutes from Universal Time Coordinated
(formerly GMT) to local time(1,2,n) on the specified date and time.
Date defaults to today() and time(1,2,n) defaults to midnight. If
local time(1,2,n) 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(1,3,5)
03.00.07 of Remind.
minute(t_time)
Returns the minute component of time(1,2,n).
mon(di_arg)
If arg is of DATE type, returns a string(3,n) which names the month
component of the date. If arg is an INT from 1 to 12, returns a
string(3,n) which names the month.
monnum(d_date)
Returns an INT from 1 to 12, representing the month component of
date.
moondate(i_phase [,d_date [,t_time]])
This function returns the date of the first occurrence of the
phase phase of the moon on or after date and time(1,2,n). Phase can
range from 0 to 3, with 0 signifying new moon, 1 first quarter,
2 full moon, and 3 third quarter. If date is omitted, it
defaults to today(). If time(1,2,n) is omitted, it defaults to mid-
night.
For example, the following returns the date of the next full
moon:
SET fullmoon moondate(2)
moontime(i_phase [,d_date [,t_time]])
This function returns the time(1,2,n) of the first occurrence of the
phase phase of the moon on or after date and time(1,2,n). Phase can
range from 0 to 3, with 0 signifying new moon, 1 first quarter,
2 full moon, and 3 third quarter. If date is omitted, it
defaults to today(). If time(1,2,n) is omitted, it defaults to mid-
night. Moontime() is intended to be used in(1,8) conjunction with
moondate(). The moondate() and moontime() functions are accu-
rate to within a couple of minutes of the times in(1,8) "Old Farmer's
Almanac" for Ottawa, Ontario.
For example, the following returns the date and time(1,2,n) of the next
full moon:
MSG Next full moon at [moontime(2)] on [moondate(2)]
moonphase([d_date [,t_time]])
This function returns the phase of the moon on date and time(1,2,n),
which default to today() and midnight, respectively. The
returned value is an integer from 0 to 359, representing the
phase of the moon in(1,8) degrees. 0 is a new moon, 180 is a full
moon, 90 is first-quarter, etc.
now() Returns the current system time(1,2,n), as a TIME type. This may be
the actual time(1,2,n), or a time(1,2,n) supplied on the command line.
ord(i_num)
Returns a string(3,n) which is the ordinal number num. For example,
ord(2) returns "2nd", and ord(213) returns "213th".
ostype()
Returns "UNIX" on UNIX systems, "MSDOS" on MS-DOS systems, and
"OS/2" on OS/2 systems. If you run Remind in(1,8) an MS-DOS box
under OS/2, this function returns "MSDOS".
plural(i_num [,s_str1 [,s_str2]])
Can take from one to three arguments. If one argument is sup-
plied, returns "s" if(3,n) num is not 1, and "" if(3,n) num is 1.
If two arguments are supplied, returns str1 + "s" if(3,n) num is not
1. Otherwise, returns str1.
If three arguments are supplied, returns str1 if(3,n) num is 1, and
str2 otherwise.
psmoon(i_phase [,i_size [,s_note [,i_notesize]]])
Returns a STRING consisting of PostScript code to draw a moon in(