html/cron.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
   2 <html>
   3   <head>
   4     <title>Crontab - doing things periodically</title>
   5   </head>
   6
   7         <meta name="Keywords" content="DX Cluster, DXSpider, Spider, Packet Cluster, DXCluster, Pavillion Software, AK1A, AX25, AX.25, WWV, Packet Radio, Amateur Radio, Propagation, DX, DXing, G1TLH, GB7TLH, Dirk Koopman, Mailing list, Linux, RedHat, PERL">
   8         <meta name="Description" content="Software and systems for realtime digital communications between amateur radio stations for the provision of information on propagation conditions and stations operating">
   9         <meta name="Author" content="Dirk Koopman G1TLH">
  10   </head>
  11
  12   <body TEXT="#000000" LINK="#0000ff" VLINK="#800080" BGCOLOR="#FFFFFF">
  13         <FONT COLOR="#606060">
  14           <hr>
  15           <h2>Crontab - doing things periodically</h2>
  16           <hr>
  17         </font>
  18
  19
  20         <address><a href="mailto:djk@tobit.co.uk">Dirk Koopman G1TLH</a></address>
  21         <p>
  22           <!-- Created: Sun Dec 13 20:25:14 GMT 1998 -->
  23           <!-- hhmts start -->
  24 Last modified: Mon Dec 28 01:06:43 GMT 1998
  25 <!-- hhmts end -->
  26         <h4>Introduction</h4>
  27
  28         There are a number of jobs that need to be done periodically. The
  29         principle one being starting <a
  30         href="connect.html">connections</a> to other clusters if you are
  31         not connected. The <tt>crontab</tt> allows you to do this.
  32
  33         <h4>Location</h4>
  34
  35         There two locations for the <tt>crontab</tt> files. The first and standard one (which
  36         in common with other 'issue' files should not be changed) lives at <b>/spider/cmd/crontab</b>.
  37         The sysop changable one lives at <b>/spider/local_cmd/crontab</b>.
  38
  39         <p>The files will automatically be re-read whenever you change them.
  40
  41         <h4>The <tt>Crontab</tt> File </h4>
  42
  43         The <tt>crontab</tt> file defines what is to be done and
  44         when. It consists of lines of text created by your favorite editor. Completely blank
  45         lines or lines starting with '#' are ignored.
  46
  47         <p>Each line of a <tt>crontab</tt> file contains six fields
  48         each separated with white space. The first five fields are times when the
  49         command is to be executed and the last field is the command
  50         itself. The time fields consist of:-
  51
  52         <p><table border=2>
  53           <tr><td>field</td><td>Allowed Values</td></tr>
  54           <tr><td>minute</td><td>0 - 59</td></tr>
  55           <tr><td>hour</td><td>0 - 23</td></tr>
  56           <tr><td>day of month</td><td>1 - 31</td></tr>
  57           <tr><td>month</td><td>1 - 12</td></tr>
  58           <tr><td>day of week</td><td>0 - 6 (0 is Sunday)</td></tr>
  59         </table>
  60
  61         <p>A field may be '*', which means 'any when' for that field.
  62
  63     <p>Ranges of numbers are allowed.  Ranges are two numbers
  64     separated with a hyphen.  The specified range is inclusive.  For
  65     example, 8-11 for an <tt>hours</tt> entry specifies execution at hours
  66     8, 9, 10 and 11.
  67
  68     <p>Lists are allowed.  A list is a set of numbers (or ranges)
  69     separated by commas.  Examples: <tt>1,2,5,9</tt> or <tt>0-3,5,8-12</tt>.
  70
  71         <p>Commands are actually small snippets of perl. They can be anything legal within
  72           perl and the context of the DXSpider <tt>cluster.pl</tt> daemon. The normal use will be connecting
  73           to another cluster and a set of routines are specially provided in the context
  74           of the <tt>DXCron</tt> package to make this easy. For example
  75         <pre>
  76   start_connect('gb7tlh') if !connected('gb7tlh')
  77     </pre>
  78         will attempt to start a <a href="connect.html">connection</a>  process to GB7TLH if it isn't
  79         already locally connected.
  80
  81         <p>There is absolutely no reason why you could not do something more complicated using information
  82           contained inside the DXSpider daemon, but this will obviously require a more complex line of code.
  83           You can also write your own functions, include them within the DXSpider system and call them from
  84           the <tt>crontab</tt>
  85
  86         <p>A full <tt>crontab</tt> file could like like:-
  87         <pre>
  88   #
  89   # This is a sample crontab file
  90   #
  91   #
  92   # check every 10 minutes to see if gb7tlh is connected and if not
  93   # start a connect job going
  94
  95   0,10,20,30,40,50 * * * * start_connect('gb7tlh') if !connected('gb7tlh')
  96
  97   # at 03:15 on Sundays start a job called 'analyse.pl' which does something
  98   # or other. This starts a new process and runs to completion, be careful
  99   # what you do with stdin and stdout as they are the same as those of
 100   # cluster.pl
 101
 102   15 3 * * 0 spawn('/spider/local/analyse.pl')
 103
 104   # this is a pointless command which will echo the string shown
 105   # on the same terminal as the cluster.pl program after substituting
 106   # the values for mycall and version
 107
 108   15,30 * * * spawn("echo $main::mycall is a DXSpider Version $main::version DX Cluster system")
 109         </pre>
 110
 111         It is important remember that these <tt>crontab</tt> routines execute in line with the main
 112         cluster code, so if you create a long, slow <tt>crontab</tt> commands, it will impact on the speed
 113         and usability of the cluster as a whole.
 114
 115         <h4>Standard Routines</h4>
 116
 117         As mentioned earlier, there are a small number of routines that are declared in <tt>DXCron</tt>
 118         context. They are there basically to make the starting of connections and external programs easy.
 119         They are:-
 120
 121         <ul>
 122                 <p><li><b>connected(&lt;callsign>)</b> - returns true if the &lt;callsign> is directly connected
 123                 to this cluster node.
 124                 <p><li><b>start_connect(&lt;script-name>)</b> - starts a <a href="connect.html">connection</a>
 125                 script just as if you had typed in <tt>connect script-name</tt> on the sysop console client.
 126                 <p><li><b>spawn(&lt;command>)</b> - start a &lt;command> as a new process. This is used to do
 127                 various batch jobs that you may wish to happen at certain times of the day or week that operate
 128                 on your machine but don't require access to the real-time internals of the cluster daemon. You can
 129                 execute just about any command you like, but <em>be warned</em> <b>stdin</b> and <b>stdout</b> are
 130                 still connected to the same terminal (if any) as the cluster daemon. Any unix command and arguments
 131                 can used, see <tt>exec</tt> in the <a href="http://www.perl.com">perl</a> documentation.
 132         </ul>
 133
 134         <h4>Caveats</h4>
 135
 136         There seems to be an intermittent problem when running
 137         (especially?) with the debugger on. Essentially you will
 138         experience random crashes with nonsensical error messages. I
 139         believe that this is caused by stack tracing trying to work inside
 140         <tt>forked</tt> processes.
 141
 142 <!-- Standard Footer!! -->
 143         <p>&nbsp;</p>
 144         <p>
 145           <FONT COLOR="#606060"><hr></font>
 146         <font color="#FF0000" size=-2>
 147           Copyright &copy; 1998 by Dirk Koopman G1TLH. All Rights Reserved<br>
 148         </font>
 149         <font color="#000000" size=-2>$Id$</font>
 150   </body>
 151 </html>