1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
4 <title>Crontab - doing things periodically</title>
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">
12 <body TEXT="#000000" LINK="#0000ff" VLINK="#800080" BGCOLOR="#FFFFFF">
13 <FONT COLOR="#606060">
15 <h2>Crontab - doing things periodically</h2>
20 <address><a href="mailto:djk@tobit.co.uk">Dirk Koopman G1TLH</a></address>
22 <!-- Created: Sun Dec 13 20:25:14 GMT 1998 -->
24 Last modified: Sun Jan 24 15:30:56 GMT 1999
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.
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>.
39 <p>The files will automatically be re-read whenever you change them.
41 <h4>The <tt>Crontab</tt> File </h4>
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.
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:-
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>
61 <p>A field may be '*', which means 'any when' for that field.
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
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>.
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
76 start_connect('gb7tlh') if !connected('gb7tlh')
78 will attempt to start a <a href="connect.html">connection</a> process to GB7TLH if it isn't
79 already locally connected.
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
86 <p>A full <tt>crontab</tt> file could like like:-
89 # This is a sample crontab file
92 # check every 10 minutes to see if gb7tlh is connected and if not
93 # start a connect job going
95 0,10,20,30,40,50 * * * * start_connect('gb7tlh') if !connected('gb7tlh')
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
102 15 3 * * 0 spawn('/spider/local/analyse.pl')
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
108 15,30 * * * spawn("echo $main::mycall is a DXSpider Version $main::version DX Cluster system")
110 # then there is always the highly contentious one like this little jem which
111 # checks every hour to see if a certain callsign is connected to another cluster
112 # and silently disconnects him. This is an example only (of course...)
114 23 * * * * rcmd('rcmd/gb7dxm disc/noinform G9TLH') if present_on('G9TLH', 'GB7DXM')
118 It is important remember that these <tt>crontab</tt> routines execute in line with the main
119 cluster code, so if you create a long, slow <tt>crontab</tt> command, it will impact on the speed
120 and usability of the cluster as a whole.
122 <h4>Standard Routines</h4>
124 As mentioned earlier, there are a small number of routines that are declared in <tt>DXCron</tt>
125 context. They are there basically to make the starting of connections and external programs easy.
129 <p><li><b>connected(<callsign>)</b> - returns true if the <callsign> is directly connected
130 to this cluster node.
131 <p><li><b>start_connect(<script-name>)</b> - starts a <a href="connect.html">connection</a>
132 script just as if you had typed in <tt>connect script-name</tt> on the sysop console client.
133 <p><li><b>spawn(<command>)</b> - start a <command> as a new process. This is used to do
134 various batch jobs that you may wish to happen at certain times of the day or week that operate
135 on your machine but don't require access to the real-time internals of the cluster daemon. You can
136 execute just about any command you like, but <em>be warned</em> <b>stdin</b> and <b>stdout</b> are
137 still connected to the same terminal (if any) as the cluster daemon. Any unix command and arguments
138 can used, see <tt>exec</tt> in the <a href="http://www.perl.com">perl</a> documentation.
139 <p><li><b>disconnect(<callsign>)</b> - disconnects a locally connected station from your node.
140 <p><li><b>rcmd(<node-call>, <command>)</b> - send a command to another node in exactly the
141 same way as, for example, <tt>RCMD/GB7TLH disc GB7DJK</tt> typed on a sysop console.
142 <p><li><b>present(<exact-callsign>)</b> and <b>presentish(<callsign-no-ssid>)</b> - returns
144 callsign is connected anywhere on the cluster either with the exact callsign or with the callsign
145 minus its ssid respectively.
146 <p><li><b>present_on(<exact-callsign>, <node>)</b> and <b>presentish_on(<callsign-no-ssid>, <node>)</b> - returns
148 callsign is connected on the node specified either with the exact callsign or with the callsign
149 minus its ssid respectively.
150 <p><li><b>last_connect(<callsign>)</b> - Returns the last connect time of the callsign or the
151 current time if it is currently connected locally.
156 There was an intermittent problem when running
157 (especially?) with the debugger on. Essentially you would
158 experience random crashes with nonsensical error messages returning from funny places on the stack (if
159 the debugger was on) or just core dumping (if it wasn't).
161 <p>I believe this now to be fixed. YMMV, if so tell me about it!
163 <!-- Standard Footer!! -->
166 <FONT COLOR="#606060"><hr></font>
167 <font color="#FF0000" size=-2>
168 Copyright © 1998 by Dirk Koopman G1TLH. All Rights Reserved<br>
170 <font color="#000000" size=-2>$Id$</font>