OS/2 Shareware BBS: 2 BBS/02-BBS.zip/unisch1a.zip/UNISCHED.ENG

Text File | 1999-06-25 | 125KB | 2,530 lines

                U N I S C H E D   -   The Universal Scheduler
                ---------------------------------------------
                                Version 1.0a GA
                          (C) 1996-99 by Tobias Ernst

       (A German Documentation can be found in the file UNISCHED.GER).


CONTENTS
--------

1.     What is Unisched?

2.     What do I need Unisched for?

3.     Unisched Step by Step
3.1    Before the Installation
3.1.1  The TZ Environment Variable
3.1.2  Unpacking the Distribution Archive
3.2    Description of the Configuration File Syntax
3.3    Events und Actions
3.3.1  Actions
3.3.2  Recursions
3.3.3  Events
3.4    Using Unisched (invocation, user interface)

4.     Advanced UniSched Usage
4.1    Online Tossing
4.2    Selective suppression of log file messages
4.3    Delayed reaction on semaphore files

5.     Shareware

6.     Miscellaneous


1. WHAT IS UNISCHED?
--------------------

Unisched  is  a  fully  year  2000  compliant scheduler software that has been
designed with special consideration of the needs of a Fidonet node system.  To
cut it short:  Unisched  can  react  to  various  kinds of events with various
actions.  Possible events are:

- time controlled events (for example:  every day at 15:00, every 1. each
  month at 10:00, every 30 minutes, ...)
- the creation of sempahore files / flag files by other programs
- new mail has been received in the mailer's inbound directory
- a function key has been pressed at the Unisched console

Possible actions are:

- An external program, batch file, script, Workplace Shell object can be
  startet.
- Unisched can exit with a certian error level.
- Unisched can modify a Binkley style static outbound (create a poll,
  change the flavour of a mail packet, ...)
- Others (like playing music, creating flag files, deleting flag files, ...)

Unisched is intended to be a powerful program built around a simple and easily
intelligible concept.  In order  to  fully understand the event-action concept
of Unisched, I suggest that you carefully read the documentation, but at least
you should read section 3.3.  Unisched is not like other  schedulers,  so  you
will surely profit from reading the docs :-).

Unisched  is available as a 16 bit DOS executable (which is multitasking aware
and has  been  successfully  tested  unter  plain  DOS,  DESQview, Windows 95,
Windows NT  and  OS/2)  and  of  course  as  32  bit  native  OS/2  executable
(UNISCHE2.EXE).  If you use the DOS executable, SHARE.EXE or a similar support
for file locking MUST be active!


2. WHAT DO I NEED UNISCHED FOR?
-------------------------------

The  possible fields of application of Unisched are diverse, and it surely can
be useful even for  non-Fidonet  specific  purpose.  However, I have primarily
written it to be a frontend for a seperate  tosser  task  of  a  Fidonet  node
system, and this is where Unisched's strengths play at their best.

Instead  of  having  to  fiddle  around in mailer batch files and mailer event
files, the node can have  a  separate  independent  tosser  task (be it a task
under a multi tasking operating systems, or a separate DOS computer in a local
area network).  Unisched is being active 24/7.  At certain times it starts the
tosser to let it export mail that has been written  locally  or  in  the  BBS.
Every  time  the  mailer  receives  mail, Unisched sees it (either because the
mailer has created a semaphore  file  indicating that mails has been received,
or because Unisched has poked directly in the inbound  directory)  and  starts
the  tosser  to  let  it import the mail.  If the sysop ever feels the need to
manually start the tosser, he simply  presses a function key in Unisched which
is associated to the same action as the event that  automatically  starts  the
tosser.  Every morning at seven o'clock, Unisched plays a little wake-up tune,
and, and, and ....

The  advantage  of this approach is obvious:  If you start the tosser directly
from the mailer batch, on a  multiline  system,  you always must take the risk
that two tossers are running parallel.  Also, if you start the tosser from the
mailer batch, the result is that the mailer is not  available  while  you  are
tossing.   These are two strong reasons why you want to have a separate tosser
task.

Unisched separates what should have been separated in  the  first  place:  The
mailer  exclusively  serves  the  modems,  and Unisched does the rest.  In the
mailer event file, you only  need  to  define  two events, namedly ZMH and the
rest of the day, so that the mailer does not have to do enything  except  what
it has been designed for: to exchange mail. :-)


3. UNISCHED STEP BY STEP
------------------------

  3.1. BEFORE THE INSTALLATION
  ----------------------------

    3.1.1 The TZ Environment Variable
    ---------------------------------

    Unisched uses  the  TZ  environment  variable,  which contains information
    about the time zone that you live in.  It is not strictly  necessary,  but
    it  prevents  ugly  side  effects  when  you turn the clock from summer to
    winter time and vice versa.

    I don't want to bore you at this point, so I simply  tell  you  the  right
    values   for  the  variable.   (Unfortunately,  the  contents  of  it  are
    absolutely non-intuitive  and  also  non-trivial).   The terminus "Summer"
    refers to daylight saving time.

    Continental Europe:            SET TZ=MEZ-1
    Continental Europe, Summer:    SET TZ=MEZ-2MSZ

    Greenwich Mean Time:           SET TZ=GMT
    Greenwich Mean Time, Summer:   SET TZ=GMT-1GST

    Eastern Standard Time:         SET TZ=EST5
    Eastern Standard Time, Summer: SET TZ=EST4EDT

    Pacific Standard Time:         SET TZ=PST8
    Pacific Standard Time, Summer: SET TZ=PST7PDT

    Other programs also  use  the  TZ  variable  (for  example the tosser when
    generating Via lines), so it can't do any harm  to  set  these  values  in
    autoexec.bat  (DOS)  resp.   Config.Sys  (OS/2) and to reboot the computer
    afterwards.

    When you change your clock  from  daylight  savings to normal time or vice
    versa, you should stop  Unisched,  change  the  TZ  variable,  reboot  (if
    necessary),  and  restart  Unisched.   Otherwise you risk that some events
    might be executed multiple  times.   (Of  course  this normally is not too
    serious a problem).

    There also is a POSIX  specification  for  the  TZ variable, and there are
    several programs floating  around  that  calculated  TZ  variable  strings
    according to the POSIX standard.  The advantage of these variables is that
    you  do  not  have to change them when you switch from daylight savings to
    normal time and vice versa.  The problem is that Unisched does not support
    this standard, and quite  some  other  programs,  like Fastecho, do not as
    well.  This is not a fault of Unisched or Fastecho, but it is a  fault  of
    the  compilers  that  have been used to compile these programs.  While IBM
    VAC++ and EMX GCC support the POSIX standard, other compilers like Borland
    C do not.


    3.1.2 Unpacking the Distribution Archive
    ----------------------------------------

    The original distribution archive is ZIP compressed.  If you are  an  OS/2
    user,  you  should  uncompress  the  file with the OS/2 version of Infozip
    UNZIP or with the OS/2 version  of  PKZIP 2.50.  If you use other programs
    to unzip  the  archive,  the  extended  attributes  of  UNISCHE2.EXE  will
    probably be lost, so that UNISCHE2.EXE will not have an icon associated.



  3.2. DESCRIPTION OF THE CONFIGURATION FILE SYNTAX
  -------------------------------------------------

  Normally  Unisched  is  not case sensitive, i.E. you may either use UPPER or
  lower case or even MiXeD spelling.

  Before  we  start  to explain the underlying concept of EVENT and ACTION, we
  have to preconfigure Unisched with  things  like path names etc.  Therefore,
  this section contains a description  of  all  valid  keywords  in  the  file
  UNISCHED.CFG.   If you are bored by this, you can skip this section, but you
  should definitely resume reading at section 3.3.

  UNISCHED.CFG is divided into  two  parts.   The  first part contains general
  settings and will be described in this section.  The  second  part  contains
  the  EVENT and ACTION configuration, which will be described in section 3.3.
  The order of the commands inside the  config file is more or less irrelevant
  (with some notable exceptions like Logfile and SemaDir).

  Inside the configuration file, you may use  %ENVIRONMENT%  variables.   This
  means  that  the  string  %VARIABLE%  will  be  replaced by the value of the
  environement varalbe named VARIABLE.  If for some reason you want to print a
  single "%" sign in the configuration file,  you have to double it like this:
  "%%".

  A  semicolon  ";",  which is either in the first column of the configuration
  file or is preceded by a whitespace character is treated as the beginning of
  a commentary which last until the  end  of the respective line.

  Now for the keywords that can  be  used.   In this section and the following
  ones, [ square brackets ] enclose parameters that are optional, the  |  pipe
  character  separates  parameters  that are mutually exclusive, and  <pointed
  brackets> enclose textual placeholders  for  values  that you should insert.
  All other special characters should be typed verbatim.


   Alivetime = <minutes>
   ---------------------

   On  startup,  Unisched  creates the file "UNISCHED.BSY", which will only be
   deleted  when  Unisched   exists   regularly.   The  "Alivetime"  parameter
   configures how often the time stamp of this file should  be  updated  (i.E.
   how  often  the  file  should  be  "touched").   If  you do not specify the
   "Alivetime" paramter, UNISCHED.BSY will never be touched except on startup.

   Please note that setting  Alivetime  will  render any powersaving modes for
   your harddisk inoperative.

   Example:
   Alivetime = 1



   Autofail = On | Off
   -------------------

   If a critical error occurs (like disk  not  ready,  sharing  violation,  et
   cetara),  normally, your OS operating system would prompt you with an error
   message ("Retry, Abort, Fail" under  DOS,  a  dialog box on OS/2).  Because
   this is not what you want when running Unisched unattended --- after all it
   would stop the execution of any actions until until you go to  the  console
   and  confirm  the  dialog  box  ---  Unisched  by default installs an error
   handler that disables these  error  messages  or  dialog boxes, and set the
   default  action  to  "Fail"  (i.E. Unisched will get an error code from the
   OS and will know how to deal with it).

   If for any reason you want or need to disable the error  handler,  you  can
   set "Autofail = Off" in your Unisched config file.

   Note that on OS/2, the error handler is only valid for Unisched itself, e.g.
   if a process that is spawned by Unisched has a critical error, but does not
   have  an  error  handler  of  its  own,  you will again get the dialog box.
   Therefore, on OS/2 it is always a  good idea to put "AUTOFAIL=YES" into the
   CONFIG.SYS file if you want to run unattended.

   Bsp:
   Autofail = On



   Clock = On | Off
   ----------------

   This specifies if the title bar of Unisched should contain a digital  clock
   or not.  Per default, the clock is enabled, but if you disable it, you will
   save a little more CPU power ...

   Example:
   Clock = Off


   DiskLog = <Loglevels>
   ---------------------

   This parameter tells what sorts  of  messages  will  be logged into the log
   file on disk (it has nothing to do with the log  window!).   The  following
   loglevels  can  each be turned on by specifying their identifying character
   as parameter:

       standard status messages (not configurable)
   ?   error messages and warnings (not configurable)
   *   semaphore events      \
   .   function key events    \  all these are triggers for actions that
   ~   periodic events        /  Unisched performs
   #   static events         /
   +   actions (that what is triggered by events)
   -   some debug messages (only in wide beta versions)
   p   messages of the action definition parser
   _   an empty line aftereach event-action block (it improves readability
       if there is lot of logging output).

   Example:
   DiskLog = !?*.~#+-


   ExcessiveSlicing = <number> | Yes | No
   --------------------------------------

   This  switch  pertains to timeslice releasing in multi tasking environments,
   i.E. you can configure how  cooperative  Unisched behaves.  If the parameter
   to ExcessiveSlicing is a number not equal  to  zero,  a  significant  higher
   amount  of timeslices is released than otherwise.  "Yes" is another word for
   "5", No for "0".  If you should  set  ExcessiveSlicing to Yes or to No or to
   another number strongly depends on your system configuration.   The  general
   rule  for  testing  which  number  fits  best  is:   It should be as high as
   possible, but the clock in  the  upper  right  corner should still show each
   second separately.

   The following values have proven good results:

     OS/2 native:    0
     OS/2 DOS box:   1 or 0
     Windows NT:     20
     Windows 95:     0, maybe a little more


   FlushLog = Yes | No
   -------------------

   If FlushLog is set to Yes (default), Unisched forces the  operating  system
   to  write  its log file on disk as soon as Unisched is idle, by closing the
   file and repening it.  The advantage of this is that if the system crashes,
   the log file will be  up  to  date  until  the point of the crash.  Another
   advantage is that you can view the Unisched log file with a log file viewer
   while Unisched is running.

   If you don't want Unisched to close and reopen the log file  when  it  gets
   idle (I don't know any reasons though), you can set "FlushLog = No".



   IgnoreOldBusyFlag = <minutes>
   -----------------------------

   Besides  flow  files,  which contain references to the files that are to be
   sent to your links, the Binkley  outbound  can also contain a .BSY file for
   each node, which serves for access serialization:  While  a  .BSY  file  is
   present,  no other programs (except for the one that created the .BSY file)
   may modify the flowfile of the respective node.

   Unisched recognises .BSY files:   When  a  .BSY  file  is  found,  Unisched
   postpones  the  action that it intends to make on the Binkley outbound, and
   periodically tests if the .BSY  file  still exists, and performs the action
   as soon as the .BSY file has vanished (then creating a .BSY file for itself
   while modifying the outbound, of course).

   Sometimes, though, the Binkley outbound contains  .BSY  files  that  result
   from  programs  that  have  been stopped the hard way (kill or lockup).  If
   terminated irrgularly, those  programs  can't  delete  their .BSY files, so
   these .BSY files are now orphan.  The result:  No new files can be sent  to
   the  outbound for eternity, because there is no one left to delete the .BSY
   file.

   Unisched  tries  to  detect  this  situation.   If a .BSY file that hinders
   Unisched in doing something  in  the  outbound  is  older than three hours,
   Unisched assumes that it is orphaned and deletes the .BSY file.

   If you want to change the deafult value of three hours, you  can  configure
   it  with  the "IgnoreOldBusyFlag" keyword.  The argument is assumed to be a
   value in minutes, so the default value of three hours would be expressed as
   "180".  If you set the argument to  0, the feature will be tunred off, e.g.
   orphaned .BSY files will never be force-deleted, but will  block  the  link
   until the sysop manually removes them.

   Example:
   IgnoreOldBusyFlag = 90


   IgnoreOldBusySem = <minutes>
   ----------------------------

   A similar mechanism like for  orphaned  .BSY  files in the binkley outbound
   also exists for the UNISCHED.BSY  file,  a  semaphore  which  indicates  if
   Unisched  is  running  or  not.   If,  on  startup,  Unisched sees the file
   UNISCHED.BSY, it assumes that another Unisched task is already running, and
   does not start itself.

   If  you  use "IgnoreOldBusySem", Unisched tests the age of UNISCHED.BSY (if
   found), and if it is older than the specified number of minutes, it removes
   the file, recreates it, and starts up,  because it assumes that the file is
   orphaned.

   Please do  note  that  you  MUST  use  AliveTime  (see  above)  if  you use
   IgnoreOldBusyTime  in  order  for  the   timestamp   UNISCHED.BSY   to   be
   continuously updated as long as Unisched is not dead, but running.

   Which numbers to choose  for  AliveTime  and IgnoreOldBusySem depend on the
   configuration of Unisched.  If you  start  all  external  programs  in  the
   background  (e.g. with EXEC START or START under OS/2), Unisched will never
   be inactive (but running) for more  than  a few seconds.  You can use small
   values in this case:

   AliveTime = 1
   IgnoreOldBusySem = 5

   If, however, you start any lengthy  task  in  the  foreground  (e.g.   EXEC
   TOSS.BAT), Unisched could be inactive (though not dead) for quite long time
   spans,  and  you  should  set  the IngoreOldBusySem timeout value to a high
   value.  A tossing task (e.g.  system  organization)  can easily take one or
   more hours:

   AliveTime = 10
   IgnoreOldBusySem = 180

   No matter how you do it, you  should  -  to help your system to continue to
   work even if you are away - start Unisched from a simple  batch  file  that
   restarts  Unisched  if it exits because of a busy sempahore file.  Unisched
   exits with error level  255  in  this  case.  However, Unisched sleeps some
   seconds before exiting, so that even if  the  batch  continuously  respawns
   Unisched  for quite some time, it will not suck of too much processor load,
   and finally (if the .BSY  file  has  vanished or is expired), Unisched will
   start up.

   :start
   unische2 /cunisched.cfg
   if errorlevel 255 goto start



   Include = <path+filename>
   -------------------------

   Use this to include additioal configuration file at the current position.

   Example:
   Include = e:\configs\colors.cfg



   KeyColumns = <cols>
   -------------------

   This keyword sets the number of columns that  are  used  for  printing  the
   function  key  descriptions  in the upper half of the Unisched window.  The
   default is 4, but if  you  use  small  window  sizes or longer event names,
   using only three columns might improve readability.

   Example:
   KeyColumns = 3



   Logfile = <path+filename>
   -------------------------

   This keyword should be the very  first  line in the configuration file.  It
   specifies the location and filename of the log file.

   Example:
   Logfile = e:\box\log\unisched.log

   If for whatever reason you  are  running  multiple  instances  of  Unisched
   simultaneously, each one must use its own log file.



   MTask = <multitasker>
   ---------------------

   Unisched is extremely multitasking friendly.  Even the DOS version is  able
   to  recognise  a  huge bunch of common multitaskers and release time slices
   accordingly in order to use  as  few  processor time as possible.  Unisched
   normally autodetects the multitasker in use (it is printed on startup).  If
   Unisched does not detect the multitasker that you are using  (this  happens
   e.g.  for  Topview),  you  can  hard-wire  it using the MTask keyword.  The
   following arguments can be given for <multitasker>:

     Argument    Meaning
     --------    --------
     DESQview    Quarterdeck DESQview
     PC-MOS      PC-MOS
     Windows     Windows 3.1, 95 und NT (actually, the DPMI time slice)
     DoubleDOS   DoubleDOS
     OS/2        Why don't you use UNISCHE2.EXE instead? ;-)
     TopView     TopView
     Multilink   Multilink
     BIOS        Timeslicing via BIOS calls. Better than nothing, at least.
                 It is said to be useful under Netware.
     Generic     Timeslicing via the multiplexer interrupt. Better than
                 nothing, at least.
     None        Completely disables time slicing.

   Also notice the corresponding  setting  of the "ExcessiveSlicing" parameter
   (see above).



   Outbound = <path>
   -----------------

   This keyword configures the base path of the static Binkley style mail/file
   outbound.   It  is required for the POLL, SEND, and other actions.  Even if
   you are not running a Fidonet node  system, you must set this keyword.  You
   can point it to an empty or non-existing directory, of course, as  long  as
   you don't use special Fidonet actions.

   Example:
   Outbound = e:\box\binkley\outbound

   The outbound directories for other zones (like outbound.0f2 etc.) are being
   automatically  calculated  by  Unisched.  If, however, you are using a full
   domain setup (for example  zone  242,  fido.de,  would result in fidode.0f2
   instead of outbound.0f2),  you  need  to  configure  each  domain  outbound
   directory as shown below.


   <zone number> = <outbound base name>
   ------------------------------------

   This is the domain setup.  You need it if your mailer uses  a  full  domain
   setup, where e.g. files for zone 242 are not stored in outbound.0f2, but in
   fidode.0f2.   (This  is the Binkley domain setup, other mailers like McMail
   do not change the outbound  directory  names  even if you do configure them
   for domains).  Important:  The <outbound base name> parameter specifies the
   physical base path name of the outbound directory, but not the real  domain
   name.   Also  imporant:  The zone number must be specified decimally.  Some
   examples:

   zone number     domain name:    outbound path
   1               fidonet         e:\inout\outbound.001
   2               fidonet         e:\inout\outbound
   ...
   6               fidonet         e:\inout\outbound.006
   9               virnet          e:\inout\virnet.009
   242             fido.de         e:\inout\fidode.0f2

   If you have a configuration like above, you would have to configure  it  in
   Unisched as follows:

   Zone = 2
   Outbound=e:\inout\outbound
   9   = Virnet
   242 = FIDODE

   You see: fidode (NOT fido.de), but 242 (NOT 0f2)



   Pipe = <pipe name>
   ------------------

   This  makes  Unisched write its log messages into a named pipe (in addition
   to the log file).  You can read  the  message  from the pipe on the same or
   (which is the main application of this feature) on a different  machine  on
   the  network with programs like PMPIPER, PIPEMAN, RXSNOOP and others.  This
   feature is often used to  monitor  Unisched  which  is running on a distant
   server from a client in the network. Example:

   Pipe = \\pipe\unisched

   Unisched supports reconnects for pipes, which means that you do not need to
   restart Unisched after the pipe has been terminated by the client.

   You should only configure a pipe if you intend to use it, because otherwise
   it slows down the startup of Unisched unnecessarily.



   PipeLog = <Loglevels>
   -----------------------

   Here you can specify what sort of messages should be visible in  the  named
   pipe.  The syntax is the same as for the "DiskLog" keyword (see above).



   RecentActivityLines = <n>
   -------------------------

   This  line  configures how many lines of log messages should be kept in the
   back scroll buffer.  The back scroll buffer stores old log messages for the
   log window, so that you can use PgUp/Dn, Home/End and the  cursor  keys  to
   scroll  through old entries in the log window.  (This is not related to the
   log file in any way).   The  default  value  for  this variable is 100, and
   changing it above 500 can only be recommonded in the OS/2 version.



   ResetDialCounters = Yes | No
   ----------------------------

   If you set it to yes, Unisched  will erase all nodial marks, dial counters,
   overtry flags etc. for the node for which it creates a poll.   Do  consider
   carefully  if  you  really want to use this option.  As an alternative, you
   could also use the RDC argument to the POLL action (see below) for selected
   polls.



   RescanSema = <path+filename>
   ----------------------------

   When Unisched creates a poll file  (*.?LO)  in the Binkley outbound, it can
   optionally create/touch a flag file that tells the mailer that it has to do
   an outbound rescan.  As the RescanSema argument, you can specify  the  file
   name of such a flag file.

   Example (settings for Binkley resp. McMail):
   RescanSema = e:\box\sema\btrescan.flg
   RescanSema = e:\box\sema\mcmscan.all

   Some  mailers  support  sempahore  files that are only valid for a specific
   mailer task number (line) that should preferably do the outbound rescan and
   perform the poll.  The line number  is  then normally coded into the rescan
   semaphore file name.  If you have a mailer of this sort, you can  code  the
   line  number  into  the  RescanSema filename argument by specifying C-style
   formatter arguments, the most commonly used of which are listed below:

   %d   The line number, in decimal notation.
   %03d The line number, in decimal notation.  If it has less than three
        digits, it is padded with zeros on the left.
   %x   The line number, in hexadecimal notation.
   %02x The line number, in hexadecimal notation.  If it has less than two
        digits, it is padded with zeros on the left.
   etc.

   Example (setting for McMail):
   RescanSema = e:\box\sema\mcmscan.%d

   The result is that Unisched creates  either mcmscan.1, or mcmscan.2, and so
   on, depending on which line should preferably do the outbound rescan (which
   you can specify as argument to the POLL action, see below).

   You can give up to ten different "RescanSema" lines  in  the  configuration
   file.   If  so,  Unisched  will  create all flag files that are configured.
   This is useful  if  you  are  using  different  mailer software parallel or
   sometimes the one mailer and sometimes the other and always  want  Unisched
   to  create all relevant rescan semaphore files.



   Registername = <Name>
   Registerkey = <Key>
   ---------------------

   Send me 12 US-$, and I'll tell you what you have to configure here ;-).



   ScreenLog = <Loglevels>
   -----------------------

   Here you can specify what sort of messages should be visible in the message
   window.  The syntax is the same as for the "DiskLog" keyword (see above).



   SeeHiddenFiles = Yes | No
   -------------------------

   This flag controls if Unisched, when looking for semaphore files and  other
   flag  files  (for  a  detailed  explanation see below), sees "hidden" files
   (files with the "hidden" or  "system"  attribute),  or  if it will only see
   normal files (which is the default setting).



   SemaDir = <pathname>
   --------------------

   The <pathname> argument  of  the  SemaDir  keyword  specifies the semaphore
   directory.  This is the directory where signal  files,  usually  with  zero
   length,  are placed by your mailer and other tools.  Note that Unisched can
   look for semaphore files even if  they reside in other places.  The SemaDir
   keyword is only for your convenience:  If you specify a name of a semaphore
   file that is not an absolute path name, Unisched will assume that the  file
   resides  in  the  SemaDir.  So  if  you have to configure lots of semaphore
   files, you will be saved from some  typing work.  -- Semadir only works for
   sempahore  file  names  that  are  specified  AFTER  the  SemaDir  in   the
   configuration file.  Therefore, you should put the SemaDir keyword near the
   beginning of the Unisched configuration file.

   Example:
   SemaDir = e:\binkley\flags



   SemaphoreCheckInterval = <seconds>
   ----------------------------------

   As  will  be  explained  in detail below, Unisched can trigger actions when
   certain files appear or  disappear,  become  older  than xx hours, etc.  To
   perform this task, Unisched must access the hard disk periodically in order
   to be able to see if anything has changed for  the  files  that  are  being
   surveyed.

   With  the  SemaphoreCheckInterval  keyword,  you  can  configure  how often
   Unisched will do this  check.   The  <seconds>  parameter  is  only  to  be
   considered  as  a  gross  guideline.   The  standard  value  is 1 (test for
   semaphore files every second),  granting  that  Unisched  will react to any
   possible changes as often as possible.  The standard value is good as  long
   Unisched  only  checks  files  on a lokal hard disk, as these requests will
   usually be satisfied by some sort of file system cache.

   If you let Unisched test for files  that reside on a volume that is mounted
   via LAN, or on volumes that are not being  cached  for  some  reasons  (DOS
   without SmartDrv, for example), it is recommended to raise this value to 10
   seconds  or  higher,  in  order  to  reduce network and/or disk IO bandwith
   usage.

   Example:
   SemaphoreCheckInterval = 30    ;test every half minute



   SmallWindow = On | Off
   ----------------------

   When SmallWindow = On is  set,  Unisched  will only use 66x18 characters of
   the display window, instead of 80x25.  This is useful  under  DESQview,  if
   you configure a smaller window size.

   Under  OS/2  this  parameter  is  deprecated  and useless, because the OS/2
   version is able to  autodetect  the  terminal  window size.  Simply use the
   MODE command before starting Unisched to set an arbitrary window  size  (as
   for  example "MODE CO66,16"), and Unisched will automatically adapt to this
   size when started.

   Example:
   SmallWindow = Off



   SpawnInit = $action_name
   ------------------------

   The given action will  be  executed  once  at program startup.  Section 3.3
   explains what actions are and how to set them up, so don't  worry  at  this
   point.  Up to 16 SpawnInit actions are possible.

   Example:
   SpawnInit = $welcome_song

   Hint for OS/2 users:  It won't work to use "SpawnInit = EXEC MODE CO66,18".
   The  reason  for this is that the terminal window detection code on OS/2 is
   executed before the SpawnInit actions, due to a restriction in the compiler
   that I use.  If you want to  change  the VIO terminal window size, you need
   to do it before calling Unisched, probably in a CMD file.



   Zone = <nr>
   -----------

   This keyword is used to configure your FTN home zone (Europe:  2, USA:  1),
   i.E. the zone number  for  which  the  outbound  directory  does not have a
   number prefix.  This setting is obligatory, as it  is  needed  for  correct
   determination  of  the  outbound  directory  names.   If  you do not have a
   Binkley outbound or do not want  to  use the POLL and related actions, just
   configure anything, but do configure something.

   Example:
   Zone = 2



   ColBorder          = <nr>
   ColKeys            = <nr>
   ColKeyDescriptions = <nr>
   ColHeadLine        = <nr>
   ColEvent           = <nr>
   ColLog             = <nr>
   -------------------------

   Use these keywords to configure the color layout of Unisched.  Just try out
   for yourself which parts of the  window  are changed by which keyword.  The
   color numbers (the <nr> parameters) are calculated using
     <nr> = <foreground color> + 16 * <background color>
   where <foreground color> and <background  color>  can  be  taken  from  the
   following table:

                │     │Back-  │Fore-                    │     │Back-  │Fore-
   Color        │Value│ground?│ground?     Color        │Value│ground?│ground?
   ═════════════╪═════╪═══════╪═══════    ══════════════╪═════╪═══════╪═══════
   BLACK        │  0  │ Yes   │ Yes        DARKGRAY     │  8  │ No    │ Yes
   BLUE         │  1  │ Yes   │ Yes        LIGHTBLUE    │  9  │ No    │ Yes
   GREEN        │  2  │ Yes   │ Yes        LIGHTGREEN   │ 10  │ No    │ Yes
   CYAN         │  3  │ Yes   │ Yes        LIGHTCYAN    │ 11  │ No    │ Yes
   RED          │  4  │ Yes   │ Yes        LIGHTRED     │ 12  │ No    │ Yes
   MAGENTA      │  5  │ Yes   │ Yes        LIGHTMAGENTA │ 13  │ No    │ Yes
   BROWN        │  6  │ Yes   │ Yes        YELLOW       │ 14  │ No    │ Yes
   LIGHTGRAY    │  7  │ Yes   │ Yes        WHITE        │ 15  │ No    │ Yes


   Example:
   Red text on a green background  =  4  +  16  *  2  = 36, so if you wish the
   function key names to be printed in red on green, you would use
   ColKeys = 36



  3.3. EVENTS AND ACTIONS
  -----------------------

  3.3.1 ACTIONS
  -------------

  As has already been noted, the key concept of Unisched is to react on EVENTS
  with ACTIONS.  Before we will examine what  kind  of  events  are  possible,
  we'll first define the actions that Unisched can execute.

  The definition of an action always begins with a $  character,  followed  by
  the name of the action.  The name of the action can be freely chosen by you,
  but may only consist of letters and the underscore.  After this, you type an
  equality  sign  and  then  the  action  description  in  a syntax soon to be
  examined.

  Example:
  $CALL_MY_HUB = POLL 2:2476/404 crash 2

  The action "CALL_MY_HUB" is defined to execute the Unisched built-in command
  "POLL 2:2476/404 crash 2", whatever that means.

  The following section  describes  the  action  syntax  for  all actions that
  Unisched can take, i.E. it describes what you can type  on  the  right  hand
  side of the equality sign in the example above.


     BEEP [<frequency> [<duration>]]
     -------------------------------

     A  simple  beep  is  emitted  by  the  PC  speaker.   You can specify the
     frequency and duration in Hertz resp. milliseconds.  If the paramters are
     omitted, the default is 1000 Hz and 100 ms.

     Areas of application:  Alarm clock, an  hourly  beep like when you have a
     digital wrist watch, ...

     Examples:
     $LONG_AND_LOUND = BEEP 800 4000
     $SHORT_BEEP = BEEP 1000 80

     If you want to make more noise than just a single beep, have  a  look  at
     the  action  "PLAY" in connection with MUS files.



     EXEC <command>
     --------------

     Unisched will execute the external  program / command specified.  EXEC is
     the most simple way to start external programs (as compared  to  OPEN  or
     START),  yet  it  is  important  to understand the way how the command is
     executed:  Unisched passes everything after the EXEC keyword verbatim the
     the command interpreter.   Under  DOS,  this  is  usally COMMAND.COM, and
     under OS/2, it is usally CMD.EXE, but  if  you  have  replaced  those  by
     4DOS/4OS2,  those  will  be used instead.  The result is that you can not
     only execute executable programs (EXE,  COM),  but also batch files (BAT,
     CMD) and even built-in commands of the command  interpreter  (like  COPY,
     DIR, ...).  To repeat it again:

     > Everything behind the EXEC keyword will be executed exactly like if
     > you would have typed it at a DOS prompt / OS/2 prompt.

     Example.:
     $Export_Mail = EXEC e:\box\batch\export.bat

     Unisched  will suspend execution until the command that is being executed
     has finished.  OS/2 users might want to use the START action  instead  in
     some  cases, which is (in contrast to EXEC), able to asynchronously start
     external programs, but  it  is  only  available  in  the  OS/2 version of
     Unisched.

     Users of the DOS version  that  have  it running under a multitasker like
     Windows 95 might consider to EXEC the START command  of  their  operating
     system  ("EXEC  START  test.bat").   In this case, the START command will
     asynchronously start the  program,  and  then  finish,  so  that EXEC can
     return immediately.



     EXIT <errorlevel>
     -----------------

     This action makes Unisched  exit  with  the  given  error level.  This is
     useful if you use a batch file (BAT or CMD) to start Unisched.  The batch
     can take certain actions,  like  executing  programs,  depending  on  the
     errorlevel code that Unisched returns.

     The EXIT action is especially useful for DOS users:  When  you  use  EXIT
     and  the  batch  file to start an external program, it will have the full
     RAM area for itself, whereas if you  would use EXEC to start the external
     program, some parts of Unisched would still remain in  memory  while  the
     external  program  is  running.  Using EXIT and a batch file instead will
     yield as much as 60 KB of additional RAM.

     Example:
     $START_TOSSER_VIA_BATCH = EXIT 80



     IGNORE
     ------

     This  action  simply  does  nothing.   It  might be useful for testing or
     debugging purposes.



     OPEN <OBJECT_ID> and OPEN <PATHNAME>
     ------------------------------------

     This command is only available on OS/2 and only if the Workplace Shell is
     installed  (this  is  the default, but some OS/2 users replace the WPS by
     other shells like Filebar of MSHELL).   The OPEN command is being used to
     Open (start) objects that reside on the Workplace Shell, to open files on
     disk using the workplace shell's file<->program association capabilities,
     or to start external programs using the workplace shell.  The action that
     Unisched performs is the same that would happen if you would double click
     on the icon that is associated with the given object ID, or if you  would
     use  the  Drives  folder  and  double  click  on  the  file  specified by
     <PATHNAME>.

     The <OBJECTID> parameter deserves special attention.  The Workplace Shell
     can assign Object ID's  to  objects  (icons)  that  live on the workplace
     shell, in order to  uniquely  identify  them  and make them accessible to
     software like Unisched.  Some objects have  predefined  Object  IDs,  for
     example  the  drives  folder  has  the  ID  <WP_DRIVES> (yes, the pointed
     brackets  are part of the object ID in this case), and the desktop itself
     has <WP_DESKTOP>.  Icons  that  you  create  by  using  the "New Program"
     template usually do not have an object ID, but you can  use  third  party
     tools  like  Deskman/2  to assign a unique object ID to arbitary icons on
     your desktop.  You can also  write  simple REXX scripts to create program
     icons that have a special object  ID  (for  an  example,  see  below,  or
     consider   the   REXX   documentation,  with  special  attention  to  the
     "SysSetObjectData" routine).

     A useful application of this is to "start icons" with Unisched.   In  the
     default configuration, the WPS will only "start an icon" once, and if you
     try  to  double  click  it  while it is already started, the WPS will not
     start a new instance, but  pop  the  running one in the foreground.  Just
     the same applies if Unisched OPENs icons  using  their  Object  ID.   You
     could create an icon that starts your tosser task and always let Unisched
     open  that  icon  (rather  than  EXECing  or  STARTing  the  tosser batch
     directly).  You can then be  sure  that  never  ever two instances of the
     tosser will run at the same time.

     The following REXX script would create an icon on the desktop  that  runs
     the "tosser.cmd" batch file, and assign the object ID "<MYID_TOSSERTASK>"
     to  it.   Save the following lines as the file "test.cmd" (take care that
     the /* are the very first two characters in the file), and run it:

       /* REXX */
       call RxFuncAdd 'SysCreateObject', 'RexxUtil', 'SysCreateObject'
       n = SysCreateObject("WPProgram",,
                           "Start the Tosser task",,
                           "<WP_DESKTOP>",,
                           "EXENAME=e:\tools\tosser.cmd;"||,
                           "OBJECTID=<MYID_TOSSERTASK>",,
                           "update")
       exit

     You could then use the following Unisched action to start the tosser task:

        $Tosser = OPEN <MYID_TOSSERTASK>

     Instead of an object ID, you can also specify a file  name  as  argument.
     However, this has to be a fully qualified file name, i.E. it must contain
     the drive letter and  an  absolute  path.   What  will  happen if this is
     executed is the same that would happen  if  you  would  open  the  drives
     folder,  locate the file, and do a double click on it, in accordance with
     all association rules  (object  class,  file  extension,  etc.).  If, for
     example, you would like to play an AVI film, just use something like

        $Parrot = OPEN c:\mmos2\movies\macaw.avi



     PLAY <filename.MUS>
     -------------------

     Plays a tune using the internal PC speaker.  The tune is  stored  in  the
     given  MUS  file.   A  file  in  the  MUS  format contains human readable
     commands that have  a  syntax  similar,  but  not  identical, to the BEEP
     action:

        TONE <frequency> <duration_in_hundreths_of_seconds>
        WAIT <duration_in_hundreths_of_seconds>

     The file format is the same file format that is used for sysop page tunes
     by the Proboard BBS software.  You can request an archive  that  contains
     some  example  songs (Startrek themes, e.g.) under the name UAPS10.ARJ at
     my node system (2:2476/418).

     The DOS version  will  play  the  MUS  file  in  the foreground, i.E. all
     operation as suspended until the song is played.  The OS/2  version  will
     play  the  songs  in background, i.E. other things can be done, while the
     song is being played. You can use the action ABORTMUSIC to abort playing.

     Example:
     $ALARM_CLOCK    = PLAY f:\box\pb\Alarm_Clock.MUS
     $I_AM_AWAKE_NOW = ABORTMUSIC



     PLAY <filename.WAV|.MID>
     ------------------------

     This command plays a sound file  in  the  WAV  or MID file format.  It is
     only implemented in the OS/2 version and  will  only  work  if  you  have
     MMPM/2  installed.   The  songs/sounds  will be played in background, but
     cannot be aborted.

     Example:
     $Bigben = PLAY f:\sounds\bigben.wav



     POLL <node> [<flavour>] [COND] [RDC] [LINE<linenr>]
     ---------------------------------------------------

     This action instructs the mailer to poll a node system by creating a .?LO
     flag  in  the  binkley outbound directory structure.  Also, Unisched will
     touch or create  the  mailer  rescan  semaphore  after  the poll has been
     created. The order of the parameters is important.

     <node>:        node number in 3D or 4D
     <flavour>:     The following flavours can be used:  "crash", "immediate",
                    "direct",  "normal",  "hold"  (did  I  say every parameter
                    makes sense?  <g>), "poll".   Please note that "immediate"
                    does not work for BinkleyTerm, and "poll" does  only  work
                    for  McMail  starting  with Gamma 5.  You can also use the
                    flavours "fl0" ..  "fl9".   This  will create flowfiles of
                    the syntax "0lo" ..  "9lo".  The idea is a  draft  by  the
                    Binkley  XE  developers  team for a more detailed priority
                    scheme in the  Binkley  outbound.   Unfortunately, I don't
                    know of any software that uses this,  except for  Unisched
                    ;-).
     COND:          If you specify the  COND  keyword,  the  poll will only be
                    generated you have something on hold for  the  destination
                    node.
     RDC:           The  "RDC" keyword is short for "reset dial counters".  If
                    specified, all dial counters,  busy  marks, and other flag
                    files  for  this  node will be removed before creating the
                    poll.  The  affected  files  have  the  extensions ".$??",
                    ".&??", ".#??" and ".-??".  It is recommended that you use
                    the RDC keyword for at least one poll for  each  node  per
                    day or at least week (otherwise,  your  system  could  not
                    dial  the node for days or even weeks because of a stupide
                    dial counter  mark).   If  you  want  to  specify  the RDC
                    keyword   for   all   polls,   you    could    also    set
                    "ResetDialCounters=Yes"  globally instead of using the RDC
                    keyword for every POLL action.

     LINE<linenr>:  You can give a number as <linenr> argument that  specifies
                    the  line  that  should preferably to the poll.  This line
                    number  is  used  for   filling   the  "%"-macros  in  the
                    RescanSema file name (see above).  If you  have  used  "%"
                    macros  in  the  RescanSema  filename,  you  should always
                    specify a line number  in  your POLL actions.  Please note
                    that because of the fact that Unisched  creates  a  rescan
                    semaphore only for this particular line, it is very likely
                    that  this  line  will  also do the poll, but it cannot be
                    guaranteed, because by  accident,  another line could also
                    do a rescan and do the  poll  before  the  line  that  you
                    intended to use does it.  (The notable exception from this
                    is  the  flavour  "Poll"  which  is specific to McMail.  A
                    McMail "Poll" for  a  specific  line  will  make only this
                    particular line do the poll).

                    You can give more than  one  LINE<linenr>  statement,  but
                    additional  LINE statements will only be used for creating
                    additional line rescan semaphore files.  A McMail Taskpoll
                    (flavour:  "poll") will only be created for the first line
                    given.  The highest line number that you can use is 32.

     Examples:
     $POLL_Hub = Poll 2:2476/998 crash rdc line2 line 3
       Polls 2:2476/998 using the "crash"  flavour.   Lines 2 and 3 are forced
       to do an outbound rescan.  Dial counters and busy marks will  be  reset
       before the poll is created.
     $Call_System_Conditional = Poll 2:2476/999 immediate cond line1
       Only  if anything is on hold for 2:2476/999 (for example a file request
       with direct flavour), create an immediate  poll  and have line #1 do an
       outbound rescan.


     REFLAVOUR <node> [<oldflavour>] [<newflavour>] [RDC] [COND] [LINE<line#>]
     -------------------------------------------------------------------------

     The  REFLAVOUR  action  changes  everything that is on hold for the given
     node with flavour <oldflavour> to the new flavour <newflavour>.

     <node>:        node number in 3D or 4D
     <oldflavour>:  You can use all flavours that can be used with the POLL
     <newflavour>:  action (see there).
     [RDC] [LINE#]: Same meaning as for the POLL action.
     [COND]:        This meaning differs slightly from the meaning of the COND
                    flag for the  POLL  action.   If  COND  is  specified  for
                    REFLAVOUR,  the  reflavour  action  will  only  be done if
                    already any mail ->  with  <newflavour>  <- is on hold for
                    the destination system.

     Please note that  the  present  version  of  Unisched  can only reflavour
     UNPACKED mail (?UT packets) if no other unpacked mail with the given  new
     flavour  does  already  exist.  This is so because Unisched cannnot merge
     two PKT files into one.  (Unisched  will  not lose any mail in this case,
     it will simply refuse to do the reflavour).

     For  Arcmail and file attaches (?LO-files) this is not a problem, because
     they can easily be appended.   Unisched  will even change hold arcmail to
     crash if already other crash mail is on hold for the system, for example.

     There are two areas of application for the REFLAVOUR action.   The  first
     one  is  to  "undo"  polls.   For  example,  in Germany the Telecom has a
     special tariff which is extremely cheap in the area from 2 to 5 a.m.  You
     could create a poll  with  flavour  crash  for  an uplink in a heavy-load
     filenet  at  2 a.m., and you could then use REFLAVOUR to change all crash
     flags and mail attaches back to normal  at  5 a.m., for the case that you
     could not reach your uplink in this night:

     $POLL_GFDnet   = POLL 2:2476/999 crash
     $UNPOLL_GFDnet = REFLAVOUR 2:2476/999 crash normal
     #001 02:00 04:59    = $POLL_GFDnet
     #002 05:00 01:59    = $UNPOLL_GFDnet

     (The  last  two  lines will be explained later when events are explained.
     Don't worry about them for now).

     Another application is something that should be known to former Frontdoor
     sysops as "Unholding".  Imagine you would  want  to  deliver  high-volume
     bulk traffic (like filenets etc.) to an uplink.  You only want to deliver
     these  packets during the cheapest tariff (in Germany, from 2 to 5 a.m.).
     However, you also want to call  this uplink at other times for delivering
     crashmail or other things, but you don't want the filenet traffic  to  be
     sent  at  this  time.  What you have to do is to configure your ticker to
     create the filenet attaches as attaches with flavour "hold", so that they
     will normally not  be  sent  when  you  call  your  uplink at day tariff.
     However, when the cheap tariff timeslot starts, you need a way to  change
     the  flavour  of  these attaches from "hold" to another flavour (at least
     "normal", but if you want  to  make  them  cause  your mailer to dial the
     uplink probably to "crash").  Unisched can do it for you:

     $SEND_BULK_TRAFFIC_TO_2469999 = REFLAVOUR 2:246/9999 hold crash



     REMOVE <filename>
     -----------------

     The file designated by <filename>.   For  examples  when  this  might  be
     useful,  refer  to  the  SEMAPHORE  command  (see  below).   You  can use
     wildcards (since Unisched 1.0wb07).  If the  path is not an absolute one,
     it  is  assumed  to  be relative to the semaphore directory (refer to the
     SemaDir command, see above).



     REQUEST <filename> [!<password>] <nodenumber> [<flavour>] [LINE<line#>]
     -----------------------------------------------------------------------

     The given file will be requested (Fidonet File Request) at the given node
     by creating a .REQ file in  the  Binkley  Outbound.  Also, a poll for the
     given node will be created in order for the filerequest to be sent.

     <filename>   The name of the file or magic to be requested.
     !<password>  If the remote  system  requires  a  password  for  the  file
                  request  (this  means  a  special  request  password, it has
                  nothing to do with the  session  password), you can write it
                  after an exclamation mark.
     <nodenumber> Same as for the POLL action.
     <flavour>    "
     LINE<line#>  "

     Examples:
     $Request_Private_Filelist = REQUEST PVTFILES !SECRET 9:99/999 crash 2
     $Request_BLAND_Files = REQUEST ALLFILES 2:2476/418 crash 1



     RESTART
     -------

     Unisched will be re-initialised.  Among  other  things,  the  Config-File
     will be re-read. There are no parameters.

     Example
     $RESTART_UNISCHED = RESTART



     SEMAPHORE <filename> ["contents"]
     REMOVE <filename>
     -------------------------------

     The SEMAPHORE action  creates  a  semaphore  file  named <filename>.  The
     semaphore file has zero length.  The normal application  of  a  semaphore
     file  is to give signals to other programs about certain conditions.  For
     example, you can create semaphore  files  that make your Mailer exit, put
     it into suspend mode, and  other  things.   Correspondingly,  the  REMOVE
     action  removes  a  (semaphore)  file.   Attention:  Of course the REMOVE
     action is also capable of deleting  files that have more than zero length
     ;-).  If filenames do not contain path specifiers, the files are  assumed
     to reside in the semaphore directory (see SemaDir, above).

     For  example,  you  could use the SEMAPHORE action in order to create the
     file BTFREEZE.01, which makes Binkley  (task  1) go into suspend mode, so
     that you can shorten its  logfiles,  recompile  the  nodelist,  or  other
     things,  and  after  these tasks are done, you could use REMOVE to remove
     the BTFROZEN.01 file in order to make Binkley wake up again.

     (Hint:  Sometimes, it is of course  easier  to  do this from a batch file
     that  does  the  job  of  shortening  logfiles  or  similar,   by   using
     ECHO>BTFREEZE.01 and DEL BTFROZEN.01)

     Examples:
     $Freeze_BT1 = SEMAPHORE BTFREEZE.01
     $Unfreeze_BT1 = REMOVE e:\mailer\bt\flags\BTFROZEN.02

     Optionally, the action SEMAPHORE can  also  create files that do not have
     zero length, but a specific content.  If you want this, give the  desired
     contents  as  a  string  enclosed  in  double  quotes as parameter to the
     SEMAPHORE action.  Within the string, you can use \n to start a new line,
     \" to use a double quote as verbatim character, and \\ to use a backslash
     as verbatim character.  An  area  of  application  for this feature is to
     create an exit semaphore for the Xenia mailer.  Xenia  expects  the  exit
     semaphore file to contain the errorlevel code for exiting:

     $FinishTask1WithErrorCode99 = SEMAPHORE xmexit.1 "99"



     SEND <filename> <nodenumber> [<flavour>] [kfs | tfs] [LINE<line#>]
     ------------------------------------------------------------------

     The given file is sent to the  given system as file attach with the given
     flavour.  The parameters are identical to those  of  the  REQUEST  action
     (excpet that no password can be given).  Additional parameters are:

     kfs:  This keyword is short for "kill file when sent":  If  you  use  it,
           Unisched will instruct your mailer software to delete the file when
           it has been sent successfully.
     tfs:  This keyword is short for "truncate file when sent":  The file will
           be truncated to zero length after it has been sent sucessfully.

     Example:
     $Send_Hubdiff = SEND 24760900.UPD 2:2476/1 crash line2



    START ["<title>"] [/option ...] <program> <parameter> ...
    ---------------------------------------------------------

    This action is only available under OS/2.  It is  used  to  asynchronously
    start  child  processes in the background, i.E. Unisched will remain fully
    operable while the background process  is  executing (in contrast to EXEC,
    where Unisched is blocked until the child process terminates).

    Besides  that,  there  is another difference between EXEC and START:  EXEC
    simply passes any arguments it gets  to  the command processor, so you can
    EXEC anything from batch files over built-in commands to real executables.
    START, to the contrary, tries to directly execute the program, so you  can
    only  execute  .EXE  executables,  unless  you set special parameters that
    cause invokation of the  command  processor  (see below).  Also, EXEC will
    nearly always work on  anything  that  is  half  executable,  while  START
    sometimes will require special arguments to be able to correctly guess the
    session type to be started.

    The  arguments  to  the START action are nearly the same as the OS/2 START
    command that you can use at an  OS/2 prompt.  Type "help start" to receive
    information on this.  Nonetheless, you should  understand  the  difference
    between  START and EXEC START.  The START action is built in into Unisched
    and although it arguments resemble those of the OS/2 START command, it has
    nothing to do with that.  EXEC START, on the other hand, tells Unisched to
    invoke the EXEC action on the  OS/2  START command, i.E. Unisched starts a
    command processor and tells it to execute the START  command.   The  final
    result  of  START  and  EXEC START are more or less the same, but START is
    faster.

    Here is a quick summary on the possible arguments for the START action.

    "<title>"  A title to be used in the  window list and for the title bar of
               the window (if applicable).

    <program> <parameters ...>
               The name of the program, batch command or script that should be
               executed.

    In the  following  you  find  possible  options  for  the  start  command.
    Multiple  options  can  follow  each  other  directly  (/F/WIN,  e.g.)  or
    separated  by  a  whitespace character (/F /WIN, e.g.).  You should always
    completely specify the desired  options,  because  the default settings of
    the  options  strongly  depend  on  other  settings,  which  is  a  little
    confusing.

      - Session type: Set one of the following options:

        /FS         OS/2 fullscreen session
        /WIN        OS/2 windowed session
        /PM         OS/2 PM, graphical application
        /DOS/WIN    DOS windowed session
        /DOS/FS     DOS full screen session

      -  Foreground  or background:  One of the follwing options should be set
         to specify if the program window  should  pop up in the foreground or
         if the program should be started hidden in the background.

        /F          Start in the foreground.
        /B          Start in the background.

      - Window size. The following options are optional:

        /MAX        Start the window maximized.
        /MIN        Start the window minimized (hidden or iconified).

      - How to  start  the  program.   You  should  set  exactly  one of these
        options, with one notable exception:  If you use the /DOS option, none
        of these options can be used.

        /N          Start the program directly.  The session  will  be  closed
                    when  the program terminates.  Use this parameter to start
                    .EXE files.
        /C          Start the program via the command processor.  You must use
                    this option if you  want  to  start build-in commands (dir
                    etc.) or .CMD files (batch or REXX scripts), because these
                    need the shell (CMD.EXE or 4OS2.EXE) to be executed.   The
                    session   will   be  closed  when  the  program  /  script
                    terminates.
        /K          Works similar to the /C  option,  but the session will NOT
                    be closed when the proram or command has terminated.

      - Environment options. This parameter is optional.

        /I          Normally the program will "see" all environment  variables
                    that  are  known  to  Unisched (i.E. that were active when
                    Unisched has been  started).   If  you  use the /I option,
                    however, The programm  will  only  see  those  environment
                    variables  that  would  also be visiable to a "fresh" OS/2
                    window.

     Examples:

     $Tosser    = START "Tosser Task" /WIN/MIN/B/C e:\tools\toss.cmd
       ;The tosser task will be started as a minimized OS/2 window in the
       ;background. Because the tosser task is implemented as a batch file,
       ;we need the /C option to start it.

     $Fileindex = START /DOS /FS /B  e:\proboard\pbutil.exe fi
       ;A DOS program will be started as a full screen session. In order to
       ;prevent  the  system  from  switching  to  full  screen  mode,  the /B
       ;parameter is used.

     $Edit_Config_File = START /PM/F/N c:\os2\e.exe e:\usched\unisched.cfg
       ;This is a possible way for editing the config file of Unisched
       ;"on the fly". Later, in the chapter about trigger files, we will
       ;see how you can Unisched make to automatically re-read the config
       ;file after you have saved the changes.

     There is one thing, though, that you should always remember when starting
     sessions  asynchronously  with  the  START  action:   These  sessions run
     completely independent of the Unisched main task, so it is possible  that
     Unisched  will  start  multiple sessions in short sequence that then will
     run, at least partially, parallel to each other.  This sometimes can have
     undesired side effects, for example two tossers that run parallel to each
     other could damage  your  message  base,  unless  the  tosser has special
     mechanisms built in to prevent this, or a huge number of tossers  running
     parallel  could  eat  up  all  system  ressources.  If you do not want to
     provide for this case (by  using  special  lock  files in the batch files
     that  you  call,  or  by  using  the online tossing feature which will be
     described later), it might be  better  if  you  just use the EXEC or OPEN
     actions for such critical tasks.



  3.3.2 Recursions
  ----------------

  You  can  define  combined actions, i.E. action names that execute more than
  one of  the  actions  mentioned  above,  by  using  recursions,  i.E. action
  definitions that refer to other action definitions.

  Example:

  $poll_tobias = POLL 2:2476/418 crash
  $unhold_mail_for_tobias = REFLAVOUR 2:2476/418 hold normal
  $call_tobias = $unhold_mail_for_tobias $poll_tobias

  The  order  of  the definitions in the config file is arbitrary, and forward
  references are allowed, i.E.  you  could  also  write  the  last line in the
  example above before the other two lines.



  3.3.3 EVENTS
  ------------

  By now, you have learned what Unisched  can do, and how you create so called
  ACTIONS, i.E. symbolic names for actions that Unisched should perform.  Now,
  it is time to learn how to tell Unisched WHEN to perform these actions.

  In  general,  an  EVENT  contains information on a) a condition that must be
  true to perform a particular action, and b) a reference to the symbolic name
  of a previously defined ACTION.

  Unisched supports four type of EVENTS:  Semaphore files, static time events,
  periodic time events, and function keys.  We start to explain the last kind,
  because it is the easiest one.


     Function Key Events
     -------------------

     Syntax: Key<key> = $<action name> [$<action name> ...]

     This is the easiest kind of event:  You can assign a function key  to  an
     action,  and  if this function key is pressed when the Unisched window is
     active, the given action will  be  executed.   It  can be useful that you
     assign a function key to every major action that you intend  to  use  for
     Unisched,  so  that  for  debugging  purposes, you can always trigger any
     action manually.  For example, you  will  want to assign function keys to
     all poll actions, so that you can poll the respective uplink of yours any
     time by simply pressing the according function key.

     The following function keys are recognised by Unisched:

     KeyF1 .. KeyF10
     KeySF1 .. KeySF10 (SF means Shift+Function Key)
     KeyAltA .. KeyAltZ (Exception: Alt+X, which is hardcoded to exit Unisched)
     KeyAlt0 .. KeyAlt9
     KeyS0 .. KeyS9 (Shift + 0 .. Shift + 9)
     Key0 .. Key9
     KeyESC

     Examples:
     KeyF3 = $Call_My_Uplink
     KeyAltI = $Import_Mail $Play_WAV_File



     Semaphore Files
     ---------------

     Semaphore File Events are used to trigger Unisched actions whenever there
     occur  certain changes on a file system, like the creation of a new file,
     the deletion of a existing file, and similar.  A semaphore file is a file
     that usually does not  have  any  meaningful  contents, but simply by its
     existing it acts as a signal for a certain condition.  Unisched  somewhat
     extends  this  concept,  as  it  can  also  react to files that do have a
     meaningful content.  This will  be  explained  soon.   --- The concept of
     semaphore files is widespread in Fidonet technology.  FTN mailer software
     often is able to create a semaphore file when it has received  new  mail,
     and  it  often  is  also  possible  to  be  controlled by the creation or
     deletion of semaphore files, like exit sempahores, rescan semaphores, and
     others.

     Unisched supports two  main  types  of  semaphore  files:  so called FLAG
     FILES (this is what you might already know under the  term  "semaphore"),
     and  TRIGGER  FILES (these are files that signal some sort of action, but
     may not simply be deleted).  This is now explained in detail.


       Flag Files ("normal semaphores")
       --------------------------------

       Syntax: *<filename> = $<action name> [$<action name> ... ]

       As soon as Unisched sees the file designated  by  <filename>,  it  will
       delete  the  file and execute the given action.  This is the concept of
       flag files:  They  do  not  have  meaningful  content,  so  they may be
       deleted as soon as the condition that they signal has been  taken  care
       of.  - If <filename> does not contain a drive letter and path name, the
       file is searched in the directory specified by the SemaDir keyword (see
       above).

       Example:
       *e:\bt\flags\sema\btmail.in = $import_mail

       The main application of the flag file function is to let Unisched start
       your tosser program or batch as  soon  as the mailer has received mail.
       In order to achieve this, you have to tell your mailer to create a flag
       file as soon as any sort of  mail  has  been  received.   In  order  to
       achieve  this,  you  have  to  consult  the manual of your mailer.  For
       McMail and Binkley  XE  (but  only  XE!),  the corresponding keyword is
       "MailFlag", and additionally, you have to set the error level for  mail
       exits  to  zero  (McM),  or to completely remove the entry for the mail
       exit level from the event file (Binkley XE).  Binkley XE always creates
       a file called BTMAIL.IN, while McMail  allows to freely define the file
       name.

       If you use some other mailer and it does not support creation of a flag
       file when mail has been received, you can fake the functionality in the
       mailer batch:  Every mailer I know can exit with a defined error  level
       when  mail  has  been received.  In the mailer batch, you can then test
       for this error level, and use ECHO  > BTMAIL.IN or a similar command to
       create the mail flag file manually.



       Trigger Files
       -------------

       Syntax: ^<filename> = $<action name> [$<action name> ... ]

       The  difference  between  trigger  files  (denoted by ^) and flag files
       (denoted by *) is that  trigger  files  will NOT be deleted by Unisched
       when it executes the corresponding action.  If you use  trigger  files,
       the action has to take care that the file is deleted or moved elsewhere
       by  itself.

       An example where this is useful:  You use a time controlled event (this
       will be explained below) to request a list of f'reqable  files  from  a
       certain  system  every  month.  As soon as your mailer has received the
       file list (which always has the same name), you want Unisched to call a
       batch file that moves the  file  list  into  a directory of its own and
       unzip the file list:

       ^e:\mailer\inbound\24760999.zip = $unzip_the_filelist_of_2476_999

       The  action  that  is  started  does not need to immediately delete the
       file, it is allowed to use  as  much  time as it wants until it finally
       deletes the file or moves it elsewhere.  Unisched is not brain dead and
       will NEVER call an action twice  for  the  SAME  trigger  file.   After
       Unisched  has  started  an  action for a trigger file, it will remember
       that particular file and will not  start  the action again until it has
       seen that file vanish and reappear, or at least change its file  length
       or time stamp.  While this is an advantage, it of course means that you
       have  to  make  sure  that  the batch file called by the action, or the
       action  itself  finally  deletes the file or moves it away, or else the
       corresponding action will  never  be  executed  again,  not even if you
       manually stop and restart Unisched.

       Unisched will also not react on a trigger file as long as it  cannot be
       opened exclusively (i.E. for exclusive writing).  The logic behind this
       is  that most modern FTN mailer software places an exclusive lock while
       it is receiving a file.  Of course  you do not want the action to unzip
       the file list from the example above to be executed before the file has
       been fully received by the mailer.  This is  assured  because  Unisched
       cannot open the file exclusively while the mailer is still holding  its
       exclusive  lock  on  the  file.   Unisched will only trigger the action
       after the filelist has been fully received.

       Another thing that has to  be  taken  special  care  of is the usage of
       wildcards in the definition of trigger files.  Unisched  supports  this
       and handles it as follows:  All files that match on the given wild card
       will  be  treated  as  a single unit.  This means:  If any file appears
       that matches on the given  wildcard  pattern, Unisched will perform the
       corresponding action.  After that, it will not react to ANY other  file
       that  might  match  the  given pattern until exactly that file that has
       triggered the action  has  vanished  or  at  least  changed its size or
       timestamp.

       To sum it up, in most cases, the action that is executed when a trigger
       file is  detected  should  take  care  to  delete  or  move  away  this
       particular  file.  It is a must if you use wildcards, but normally also
       needed if you do  not  wildcards.   There  are  some exceptions to this
       rule, however.  For example,  you  could  define  the  config  file  of
       Unisched  (usually  Unisched.Cfg)  itself   as  a  trigger  file.   The
       assosciated action just tells  Unisched  to  reread  the  config  file.
       Unisched  will  then  always  reread  the  config  file  whenever it is
       modified, because when it is modified,  it changes its file time stamp,
       and this suffices for Unisched as a criterium to restart the associated
       action.  If you do it this way, you can simply  edit  the  config  file
       with  an  external  editor,  and  Unisched will detect when it has been
       modified and reread it automatically:

           $Reread_Config_File = RESTART
           ^e:\usched\unisched.cfg = $Reread_Config_File



       inverted flag files ("inverted normal semaphores")
       --------------------------------------------------

       Syntax: !*<filename> = $<action name> [$<action name> ... ]

       This sort of event definition  is  the  exact inversion of a flag file.
       (We remeber:  A flag file is deleted by Unisched  when  it  starts  the
       corresponding action).  With an inverted flag file, Unisched will start
       the  corresponding action as soon as the given file does not exist (any
       more).  Unisched recreates the file  (with zero length) before starting
       the action.

       A possible area of application for  this  feature  is  to  use  another
       software  to  test  if  Unisched  is  running  or not.  (Other types of
       software, e.g.  Mailers, know  this  concept  as an "alive semaphore").
       Example:

       !*e:\flags\unisched.alv = IGNORE

       Unisched will do nothing (the IGNORE command) in terms of actions  when
       the  file  unisched.alv vanishes, but it will recreate the file.  Other
       software can check if  Unisched  is  running  by  deleting the file and
       waiting for some time (approx 30 seconds should suffice unless you have
       changed the defaults) to see if it reapperas.  If it doesn't,  Unisched
       is not running.

         (A note to the more experienced readership:  You might ask yourselves
         why we did not have to write something like

         $Do_Nothing = IGNORE
         !*e:\flags\unisched.alv = $Do_Nothing

         Instead, we simply wrote the IGNORE command directly after the  equal
         sign.   You  have  just  discovered  that  the assignment of symbolic
         action names starting with a $  sign  is  in fact nothing more than a
         macro facility.  You could always write Unisched action commands like
         IGNORE, POLL,  EXEC  etc.  directly  after  the  "="  sign  in  event
         definitions.   Using  symbolic  names,  however, often gives a better
         structure in the config  file  and  also  often saves you from typing
         things twice, e.g. when the action to poll a certain person should be
         accessible both for time-controlled events  and  from  the  keyboard.
         There  is  also one situation when you must use symbolic names.  This
         is the case when  you  want  to  combine  two  actions into one.  You
         cannot write two action commands in sequence unless you use  symbolic
         names.    E.g.   "IGNORE  IGNORE"  is  not  valid,  but  "$Do_Nothing
         $Do_Nothing" is.)

       But to come back on topic:



       inverted trigger files
       ----------------------

       Syntax: !^<filename> = $<action name> [$<action name> ... ]

       Unisched will act as follows:  The  given action(s) will be executed if
       (as soon as) the given file does not exist.   After  that,  the  action
       will  not  be executed as long as the file keeps absent.  Unisched will
       register if the file reappears,  and  from  that time on, Unisched will
       again be prepared to start the corresponding action as soon as the file
       disappears.

       With inverted trigger files, wild cards CANNOT BE USED.


       Summary on Semaphores
       ---------------------

       Kind of semaphore  Marker  Action
       flag file          *       Unisched deletes the file
       trigger file       ^       Action has to delete the file
       inv. flag file     !*      Unisched creates the file
       inv. trigger file  !*      Action / external event must create the file



     Static Time Controlled Events
     -----------------------------

     Static  events are what you would at first place expect from a scheduler.
     (The terminus "static" is used to give a distinction between this kind of
     events and "periodical" events that will be explained later).  Quite some
     other scheduler software or built-in schedulers of  FTN  mailer  software
     have functions that resemble Unisched static events.  However, Unisched's
     conecpt  on how to handle those events, especially in case of overlapping
     events, is different and more intelligent in comparison to the concept of
     common FTN mailer schedulers.  So read on to learn how it works.

     Syntax:
     #<nr> <from> <to> [<weekday>] [<fromdate> <todate>] [even|odd] = $<action>

     <nr>:      This is the number of the event in the range from  0  to  999.
                Every  time controlled event must have a unique number.  It is
                used by Unisched to identify  the  event, so that Unisched can
                keep track of various information pertaining  to  this  event.
                The  event numbers need not be in sequence, or sorted (a event
                that you define at the bottom of the config file is allowed to
                have a lower number than  an  event  that is definied near the
                top) --- the only thing that you must ABSOLUTELY take care  of
                is that you never assign one number twice to different events.
                Unisched  cannot  detect  this  situation, but will do strange
                things if you do it.  EVENT NUMBERS MUST BE UNIQUE AND <= 999.

                If you change anything  on  your  config  file, you should not
                change the numbers of events  that  did  not  change,  because
                everytime  that  you  change  the number of an event, Unisched
                will loose all information that it has kept on the event.  For
                instance, if the action of  an event has already been executed
                and you change the event number, the action will  be  executed
                again.

     <from>,
     <to>:      This is the start and end time of the event.  It is one of the
                main points where Unisched's  behaviour is different from that
                of common FTN mailer schedulers.  Unisched will make sure that
                the action that is associated with this event will be executed
                as soon as possible, but EXACTLY ONCE within  the  given  time
                span.   You  can  quit and restart Unisched, and Unisched will
                still not execute the event another time.

                The consequence from this  is  that  you can usually use LARGE
                time spans when defining static events.  For example,  if  you
                define an event to poll your uplink at 05:00, it does not make
                sense  to  let  the  event end at 05:01.  If, for some reason,
                Unisched is not active  in  the  time between 04:59 and 05:02,
                the event would not be executed, and this is probably not what
                you want.  You want that if Unisched becomes active  again  at
                05:03,  the  uplink  should be polled anyway.  Even if it only
                becomes active at 06:00, the  uplink should be polled.  But if
                it only becomes active at 07:30,  the  uplink  should  not  be
                polled, because at 08:00, there is already the next event when
                the  uplink should be polled.  For example ;-).  In this case,
                you should take the time span to last from 05:00 until 07:00.

                A time span from 05:00  to  07:00  would  mean  that  Unisched
                normally starts the associated action at 05:00, but if for any
                reason, Unisched cannot do it at 05:00 (for example because it
                has EXECed a tosser batch  at  04:50  that took longer than 10
                minutes), it will catch up for this event as soon as possible,
                but it will not do it after 07:00.

                Another time for those of you that only read bold letters:

                DEFINING EVENTS THAT ONLY LAST  ONE  OR JUST A FEW MINUTE DOES
                NORMALLY DOES NOT MAKE ANY SENSE.  IT USUALLY IS BETTER TO USE
                A LARGER TIMESPAN (THAT LASTS  SEVERAL  HOURS  OR  EVEN  UNTIL
                24:00), SO THAT THE EVENT CAN BE CAUGHT UP FOR IF NECESSARY.

                Another important thing to note  if  you have been used to use
                built-in shedulers of typical FTN mailers:

                THE TIME SPANS OF SEVERAL EVENTS MAY  OVERLAP.   UNISCHED  CAN
                HANDLE THIS PERFECTLY WELL.

                In order to keep  track  of  which  event actions have already
                been executed  and  which  haven't,  Unisched  uses  the  file
                UNISCHED.DAY.   It  is  not  a  good idea to delete this file!
                (Exception:  If you have  the  impression that Unisched is not
                at all doing what you have configured, it might  be  the  case
                that  the DAY-file contains wrong information or is broken, so
                you might try to  delete  it).   If  you  delete the DAY file,
                Unisched will think that no event actions have  been  executed
                at  all  this  day,  and will consequently catch up for all of
                them.

                Also  note  that the time span may overlap the 24:00 boundary,
                Unisched can handle this perfectly well.

     <weekday>: By default  an event is  valid  for every day of the week.  If
                you want an event to be used only on certain  week  days,  you
                can  place  the abbreviations of the desired week days here in
                English  (Mo Tu We Th Fr Sa Su are valid abbreviations)  or in
                German (Mo Di Mi Do Fr Sa So).  You can also use  the  special
                keyword  "Week"  which defines the days Mo ..  Fr, and "WkEnd"
                which is a synonym for  "Sa  Su".  If events overlap the 24:00
                boundary, the week day of the *new* day is used, not  that  of
                the old one!

     <fromdate>,
     <todate>:  You can use these options  to  specify that events should only
                be valid on certain days of a  month  or  in  a  certain  date
                range.   You can give the dates as day numbers, as combination
                of day and month, or  as  a fully specified date consisting of
                day, month and year.  German notation is used, i.E.  you  must
                specify   the  day  number  BEFORE  the  month  number!   Some
                examples:

                01. 01.       ; every 1st day of each month
                24. 31.       ; every 24st, 25st, .., 31st day of each month
                20. 05.       ; every 20st, .., 31st, 1st, .., 05th day of
                              ; each month.
                21.06. 22.09. ; do it on every summer day each year, i.E. from
                              ; June 21st until September 22nd.
                24.12. 06.01. ; only during christmas holidays
                01.01.2000 01.01.2000 ; only on the exact date of Jan 1st 2000

                As you can see from the examples, you always have to specify a
                complete date range (not just a single  datum)  with  a  start
                and  end  date.  If you want an event to be executed only at a
                single day, the start and end  day  are the same date (like in
                the examples above, 01. 01. or 01.01.2000 01.01.2000).

     even, odd: If you specify either  the  "even"  or  the "odd" keyword, the
                event will only be active if the current week number  (in  the
                range  from  1 to 52) is even (resp. odd).  You could use this
                feature to execute an event in  a 14 day period (for this, you
                of course must also specify  a  certain  week  day,  like  "Su
                even").

     <action>:  The action or name of the action.

     Examples:
     #010 00:00 24:00 01. 01.       = $Post_Statistics
     #020 00:00 04:00               = $Export_Mail
     #030 04:05 04:55 Mo We Fr      = $Poll_Uplink_1
     #040 04:10 04:55               = $Poll_Uplink_2
     #050 12:00 13:00 Mo even       = $Post_some_sort_of_information_mail
     #060 08:00 24:00 01.06. 22.06. = $Tobias_will_soon_have_his_birthday



     Periodic Events
     ---------------

     Periodic events are another  flavour  of  time  controlled events thas is
     used to have  certain  actions  be  executed  in  fixed  intervals.   For
     example,  you could execute a batch file or REXX script every 15 minutes,
     which checks if all mailers are  still  active (and does actions that try
     to fix this if not).  Another area of application is to have  the  system
     export  newly  written  mail  every xx minutes, or if you live in an area
     where local phone calls are for free, to generate automated polls to your
     Uplink every xx minutes.

     Syntax:
      #<nr> ~<min> [+<sync> | -<sync>] [exact] [<from> <to>] [<weekday[s]>]
                          [<fromdate> <todate>] = $<action[s]>

     <nr>:     Like  above,  a number in the range of 1 to 999 that identifies
               the event and must be unique.

     <min>:    The length  of  the  interval  between  execution  of the event
               action in minutes.

     <+sync>:
     <-sync>:  These  options  specify  synchronisation  offsets  in  minutes.
               Explanation:  Normally, periodical events will be  synchronised
               relative  to  0:00  (midnight).  This means that the times when
               the event is targeted for execution  are 0:00h + n * <length of
               interval>.  An event with a  period  of  60  minutes  would  be
               executed    at   0:00h,   1:00h,   ...,   23:00h.    By   using
               synchronisation offsets, you can shift the synchronisation time
               by some minutes into the future  or into the past.  If you have
               an  event  with  a  period  of  60  minutes  and   specify   an
               synchronisation offset of "+10", the  event will be executed at
               0:10h, 1:10h, ..., 23:10h.

               It is definitely  a  good  idea  to use synchronisation offsets
               especially if you have more than one periodic event  (by  using
               different  synchronisation  offsets,  they will be scheduled at
               different times,  so  that  the  stress  on  your  computer  is
               distributed better), or if you  use periodic events to generate
               polls (if  an  uplink  had  multiple  downlinks  that  all  use
               periodic events without synchronisation offsets, they would all
               try to poll him at the same time ...).

     exact:    Normally, Unisched catches up  for  the execution of a periodic
               event, i.E. it will do it later if it couldn't start it exactly
               at the scheduled time because Unisched was  down  or  otherwise
               busy.   This  makes  sense for most areas of applications.  For
               example, for a  mail  export  event,  it  is  not relevant when
               EXACTLY it is executed, only that it IS executed at least  once
               every xx minutes.  There are exceptions, however.  For example,
               if  you use periodic events to play a sound every 60 minutes at
               the full hour, you do  NOT  want  that  it is played at a later
               time.  Unisched should either play it, or if nothing helps, not
               play it, but it should not play  it  at  a  later  time.   This
               behaviour can be  enforced  by  specifying the "exact" keyword.
               If  present, Unisched will not catch up for a periodic event if
               it could not be executed at the exact scheduled time.

     The other parameters have the  same  syntax as for static time controlled
     events, but some of them  have  a slightly different meaning.  The <from>
     and <to> options specify a time span within which the periodic  event  is
     ALLOWED  to  be  executed.  In contrast to static events, periodic events
     could be executed  multiple  times  during  this  time span, depending on
     their period.  Also read the  explaination  for  the  examples  below  to
     understand this:

     Example:
     #510 ~60 -10 = $Export_Mail
     ;The $Export_Mail action is being executed every hour at minute 10, i.E.
     ;at 00:10, 01:10, ...  If Unisched is  busy at this time, the action will
     ;be executed at a later time, as soon as possible.

     #520 ~60 exact 08:00 20:00 Week Sa = $coocoo
     ;The $coocoo action (which plays a sound  at  every  new  hour)  will  be
     ;executed at every new hour. If Unisched can't play it at that exact time
     ;it will be skipped.  The $coocoo action will never be executed at a time
     ;that does not have minute 0. Also, the $coocoo action will only be done
     ;in the time from 08:00 to (and including) 20:00,  because during the
     ;night, we do not want to hear these sounds.

     #530 ~60 +30 exact 08:00 20:00 Week Sa = $half_hour_gong
     ;Like the previous example, but this action will ONLY be played at half
     ;hours, but not at full ones.

     Let  us  further  examine  how  exactly  periodic  events  are treated by
     Unisched.  To begin with, Unisched  synchronises a newly defined event to
     midnight (0:00 h) - or to a different time,  if  synchronisation  offsets
     have  been  used  (see above).  After that, it will schedule events to be
     executed each after the given period.   So if, for example, you define an
     event with a period of 15 minutes, this event will be scheduled at 0:00h,
     0:15h, 0:30h, 0:45h, 1:00h, and so on.

     If  Unisched  cannot  execute any of these events at the time when it has
     been scheduled, Unisched will execute them  as soon as possible, but only
     as long as the next instance of this event is not already  due.   In  our
     example,  if  Unisched  is busy between 0:14h and 0:25h with other tasks,
     the periodic event  action  would  be  executed  at  0:00h, 0:25h, 0:30h,
     0:45h, and so forth.  If Unisched would have been busy between 0:14h  and
     0:35h,  one instance of the event would be omitted, i.E. the action would
     be executed at 0:00h, 0:35h,  0:45h,  and  so on.  This behaviour ensures
     that there will never be an "event  congestion",  which  could  otherwise
     happen  if  for  example  you define a periodic event to be scheduled all
     five minutes, while the event action actually lasts 15 minutes ...

     If you don't want Unisched to  catch  up for periodic events at all, i.E.
     if the associated action of an periodic event should only be executed  at
     the  exact minute for which it originally has been sheduled, you must use
     the keyword "exact" in the  event  definition.   If you define an "exact"
     event with a period of 15 minutes and Unisched is busy between 0:14h  and
     0:20h,  the event would only be executed at 0:00h and 0:30h (and at later
     times, of course).  The only application where "exact" makes sense that I
     can imagine is if Unisched schould  play  a  sound at every full hour, or
     things like this.  In all other areas, it is better not to use "exact".

     The <from>, <to>, <weekdays>, <fromday> etc.  parameters  define  a  time
     frame  within which the event principally is ALLOWED to be executed.  (If
     omitted, the time frame is 0h to 24h).  They do not  at  all  change  the
     principal  mechanism  how synchronisation works as it is described above.
     I.E. Unisched schedules all  event  instances  for their proper execution
     time according to the event's period.  Only right before the event action
     is to be executed, Unisched tests if  the  current  time  is  within  the
     specified  time  frame,  upon  which  it  bases  its  decision whether to
     actually execute the event action or not.

     Here is an example for time frames:

     #123 ~15 14:50 17:25 = $Do_Something

     The action $Do_Something will be  executed  at  15:00h, and then every 15
     minutes.  Let us assume that Unisched  is busy with some other event from
     15:10 until 15:20.  The event will then  be  executed  at  15:20,  15:30,
     15:45.   You  see  that  the  scheduled execution time of 15:15 had to be
     postponed to 15:20 because Unisched was busy at 15:15.  Now let us assume
     that Unisched is busy from 15:50 until  16:47 (not that it is likely that
     Unisched is busy as long, but only  for  demonstration  purposes:).   The
     next  execution  of  the  event action will then be on 16:47, followed by
     17:00 and 17:15.  The scheduled execution times of 16:00, 16:15 and 16:30
     were omitted and 16:45 was postponed to 16:47 because Unisched was busy.

     As a side note, if  you  are  running a multitasking operating system and
     use the START action (OS/2), or use EXEC to execute that START command of
     your operating system (OS/2,  Windows),  it  is  not likely that Unisched
     will be busy for more than a few seconds,  so  normally  event  execution
     times  will  not have to be postponed at all.  However, Unisched has this
     logic built in so  that  its  behaviour  in  case of unexpected events is
     predictible, and of course also for DOS  users  that  must  EXEC  lengthy
     tossing  processes.   And  of course this logic is useful if Unisched has
     been down (i.E. terminated and  not  restarted) for some minutes or hours
     because of system maintenance.


  Now  you  know enough to set up a basic Unisched configuration file.  If you
  encounter problems or have questions  that  cannot be solved by this manual,
  feel free to contact me.  Refer to chapter 6 for contact information.



  3.4 USING UNISCHED
  ------------------

  You can start Unisched  by  invoking  UNISCHE2.EXE  (OS/2)  or  UNISCHED.EXE
  (DOS).   Unisched  will then search its configuration file, UNISCHED.CFG, in
  the directory where the executable file  is stored (and only there).  If you
  want to place the configuration  file  elsewhere,  or  want  to  give  it  a
  different name, you have to use the /c<filename> parameter, like for example

     UNISCHE2 /ce:\configs\uni.cfg

  In the directory where the configuration  file is stored, Unisched will also
  create some other files.  Normally, you do not have to  bother  about  them,
  but I will give a short explanation on what these files do anyway:

     UNISCHED.DAY  In  this  file,  Unisched  stores  information  about which
                   events have already been executed  today.   If  you  delete
                   this file while Unisched is not running, all events will be
                   redone  the  next  time that Unisched starts, provided that
                   the current time still  is  in  the allowable time frame of
                   each event.  So normally you should not delete this file to
                   avoid  multiple  executions  of  a   single   event/action.
                   Sometimes,  on  the  other  hand,  it can be useful to quit
                   Unisched, delete  this  file,  and  restart  Unisched  - in
                   particular if Unisched seems to do strange things like  not
                   executing  events  that  should  be  executed  or executing
                   periodic  events  at  other   times  than  expected.   Such
                   behaviour results if you previously did heavy  modifcations
                   on  Unisched.Cfg  and  did  not  obey  to  the  rule not to
                   reassign  an  event  number  that  has  been  in  use  to a
                   different, new event.  Unisched will come back on track  by
                   itself  sooner  or  later (at midnight at lastest), but you
                   can delete UNISCHED.DAY in order to accelerate this.

     UNISCHED.ACT  This file  contains  a  dump  of  the  log  window  and the
                   backscroll buffer.  The backscroll buffer contains all  log
                   entries  that  have  been written on screen (in contrast to
                   the log file, which  usually  contains more entries) and is
                   used so that you can scroll  back  and  forth  in  the  log
                   window. Deleting this file does not cause any harm.

     UNISCHED.BSY  This  is  a  semaphore file that indicates that Unisched is
                   already running with the corresponding config file.  If you
                   try to invoke Unisched  while  a  busy semaphore exists, it
                   will not start up in order  to  avoid  undefined  behaviour
                   that  would  result if two Unisched processes would work on
                   the same configuration file.  It  is a good idea to include
                   a command to delete UNISCHED.BSY in the system startup file
                   (STARTUP.CMD or AUTOEXEC.BAT, etc.), because if your system
                   locks or reboots while Unisched is active,  the  .BSY  file
                   will survive the reboot, and Unisched would not start after
                   the system has rebooted.

  If  you  start  Unisched  with  a  config  file  that does not have the name
  "unisched.cfg", the basename  of  the  abovementioned  files will be adapted
  accordingly.

  Example:    UNISCHED   /Ce:\configs\usched1.cfg
  This will start Unisched with the configuration file e:\configs\usched1.cfg.
  The  other files that Unisched creates will be named e:\configs\usched1.day,
  e:\configs\usched1.act and e:\config\usched1.bsy.

  If there is a severe error in the config file, Unisched will not  start  up,
  but  print  a  log message dump onto the screen (the actual error reason can
  normally be found near the bottom of this dump) and waits 30 seconds for you
  to press a key.  After that time, or if you press a key, it will exit.   Non
  severe errors like faulty event action syntax will be logged when the action
  is  about  to  be executed, but they will not prevent Unisched from starting
  up.

  When  you  managed  to  start Unisched, you will see a list of function keys
  that have been assigned by you  in  the configuration file in the upper part
  of the screen.  Below that, a two line display shows the next static and the
  next periodic time controlled event that will be executed.  The bottom  half
  of  the  screen  is  filled  with  the log window, that shows messages about
  events and actions and other things that happen while Unisched is running.

  While Unisched is  a  tool  that  is  designed  to  work  automatedly in the
  background, you can also use it interactively.  You can press  all  function
  keys  that  you have assigned previously.  There are also some function keys
  that are hard-wired, cannot be changed, and will always be present:

  Alt+X          Exit Unisched.
  Cursor Up:     Scroll the log window up (back) by one line.
  Cursor Runter: Scroll the log window down (forward) by one line.
  Page Up:       Scroll the log window up by one page.
  Page Down:     Scroll the log window down by one page.
  Home (Pos1):   Jump to the beginning (oldest entry) of the log window.
  End (Ende):    Jump to the end (latest entry) of the log window.

  Under  OS/2,  you  can  also terminate Unisched by simply clicking the close
  button (you should not do this with the DOS version in Windows or OS/2, only
  the native OS/2 version  has  this  functionality).  The native OS/2 version
  also terminates correctly when you do a system shutdown.

  These are all hard-wired keys that Unisched knows.  If you want to use other
  function  keys  to  invoke  certain,   you   can  define  them  with  KeyXXX
  configuration statements.  Here are some examples.

  You want Alt+J to make Unisched open a DOS (OS/2) shell?

    KeyAltJ = EXEC COMMAND.COM
  or:
    KeyAltJ = EXEC CMD.EXE

  You want to have a hotkey that pops up an editor where you  can  change  the
  Unisched configuration?

    $EditConfig = EXEC c:\msdos\edit.exe e:\mailer\sys\unisched.cfg
    $ReadConfig = RESTART
    $DoConfig = $EditConfig $ReadConfig
    KeyAltC = $DoConfig

  Infinite possibilities are imaginable ... ;-)



4. ADVANCED UNISCHED USAGE
--------------------------

  4.1 ONLINE TOSSING
  ------------------

  4.1.1 - What is Online Tossing?

    Let us consider the case that for example you get  two  arcmail  packages,
    each  2  MB  in  size, from your uplink during a poll.  First, your mailer
    receives both packages, a total of  4  MB.   After that, it creates a flag
    file that triggers (because Unisched sees the flag file) the tosser  task,
    which  will process the packets.  The net time that passes from the moment
    that you start  your  outgoing  call  until  the  moment  when the mail is
    available for your downlinks is the time that you need to transfer  all  4
    MB, plus the time that your tosser takes to process it.

    Online  Tossing  is a technique to reduce this time.  It works as follows:
    You ask your uplink not to  send  you monolithic 2 MB arcmail packets, but
    to reduce the arcmail packet size to, say, 400 KB per packet.  Most tosser
    have a way to limit this size, so ask your uplink if his one supports  it.
    The  function  of  Unisched  in  this context is as follows:  Unisched can
    continuously monitor  your  inbound  directory.   As  soon  as any arcmail
    packet has been received completely, Unisched will start the tosser  which
    in  this  way  is  able  to process the first arcmail packet while you are
    still polling the  other  ones!   As  soon  as  your  tosser  is done with
    processing the first arcmail packet, Unisched will  again  look  into  the
    inbound  directory  and  if  (as soon as) any further arcmail packets have
    been received, Unisched  will  restart  the  tosser  to also process these
    ones.

    The result is that when you have finally  finished  polling  your  Uplink,
    there is only the very last arcmail packet still untossed, and your tosser
    will toss it within a much shorter time than if it  would  still  have  to
    toss  the  whole amount.  Also, if for example you are running a multiline
    system and a downlink calls you  at  a time when you have already received
    3.6 MB out of 4 MB, the downlink will probably already get those 3.6 or at
    least 3.2 MB out of those 4 MB, while if you would not use Online Tossing,
    he would get nothing.

    Online Tossing effectively reduces the time  until new mail polled at your
    uplinks will be available for your downlinks.

  4.1.2 - System Requirements for Online Tossing

    1. You should have a good knowledge of your system and some experience
       with Unisched.
    2. Your mailer and operating system must have support for file  sharing  /
       locking.   I.E.  while  a  mailer  is still receiving a file, it should
       disable access to those files for  other processes by opening them with
       SH_DENYALL.  This is the only way for Unisched to know  when  the  file
       has  been  received  completely:  as soon as it is not locked any more.
    3. Your system must be capable of doing 100% reliable multitasking.
    4. Your tosser must be configured correctly.

    Remarks on item  2:   I  tested  the  software  McMail, BinkleyTerm XE and
    Cantaloup.  McMail 1.0g5 and later versions worked OK.   Binkley  XE  also
    worked  OK  (except for DOS XR1 and XR2, you must either use a later gamma
    like XR6 or an OS/2 version).  Cantaloup 1.0 also worked OK.  Also do note
    that  on  DOS,  you must load SHARE.EXE for file locking support.  You can
    test if your system  is  ready  for  online  tossing  (with regard to file
    locking) in the follwing  way:   F'request  a  large  file  that  takes  a
    sufficiently  long  time  for  downloading.   While  your  mailer is still
    downloading the file, try to  run  TYPE  on  this file.  You should get an
    error message about a sharing violation.  If you get it, online tossing is
    OK, if you don't get it, your  mailer  software,  OS  or  network  is  not
    capable of file locking.

    Remarks on item 3:  You would probably not be using Unisched if  you  were
    not using some sort of multitasking system, be it OS/2, Windows, DESQview,
    or  a  network  of  many  DOS  PC's.   However,  not  all  system  that do
    multitasking are also fit for  online  tossing.  In normal operation (i.E.
    without online tossing), the tosser task only runs occasionally while  the
    mailer  is  transferring  files.   If  starting the tosser task produces a
    single CRC error, or decreases the CPS rate slightly by 5% or  so,  it  is
    OK,  because  it only happens rarely and does not last long.  If, however,
    you are using online tossing, you  do enforce that EVERYTIME when you have
    a mailer connect, the tosser task WILL start while  the  mailer  is  still
    transferring  files.  Or to put it the other way round, ALL of your mailer
    connects will definitely be accompanied by a tosser process running in the
    background.  The requirements  that  result  from  this  are simple:  Your
    multitasking system must be capable of running a  background  tosser  task
    with NO visible impact on CPS rate or connection quality AT ALL.

    If  your  system  is  capable  of  doing  this  strongly  depends  on your
    individual configuration.  Generally, an OS/2  PC  with a Pentium 90, SCSI
    hard disks and ISDN TAs (not passive cards!) using FIFO's and Ray  Gwinn's
    SIO.SYS  using  native  OS/2  mailers  and  tossers  will be OK.  I tested
    several of those configurations  and  they  fulfilled my requirements.  As
    for Windows PCs, well, I also tested several of those ... to put  it  this
    way, it is possible that Windows also fulfills the requirements, but it is
    not  very  likely  that  a  default  Windows  Fido setup does.  Generally,
    systems with EIDE tend to have  impacts on communication quality while the
    hard disk is running, while systems with SCSI are usually better off.

    Remarks on item 4:  You absolutely have to make sure that your tosser will
    remove ALL packets, PKT  files  and  Arcmail  packets  from  your  inbound
    directories,  either  by  processing them or by moving them to a bad path.
    If your tosser cannot process a packet, because of security considerations
    or because it is broken, it  MUST  move  the  packet to another path or at
    least rename it to *.BAD or something.   If  it  doesn't,  Unisched  would
    restart  the  tosser  as  soon as it has finished, because Unisched thinks
    that there is still mail that has  to  be tossed.  This would result in an
    endless loop.  -- Generally, Fastecho is OK in this  respect,  though  you
    have to take some considerations even with Fastecho.

    Online tossing is not for the weak of heart.  Unisched provides you with a
    lot of help and guidance, but never the less, you  can  easily  stop  your
    system from working reliably with online tossing ;-).

    Now  if  you  are scared by this huge bunch of warnings, let me assure you
    that online tossing is working  flawlessly  on  my  own system, and that I
    know about a dozen other users of Unisched that use it as well.


  4.1.3 - How to do it!

    After this prolongued epilogue, I will  now  tell you what you have to put
    into your configuration file for online tossing to work.   Some  of  these
    keywords have not been mentioned in the previous chapter!


     Inbound = <inbound directory>
     -----------------------------

     This is a directory where Unisched will look for .PKT files, and ONLY for
     .PKT files.   You  should  configure  your  unprotected inbound directory
     (that one in which you receive crash mails from  system  with  which  you
     don't  have  a  password  -  you usually want only to toss PKT files from
     here, but  never  arcmail  packets)  with  this  keyword.   The "Inbound"
     keyword may be repeated as often as you desire.

     Example:
     Inbound=e:\bt\inbound
     Inbound=e:\bt\local


     ProtIn = <directory>
     --------------------

     In this directory,  Unisched  will  look  for  .PKT  files,  for  arcmail
     attaches  (*.MO?,  *.TU?,  ...  *.SU?), and, if enabled (see below), also
     for *.TIC files.  You can  repeat  the  "ProtIn"  keyword as often as you
     desire.

     Example:
     ProtIn=e:\bt\secure


     TosserSema = <filename>
     -----------------------

     This sempahore file serves communication purposes  between  Unisched  and
     the  online  tossing  tosser  task.   Unisched  creates this file when it
     starts the tosser task  after  finding  a  mail  packet in the configured
     inbound directories.  As long as it does exist, it will not start another
     instance of the tosser task.  Consequently it is a good idea to let  your
     system startup scripts delete this file.

     Example:
     TosserSema = e:\sema\tossing.sem


     TosserAction = $<action1> [$<action2> ...]
     ------------------------------------------

     With  this  keyword  you  specify the action that will be executed if any
     mail packet hsa been found.  Usually,  the  action will invoke a batch or
     script file.  In writing this script file, you should take  care  of  the
     following requirements:

     - Reapeating this again, the online tossing batch  or  script  file  MUST
       remove  all  PKT  and  Arcmail  (*.MO?  ..  *.SU?) files from the given
       inbound and protin directories in  order to avoid endless tossing loop.
       If the tosser sometimes leaves files in the  inbound  directores  (good
       tossers  rename packets which they cannot process to *.BAD, but not all
       tossers are good ...),  the  batch  file  has  to  take care of this by
       issueing the respective RENAME commands.

     - When the batch file has finished, the file that has been specified  as
       argument to the TosserSema parameter MUST be deleted, so that Unisched
       knows that it can restart the tosser task if necessary.

     - You should NOT invoke the ticker software (TIC file processor, Filefix,
       Allfix,  etc.)  in  this batch file, because if the remote mailer first
       sends the TIC file and sends the file that is described by the TIC file
       after the TIC file  itself,  it  could  happen  that your batch file is
       invoked  when  the  TIC  file  has  already  been  received,  but   the
       corresponding binary file has not yet been received, so that the ticker
       would treat the TIC file as bad.

       You  should  only invoke the ticker in a batch file that is executed by
       Unisched AFTER the  mailer  session  has  completed.   You do this with
       tosser task dependent semaphores, see below.

     To sum it up:  The batch file should only process netmail  and  echomail,
     but it should process ALL mail. Also it must delete the TosserSema file.

     Example:
     TosserAction = $Import_Mail_Only


     Tosser Task Dependent Semaphore Files
     -------------------------------------

     Syntax: +<path+filename> = $<action name> [$<action name> ... ]

     Semaphores declared like this work like normal flag files (those declared
     with  an  asterisk  "*"),  except  for  the  case  when  the file that is
     configured  with  TosserSema  keyword  exists.   In  this  case, Unisched
     ignores a tosser dependent semaphore file for as long as  the  TosserSema
     file does exist.

     You  need  tosser  task  dependent  semaphore  files  in conjunction with
     online tossing.  As  has  been  explained  above,  some  actions that are
     normally performed in a tosser batch file (like invoking the file ticker)
     must NOT be performed in the online tossing  tosser  batch  file.   Those
     actions must be performed in a batch file that is being executed when the
     mailer session has finished completely.

     They  way  to  go  is  to test for the "inbound mail semaphore" that your
     mailer creates  (like  BTMAIL.IN  or  simlar,  the  file  that the mailer
     creates when a session has finished and anything has been received during
     this session).  You should, however, not use normal flag files  ("*")  to
     test  for  the  inbound  mail  semaphore if you are using online tossing,
     becuase in thise case the "end  of  session batch file" could be executed
     while the "online tossing batch file" (the one defined  in  TosserAction)
     is  still  running.   Instead,  you  use tosser task dependend flag files
     ("+") to test for the  inbound  mail  semaphore.  This will make Unisched
     ignore the inbound mail semaphore as long as the online tossing batch  is
     still  running,  but  invoke  the  "end  of session batch" as soon as the
     online tossing batch has  finished  (if  any  mail  has been received, of
     course).

     Unisched also provides for the reverse case:  When Unisched executes  the
     action  that  has  been  defined  with  a  "+"  (tosser  task  dependent)
     semaphore   definition,  it  creates  the  file  that  is  configured  as
     "TosserSema". So the result is:

     THE END OF SESSION BATCH  FILE  that  you  configure with "+" MUST DELETE
     THE "TosserSema" FILE!!!

     Example:
     +btmail.in = $end_of_session_batch


  4.1.4 - Good Luck!

     Now that you have read everything, I suggest that you sleep a night  over
     it  and  contemplate  what  actually  is  going  on there :-), before you
     actually start to configure it.



  4.2 SELECTIVE SUPPRESSION OF LOG FILE MESSAGES
  ----------------------------------------------

  In principle,  the  keywords  DiskLog,  ScreenLog  and  PipeLog  give  you a
  possibility to control how much information you want to see in the disk  log
  file,  in  the  log  window or in the control pipe.  However, sometimes, the
  granularity of these commands is not good enough.

  An example situation might be a  periodic  event that does nothing more than
  to create a semaphore file regularly (so that other supervisor  tools  could
  see  that  Unisched  is  still  running).   Normally,  you would want to see
  information about periodic  events  to  be  logged,  but for this particular
  event, you do not want to see log information because it would pollute  your
  log files with too much detail.

  For situations like that, you have the possibility  to  selectively  exclude
  information  about  a certain event and the corresponding actions from being
  logged by including  the  whole  event  definition  in  square brackets.  No
  information pertaining to conditions that lead to execution of  this  event,
  nor  information  pertaining  to the execution of the event commands itself,
  will be printed neither into screen, nor disk, nor pipe log.

  For example, an entry like

  $Create_Alivesemaphore = SEMAPHORE e:\flags\unisched.alv
  #111 ~1 = $Create_Alivesemaphore

  would  lead  to  a  massive  pollution  of  your  log  file  with  senseless
  information, so you will want to change these lines either like this:

  [ $Create_Alivesemaphore = SEMAPHORE e:\flags\unisched.alv ]
  #111 ~1 = $Create_Alivesemaphore

  or like this:

  $Create_Alivesemaphore = SEMAPHORE e:\flags\unisched.alv
  [ #111 ~1 = $Create_Alivesemaphore ]

  or like this:

  [ $Create_Alivesemaphore = SEMAPHORE e:\flags\unisched.alv ]
  [ #111 ~1 = $Create_Alivesemaphore ]

  to prevent inclusion of information about this action in the log.



  4.3 DELAYED REACTION ON SEMAPHORE FILES
  ---------------------------------------

  Recapitulating the information from chapter 3, a line like

  *btmail.in = $start_the_tosser

  will make Unisched, as soon as  the  file  btmail.in is found, a) execute an
  action (in this case, the action named $start_the_tosser, which we assume to
  start the tosser task) and b) delete  the flag file btmail.in.  We call this
  a FLAG FILE definition.

  A line like

  ^\mailer\inbound\xxxfiles.zip = $unpack_filelist

  will make Unisched start the given action as  soon  as  the  given  file  is
  found, but Unisched will not delete the file.  Unisched will not trigger the
  action  again  unless the file vanishes (probably because the action deletes
  or moves it, or because of some other effects) and then reappears.  We  call
  this a TRIGGER FILE definition.

  Sometimes,  however,  you  might wish that Unisched does not react instantly
  when one of these files  is  created  by  another program,  but you may wish
  that Unisched only reacts if the file  is  older  than  a  given  number  of
  minutes  or  seconds  (or in another way of viewing it, if the file has been
  in existance for a minimum duration).

  You can do so by specifying the desired  delay  in  minutes  within  pointed
  brackets directly  after  the  asterisk  (*)  or  hat  (^)  character of the
  semaphore file definition.

  Here are two examples of application:

  4.3.1 Delaying the export of newly written mails

     ^<-10>echotoss.log = $export_local_mail

     Mail editors like Timed or Msged can create a  file  named  echotoss.log,
     netmail.jam, echomail.jam or similar that contains information about what
     area  you have written mails in.  Some mail editors create this file only
     when you exit the mail editor, while  other  update the file as soon as a
     new mail has been entered.

     While the main usage of these  files  is  to reduce the CPU time usage of
     the tosser by instructing it to only export mail from some areas  instead
     of  scanning the whole message base mostly in vain, you could also simply
     regard these files as an indication  for newly written mail.  So it would
     make sense to instruct Unisched to start the mail export  batch  file  as
     soon as such a file is created.

     However, at least for me it is not uncommon that I write a mail, save it,
     and some minutes later, things come into my mind that I would like to add
     to the mail, or I decide to change it substantially.  If this also occurs
     to you frequently, it is a bad  idea  to configure Unisched in a way that
     it instantly exports all newly written mail, because as soon as a mail is
     exported, you cannot change it without major hassle.

     Therefore, you may want to use delayed trigger files like in the  example
     above.   The  command  line that is shown above will instruct Unisched to
     wait 10 minutes before reacting to the echotoss.log file.  So you have 10
     minutes time to decide if  you'd  rather  delete  the flame that you have
     just written, rather than exporting it. ;-).



  4.3.2 Test if the mailer is still up and running.

     *<-30>e:\flags\cl-alive.01 = $some_action

     The mailer Cantaloup creates a file named cl-alive.<task_number> when  it
     starts  up.   Also,  Cantaloup "touches" (updates the time stamp of) this
     file  every  five  minutes.   Most  other  mailer  software  has  similar
     features.

     If you configure Unisched  like  shown  above,  as  long as everything is
     working OK, Unisched will never react to cl-alive.01,  because  Cantaloup
     will  periodically  touch  the file, so the file will never be older than
     five minutes for Unisched's eyes,  but  Unisched  would only react if the
     file was at least 30 minutes old.

     If, however, something unusal happens to Cantaloup -- i.E. if it  crashes
     --,  the  file  cl-alive.01  will  no longer be touched by Cantaloup, and
     after half an hour, Unisched will  detect this problem and has the chance
     to perform some action against it  (usually  this  means  to  reboot  the
     system because you cannot know what in detail went wrong, but some sysops
     do more sophisticated things here)

     However,  you should be aware of the fact that some mailers do not update
     the alive flag as long as a  BBS  is spawned.  In this case, you must set
     the delay to a value that is greater than the  maximum  allowable  online
     time in your BBS.

     Also, there are other (more common!) reasons for mailers not being up and
     running  than  a  crash.   The  most common reason at my system is that I
     inadvertently close the mailer (think  of your baby daugther running over
     the keyboard <g> -- although you can also do it without little  children,
     as my example proves ...).   In  this  case, the cl-alive.01 file will be
     deleted by Cantaloup before it closes, and Unisched will not see an "old"
     alive semaphore file.

     Therefore if you are using delayed trigger files that test  if  a  mailer
     has  crashed  you  should always combine them with inverted trigger files
     that test if the mailer is running at all, and restart it if not:

     !^e:\flags\cl-alive.02 = $Start_CL_Task_1



5. SHAREWARE / LICENSE
----------------------

UniSched  is  (C) 1996-99 by Tobias Ernst.  This software is Shareware and may
be evaluated free of charge  for  a  period  of  30  days.  You may spread the
Shareware version among friends, over BBSes or the internet as long as you  do
this  without modifying the original distribution archive or its contents.  If
you continue to use Unisched after the  evaluation period of 30 days, you must
register the software.

Registration of Unisched is EUR 12 or US$ 12.  When you register Unisched, you
will receive a personalized key that will be valid for  all  future  text-mode
OS/2  and  DOS  versions of Unisched.  A registration form can be found in the
REGISTER.ENG file.  Note that the  key  is  only  a proof that you are legally
using Unisched after the evaluation period is over.  It does  not  enable  any
new  feature,  as  the  Shareware  version  of  Unisched  is not restricted or
crippled in any way.  Also note that the author denies any responsibilites for
any damage that might be  the  direct  or indirect consequence from using this
software.




6. CONTACT AND SUPPORT
----------------------

Fidonet (preferred):

  I do regularly monitor the following echomail areas:

      FIDO_UTIL
      OS2BBS.GER
      FIDOSOFT.MISC.GER

  All of them are certainly good  places  to  place to discuss Unisched, and I
  will also answer therein if you post a question on Unisched.

  You can reach me via Fidonet netmail at

      Tobias Ernst @ 2:2476/418

  The lastest version of Unisched will always be available for filerequest
  using the magic UNISCHED at my fido node (2:2476/418).

Internet:

  There is a  mailing  list  available.   Announcements  about new versions of
  Unisched will be made there, and you can post questions  and  discuss  about
  the  program  with  other  users.  To subscribe to the mailing list, send an
  e-mail to

               [e-mail]

  and put the string

               subscribe

  as the only line into  the  body  of  the message.  (Even though the mailing
  list is powered by BMT Micro, you can of course also participate  in  it  if
  you are not (yet?  <g>) a registered user.)

  You can also reach me via e-mail at

               [e-mail]

  The most recent version of  Unisched will always be available at

               ftp://ftp.bmtmicro.com/bmtmicro

[EOF]