]> gb7djk.dxcluster.net Git - spider.git/blob - html/program.html
fixup git indent problem
[spider.git] / html / program.html
1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
2 <html>
3   <head>
4     <title>Programming New Commands</title>
5
6         <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">
7         <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">
8         <meta name="Author" content="Dirk Koopman G1TLH">
9     <link rel=stylesheet href="style.css" type="text/css" title="default stylesheet">
10
11   </head>
12
13   <body TEXT="#000000" LINK="#0000ff" VLINK="#800080" BGCOLOR="#FFFFFF">
14         <FONT COLOR="#606060"> 
15           <hr>
16           <h2>Programming New Commands</h2>
17           <hr>
18         </font>
19         
20         
21         <address><a href="mailto:djk@tobit.co.uk">Dirk Koopman G1TLH</a></address>
22         <p>
23           <!-- Created: Sun Dec 13 20:25:14 GMT 1998 -->
24           <!-- hhmts start -->
25 Last modified: Mon Dec 28 23:13:21 GMT 1998
26 <!-- hhmts end -->
27         <h4>Introduction</h4>
28         
29         All the commands in the DXSpider system are 'soft', that is they are bits of
30         perl code that are put into specific places in the <tt>/spider</tt> directory tree. 
31         
32         <p>By putting them in a specific place and calling them &lt;command>.pl, they become
33           commands - in real time. Such is the magic of 
34           <a href="http://www.perl.com">perl</a>.
35
36         <h4>Directory Structure</h4>
37
38         The directory structure is very simple:-
39         <table border=2>
40           <tr><td>/spider</td><td>the main directory</td></tr>
41           <tr><td>/spider/data</td><td>where generated and/or reference data goes</td></tr>
42           <tr><td>/spider/data/spots/&lt;year>/&lt;day>.dat</td><td>one day's worth of spots</td></tr>
43           <tr><td>/spider/data/debug/&lt;year>/&lt;day>.dat</td><td>one day's worth of console debugging</td></tr>
44           <tr><td>/spider/data/log/&lt;year>/&lt;month>.dat</td><td>one month's worth of Logging info including things like rcmd, announces, talks etc</td></tr>
45           <tr><td>/spider/data/wwv/&lt;year>/&lt;month>.dat</td><td>one month's worth of WWV</td></tr>
46           <tr><td>/spider/msg</td><td>the messages directory</td></tr>
47           <tr><td>/spider/packclus/files</td><td>the files directory</td></tr>
48           <tr><td>/spider/packclus/bulletin</td><td>the bulletins directory</td></tr>
49           <tr><td>/spider/perl</td><td>where the issued program code lives</td></tr>
50           <tr><td>/spider/local</td><td>where your experimental/site specific programs go</td></tr>
51           <tr><td>/spider/cmd</td><td>where the issued command code lives</td></tr>
52           <tr><td>/spider/local_cmd</td><td>where your experimental command code goes</td></tr>
53         </table>
54
55         <p>A command is put in full as a file under the 'cmd' directory tree, for example, 
56           <tt>announce</tt> lives in <tt>/spider/cmd/announce.pl</tt> and <tt>show/dx</tt> lives
57           in <tt>/spider/cmd/show/dx.pl</tt>. 
58
59         <p>In general terms I don't like the habit of the standard packet cluster software has
60           of taking the DEC VMS command paradigm to the extreme that it has. So I have adopted
61           the convention of separating commands from arguments. So <tt>sh/dx/10 20</tt> is input
62           on the DXSpider system as <tt>sh/dx 10 on 20m</tt>. This is rather contentious.
63
64         <P>In order to maintain a larger level of compatibility, there is an <tt>Aliases</tt> which
65           lives in <tt>/spider/cmd</tt> (or can be overidden by one in <tt>local_cmd</tt>). This file
66           takes standard expressions, parses command lines and produces DXSpider compatible versions
67           of the old Packet Cluster commands. Currently, however, it doesn't do a 100% job because
68           the functionality of the new commands is different (and hopefully better).
69
70         <P>In addition, in the <tt>/spider/perl</tt> directory (overidden by ...) there is 
71           the <tt>Messages</tt> file. This is the file where all the system messages will be stored
72           (because of laziness on my part this isn't currently the case). You will see instances
73           of its use like <tt>$self->msg(&lt;string>&nbsp;[,$arg..])</tt>. This call uses
74           <tt>$self</tt> to determine what language you are in, to return you the correct message.
75           The way arguments are passed to the routine, mean that you can reorder the arguments
76           in your message to suit your language without changing the actual code.
77
78           <p>When you roll your own commands, put
79           your messages in your own copy of the <tt>Messages</tt> file and don't forget
80           to send me the patches for that as well the command itself.
81                             
82         <p>When I issue a new version or patches for an existing version then only files in
83           the <tt>/spider/cmd</tt> and <tt>/spider/perl</tt> directories will normally be altered.
84           Occasionally, one or two of the reference files in <tt>/spider/data</tt> may be altered.
85           The only files likely to be affected are <tt>bands.pl</tt> and <tt>prefix_data.pl</tt>.
86
87         <p>As it says in the next section, <b>PLEASE</b> experiment in the local directories! It will
88           save a lot of pain when patching code. Having said that, if you have been playing, then 
89           remember to remove or rename any files with new releases that claim to have incorporated 
90           your modifications, otherwise <EM>it will continue to use the old ones in your local 
91                 directories!</em>
92
93         <p>If you want to add facilities to the daemon itself or do some
94         fancy local spot routing, you might like to try looking at <a
95         href="local.html">Local</a> customisations.
96
97         <h4>Hints, Tips and Exhortations</h4>
98
99         <ol>
100
101                 <p><li>Every command that can used on the command line lives in either
102                 this directory ('cmd') or in a local version ('local_cmd'). You are
103                 cajoled or ordered not to and generally discouraged from altering the
104                 commands in the 'cmd' directory. You can put local copies in the
105                 'local_cmd' directory and they will override the standard ones.
106
107                 <p><li>If you want to play, do it in the 'local_cmd' directory. It's
108                 very easy and reasonably safe. You can override a command whilst the
109                 cluster is running.  Compilation errors will simply give you error
110                 messages, it won't stop the cluster running - this only happens if you
111                 mess with the internals to the extent that it gets confused...
112                 
113                 <p><li>A command is a piece of perl, it is simply a small snippet of
114                 program that is dynamically loaded into the cluster on invocation from
115                 the command line. The last modification time is used to determine
116                 whether to reload it.
117                 
118                 <p><li>New (or altered) commands are available for test the moment you
119                 save them.
120                 
121                 <p><li>A command is placed into the appropriate directory with a '.pl'
122                 appended to the end. So the 'show/qra' command lives in
123                 'cmd/show/qra.pl' (or a local version would be in
124                 'local_cmd/show/qra.pl'.
125                 
126                 <p><li>For the security conscious, potentially dubious
127                 characters command line args (i.e. not [A-Za-z0-9_/]) are
128                 converted to their hex equivalents. This will almost certainly
129                 mean that the user will get an error message (unless you have
130                 your secret squirrel hat on and have deliberately put such
131                 commands up [in 'local_cmd' of course]).
132
133                 <p><li>The snippets of program you put here are wrapped in an eval { }
134                 and are subroutines derived from the DXChannel class. They effectively
135                 the following declaration :-
136                 <p><pre>
137   sub Emb_&lt;cmdname>($self, $args)
138   {
139      ...
140      your code here
141      ...
142   }
143                 </pre>
144
145                 <p><li>slash characters are replaced by '_' so the equivalent name for
146                 'show/qth' is 'Emb_show_qth'.
147
148                 <p><li>you would normally do a 'my ($self, $line) = @_;' as the first
149                 thing. There are a complete set of accessors for DXUser, DXCommandmode,
150                 DXChannel and most other classes and these are the recommended way of getting at
151                 the contents of these classes.  A fairly standard start might be:-
152                 <p><pre>
153   my ($self, $line) = @_;
154   my @args = split /\s+/, $line;
155   my $call = $self->call;
156   my $user = $self->user;
157   my @out;
158
159   # check privileges
160   return (1, $self->msg('e5')) if $self->priv &lt; 5;
161
162   ....
163   ....
164   some perl code here
165   ....
166   ....
167   return (1, @out);
168                 </pre>
169
170                 <li>$line (in this example) is the rest of the line after the command (as a string).
171
172                 <p><li>You are responsible for maintaining user security. If you have
173                 a command that does something a normal system shouldn't be allowed to
174                 do or see, there is $self->priv (using the above example) which gives
175                 you the running privilege level of the channel. USE IT!
176
177                 <p><li>The privilege levels used in the standard code are:-
178
179                 <p>0 - is the normal user privilege.
180                 <p>1 - is the remote user privilage (you need to be at least 1 to get
181                   any output from an <tt>rcmd</tt>).
182                 <p>5 - is the normal external sysop privilege, give this to commands that
183                   you are prepared to let non-local sysops use.
184                 <p>8 - a <em>very</em> trusted, probably internet rather than radio connected
185                   remote sysop.
186                 <p>9 - the do anything console privilege. 
187                 
188                 <p>The sysop privilege is for things that you are prepared for remote
189                 sysops and clusters to do or see.
190                 
191                 <p>A console privilege can only be executed locally (at least if you have
192                 correctly installed the client program in inetd or ax25d).
193                 
194                 <p>The set/priv command can only be executed by a console privileged 
195                 session.
196
197                 <p><li>You must return a list with a 0 or 1 as the first element. 1
198                 means success and 0 means fail. Each element of the list which follows
199                 is assumed to be one line for output. Don't put \n characters at the
200                 end of an element (the client will put the correct one in if required
201                 [but see below]).
202                 
203                 <p><li><b>DO NOT</b>send output direct to the user unless you <em>really</em>
204                 mean it (i.e. it is never appropriate for this command to be used remotely
205                 as an <tt>rcmd</tt> or from some kind of batch or cron file.
206
207                 <p>What you do instead is create a list using
208                 <pre>
209 my @out;
210         </pre> 
211                 and then <tt>push</tt> stuff onto it. Each element on the list will
212                 become a line of output. For exmaple:-
213                 <pre>
214 #
215 # set a user's password
216 #
217 # Copyright (c) 1998 Iain Phillips G0RDI
218 # 21-Dec-1998
219 #
220 # Syntax:       set/pass &lt;password> &lt;callsign>
221 #
222   
223 my ($self, $line) = @_;
224 my @args = split /\s+/, $line;
225 my $call;
226 my $pass = shift @args;
227 my @out;
228 my $user;
229 my $ref;
230   
231 return (1, $self->msg('e5')) if $self->priv &lt; 9;
232   
233 foreach $call (@args) {
234     $call = uc $call;
235     if ($ref = DXUser->get_current($call)) {
236         $ref->passwd($pass);
237             $ref->put();
238                 push @out, $self->msg("password", $call);
239         } else {
240                 push @out, $self->msg('e3', 'User record for', $call);
241         }
242 }
243 return (1, @out);
244             </pre>
245                 a more complicated example:-
246                 <pre>
247 #
248 # display the band data
249 #
250 # Copyright (c) 1998 - Dirk Koopman G1TLH
251 #
252 # $Id$
253 #
254
255 #$DB::single = 1;
256
257 my ($self, $line) = @_;
258 my @f = split /\s+/, $line;
259 my @bands;
260 my $band;
261 my @out;
262 my $i;
263
264 if (!$line) {
265         @bands = sort { Bands::get($a)->band->[0] &lt;=> Bands::get($b)->band->[0] } Bands::get_keys();
266         push @out, "Bands Available:-";
267         foreach $band (@bands) {
268                 my $ref = Bands::get($band)->band;
269                 my $s = sprintf "%10s: ", $band;
270                 for ($i = 0; $i &lt; $#{$ref}; $i += 2) {
271                         my $from = $ref->[$i];
272                         my $to = $ref->[$i+1];
273                         $s .= ", " if $i;
274                         $s .= "$from -> $to";
275                 }
276                 push @out, $s;
277         } 
278         push @out, "Regions Available:-";
279         @bands = Bands::get_region_keys();
280         foreach $band (@bands) {
281                 my $ref = Bands::get_region($band);
282                 my $s = sprintf("%10s: ", $band ) . join(' ', @{$ref}); 
283                 push @out, $s;
284         }
285 }
286
287 return (1, @out)
288         </pre>
289                 <p><li>As this is perl and it is very easy to alter stuff to get it
290                 correct, I would like to see some intelligent argument processing,
291                 e.g. if you can have one callsign, you can have several. Interpret
292                 your arguments; so for example:-
293
294                 <pre>
295   set/qra jo02lq       - sets your own locator to JO02LQ
296   set/qra g1tlh jo02lq - sets G1TLH's locator (if you are allowed)
297   or
298   show/qra in92jo      - displays the bearing and distance to 
299                          IN92JO using your lat/long or locator
300   show/qra jn56in in92jo  - bearing and distance between two
301                             locators
302         </pre>
303
304                 <p><li>It is important that you remember when you have tie
305                 hashes using MLDBM et al. If you do a
306                 <tt>DXUser->get($call)</tt> you will get a different (older)
307                 thing than the one in <tt>$self->user</tt>. This is almost
308                 certainly NOT what you want if want to modify a user that is
309                 currently connected. Either use <tt>$self->user</tt> or, if
310                 you want another user, use <tt>DXUser->get_current($call)</tt>
311
312                 <p><li>If you want to debug something, start the cluster.pl up thus:-
313                 <pre>
314   perl -d cluster.pl
315   dbg> r
316                 </pre>
317                 Then you can go into debug mode at anytime by using the command :-
318                 <pre> 
319   debug
320         </pre>
321   or you can put the line:-
322                 <pre>
323   $DB::single = 1;
324                 </pre>
325                 in an appropriate place in a command. This will only have an effect
326                 if you are running in perl debug mode.
327                 
328                 <p>If all else fails (actually it is very simple), just stick print
329                   commands in everywhere and the output will appear on the cluster.pl
330                   screen.
331
332                 <p><li>Anything you output with a > as the last character is taken to
333                 mean that this is a prompt and will not have a \r or \n appended to
334                 it in the client for telnet sessions (only).
335
336                 <p><li>help is kept in <tt>/spider/cmd/Command_&lt;lang>.hlp</tt> files.
337                 The format of the help files should be self explanatory, but they are
338                 explained further in the files themselves.
339
340                 <p><li>PLEASE add your new commands to the Commands_*.hlp file so that
341                 people know about and how to use them!
342
343         </ol>
344
345         <h4>Editting the source</h4>
346         
347         I suppose this has to be discussed but although I may have confused some of you, I 
348         insist on the following formatting conventions:-
349
350         <ol>
351                 <p><li>All white space to left of a line shall be tabs.
352                 <p><li>A tab shall be 4 characters (unless it is 8) (I use 4). Anything you see
353                 with multiples of 2 spaces will be reformatted next time I edit it. 
354                 <p><li>You <b><u><i>WILL</i></u></b>use the one true (documented) bracing method as 
355                 documented in K & R and all the 'official' perl books.
356         </ol>
357
358         <p>I have been experimenting with editors and tabwidths and have settled on 
359           <a href="http://www.xemacs.org">XEmacs</a>. You can get a copy from the 
360           <a href="ftp://contrib.redhat.com">RedHat Contrib</a> ftp site for your version
361           of Redhat. I use the following parameters in my .emacs file.
362
363           <pre>
364   ;; End of Options Menu Settings
365   (custom-set-variables
366    '(cperl-electric-parens t)
367    '(cperl-auto-newline t)
368    '(cperl-electric-linefeed t)
369    '(cperl-hairy t)
370    '(tab-width 4)
371    '(cperl-indent-level 4)
372    '(cperl-brace-offset 0)
373    '(cperl-continued-brace-offset -4)
374    '(cperl-label-offset -4)
375    '(cperl-merge-trailing-else nil)
376    '(cperl-continued-statement-offset 4)
377   )
378         </pre>
379
380         I also have all the fancy colouring on (don't know what sets that) but this is 
381         what I have in .xemacs-options file:-
382
383         <pre>
384   ;; -*- Mode: Emacs-Lisp -*-
385
386   (setq options-file-xemacs-version '(20 4))
387     (setq-default case-fold-search t)
388     (setq-default overwrite-mode nil)
389       (setq-default case-fold-search t)
390     (setq-default case-replace t)
391       (setq-default zmacs-regions t)
392     (setq-default mouse-yank-at-point t)
393     (setq-default require-final-newline t)
394     (setq-default next-line-add-newlines nil)
395     (setq-default teach-extended-commands-p t)
396     (setq-default teach-extended-commands-timeout 4)
397     (setq-default debug-on-error nil)
398     (setq-default debug-on-quit nil)
399     (setq-default lpr-switches nil)
400     (setq-default ps-print-color-p t)
401     (setq-default ps-paper-type 'letter)
402     (setq-default get-frame-for-buffer-default-instance-limit nil)
403     (setq-default temp-buffer-show-function 'show-temp-buffer-in-current-frame)
404       (setq-default font-lock-auto-fontify t)
405     (setq-default font-lock-use-fonts nil)
406     (setq-default font-lock-use-colors '(color))
407     (setq-default font-lock-maximum-decoration t)
408     (setq-default font-lock-maximum-size 256000)
409     (setq-default font-lock-mode-enable-list nil)
410     (setq-default font-lock-mode-disable-list nil)
411     (require 'font-lock)
412     (remove-hook 'font-lock-mode-hook 'turn-on-fast-lock)
413     (remove-hook 'font-lock-mode-hook 'turn-on-lazy-shot)
414     (require 'paren)
415     (paren-set-mode 'blink-paren)
416     (if (featurep 'scrollbar) (progn (add-spec-list-to-specifier scrollbar-width 'nil) (add-spe$
417     (add-spec-list-to-specifier modeline-shadow-thickness '((global (nil . 2))))
418     (setq-default truncate-lines nil)
419     (setq-default bar-cursor nil)   
420       (setq-default buffers-menu-max-size 25)
421     (setq-default complex-buffers-menu-p nil)
422     (setq-default buffers-menu-sort-function 'sort-buffers-menu-by-mode-then-alphabetically)
423     (setq-default buffers-menu-grouping-function 'group-buffers-menu-by-mode-then-alphabeticall$
424     (setq-default buffers-menu-submenus-for-groups-p nil)
425     (setq-default font-menu-ignore-scaled-fonts t)
426     (setq-default font-menu-this-frame-only-p nil)
427     (if (featurep 'toolbar) (progn (set-default-toolbar-position 'top) (add-spec-list-to-specif$
428     (setq-default mouse-avoidance-mode nil)
429     (setq-default browse-url-browser-function 'browse-url-w3)
430     </pre>
431
432         I also use <a href="../download/cperl-mode.el.4.19.gz">cperl-mode.el.4.19</a> which I got from
433         <a href="http://www.cpan.org">CPAN</a> for the auto formatting of the perl as I write it. Some
434         of its habits are rather peculiar, but you can either switch them off or learn to live with them
435         as I did. I installed my copy in <b>/usr/lib/xemacs/site-lisp</b>. 
436
437         <p>XEmacs runs perfectly happily on the console as well as under X.
438
439 <!-- Standard Footer!! -->
440         <p>&nbsp;</p>
441         <p>
442           <FONT COLOR="#606060"><hr></font>
443         <font color="#FF0000" size=-2>
444           Copyright &copy; 1998 by Dirk Koopman G1TLH. All Rights Reserved<br>
445         </font>
446         <font color="#000000" size=-2>$Id$</font>
447   </body>
448 </html>