@comment Tell Emacs to use -*-texinfo-*- mode
@comment $Id: events.tex,v 2.3 91/09/01 23:04:21 royce Exp $

@node Events, Networking, Modem Stuff, Top
@chapter Events
@cindex Events

Events are a highly generalised way of making your Fnordadel do
things that it otherwise couldn't, like interface with networks other than
Citadel, run utility programs regularly, et cetera.  The mechanism allows
unlimited flexibility with minimal useless baggage; if we had to build all
these neat extra things into Fnordadel itself, it would be the
programming equivalent of Monty Python's ``Mr. Creosote''.

There are three general types of events.

@itemize @bullet
@item
@cindex Timeout event
@dfn{Timeout events} cause Fnordadel to exit to
its calling program (a shell, if you want to do anything
useful) at a specified day and time.  The @sc{bbs} will be polite
enough to wait for any current online user to terminate
before exiting.
@item
@cindex Preemptive event
@dfn{Preemptive events} are like timeout events except that
Fnordadel won't be the least bit polite; it will
immediately boot anybody who is logged in.
@item
@cindex Network event
@dfn{Network events} invoke the built-in networker, to do
standard Citadel networking.  Please @pxref{Networking}, for a
nauseatingly-detailed description of networking.  These kind
of events will rudely boot any online user, as with the
preemptive type.  Note that during a network event, the system
will be effectively closed to normal user traffic---it will
blurt out a terse message if it discovers that a caller is not
a Citadel net node, and drop carrier on him/her.
@end itemize

@node Events in General, Notes on Events, Events, Events
@section Events In General
@cindex Configuration, events

Events are set up in @file{ctdlcnfg.sys}, as you'd expect.  Each
event is defined separately, and the format of the definition is:
@cindex Event declaration
@vindex event
@example
#event <@var{type}> [@var{days}] <@var{time}> <@var{duration}> <@var{name}> <@var{flags}>
@end example
@noindent
where the fields mean:
@table @code
@item <@var{type}>
One of @samp{timeout}, @samp{preemptive} or @samp{network}.
@item [@var{days}]
This is optional.  If there, it gives the days that
the event will happen.  This field is either @samp{all},
meaning that the event happens every day, or any
combination of @samp{Mon}, @samp{Tue}, @samp{Wed}, @samp{Thu}, @samp{Fri}, @samp{Sat},
or @samp{Sun}---separated by commas.  For example, if you
wanted an event for Monday, Wednesday, and Saturday,
you would use a days field of @samp{Mon,Wed,Sat}.
@item <@var{time}>
When the event is scheduled to go off (in
24-hour time---e.g., 3:00pm is @samp{15:00}).
@item <@var{duration}>
How long the event is supposed to last,
in minutes.  If Fnordadel is brought up after the
start of an event but before the event is supposed to
be over, it will immediately do the event.
@item <@var{name}>
A meaningful (to you) name for the event (up to 19
alphanumeric characters, no spaces.)
@item <@var{flags}>
Depends on the type of event.  For timeout and
preemptive events, it is the condition code to be
returned to the calling program; remember not to use
@samp{0} through @samp{3}, as these are reserved for Fnordadel's
own purposes.  (See @file{citadel.man} for their specific
meanings.)  For network events, <@var{flags}> represents the
number of the specific net to be used.  (@xref{Network events},
for more details.)
@end table

Here are a couple of examples:

@vindex event
@example
#event NETWORK all 2:30 30 ld-net 1
@end example
This sets up a network event to run every night
at 2:30 AM, lasting for 30 minutes.  The event is called
@samp{ld-net}, and will use network #1.

@vindex event
@example
#event TIMEOUT Mon,Wed,Fri 6:00 0 uucp-net 10
@end example
This one sets up a timeout event for 6:00 AM on
Mondays, Wednesdays and Fridays.  The event is called
@samp{uucp-net}, and exits to the shell with code 10.  (The
shell, presumably, knows what to do when it gets a 10
back---@pxref{Running from a Shell}.)  Since the event is a timeout and
not preemptive, if a user is logged in at 6:00, the system
will wait until he/she terminates before exiting to the
shell.

You may have any number of events defined in @file{ctdlcnfg.sys},
though there are some practical limits---too many events and your
system won't be up long enough for a user to sign on.

@node Notes on Events, Timeouts, Events in General, Events
@section Some Notes on Events

@itemize @bullet
@item
@xref{Shells vs. the Desktop}, for some ideas of
what to use all this event stuff for.  But we'll tell
you now:  If you're running from the desktop, you can't
really use timeout/preemptive events, because the desktop
has no mechanism for dealing with codes returned by
programs.

@item
If you set up a timeout event, followed soon after by a
preemptive event, and a user logs stays logged in through
the duration of the timeout and into the preemptive,
silly things will probably happen.

@item
If the event is a timeout or preemptive event, you'd
probably want to use a <@var{duration}> of @samp{0}, to prevent the
situation where Fnordadel exits, the shell does
whatever it does, the shell finishes, and then reruns
Fnordadel, all before <@var{duration}> has expired---Fnordadel
would then exit all over again.

@item
An event causes Fnordadel to exit completely; this is
different from a door, which causes Fnordadel to act
as a shell and run another program, while still remaining
in memory.  @xref{Doors}, for information on doors.
@end itemize

@node Timeouts,  , Notes on Events, Events
@section Timeouts
@cindex Timeouts

An additional form of event is the specialised variable
@code{timeout}.  (This should not be confused with an
@vindex event
@code{#event} of type
@vindex timeout
@code{#timeout}.)  If you have the variable
@vindex timeout
@code{#timeout} defined as @samp{1} in
@file{ctdlcnfg.sys}, Fnordadel will look for another variable called
@vindex hourout
@code{#hourout}.  The system will set up a timeout event for
@vindex hourout
@code{#hourout}
hours after the system comes up, and will exit to the shell
with a condition code of @samp{1}.  Here's an example:
@vindex timeout
@vindex hourout
@example
#define timeout 1
#define hourout 8
@end example
This will, in effect, cause Fnordadel to take itself down
every 8 hours (because the counter is reset every time the is brought up.)
This feature is designed for doing things like regular backups controlled by
a shell script.

