1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
4 <title>Programming New Commands</title>
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">
13 <body TEXT="#000000" LINK="#0000ff" VLINK="#800080" BGCOLOR="#FFFFFF">
14 <FONT COLOR="#606060">
16 <h2>Programming New Commands</h2>
21 <address><a href="mailto:djk@tobit.co.uk">Dirk Koopman G1TLH</a></address>
23 <!-- Created: Sun Dec 13 20:25:14 GMT 1998 -->
25 Last modified: Mon Dec 28 23:13:21 GMT 1998
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.
32 <p>By putting them in a specific place and calling them <command>.pl, they become
33 commands - in real time. Such is the magic of
34 <a href="http://www.perl.com">perl</a>.
36 <h4>Directory Structure</h4>
38 The directory structure is very simple:-
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/<year>/<day>.dat</td><td>one day's worth of spots</td></tr>
43 <tr><td>/spider/data/debug/<year>/<day>.dat</td><td>one day's worth of console debugging</td></tr>
44 <tr><td>/spider/data/log/<year>/<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/<year>/<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>
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>.
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.
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).
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(<string> [,$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.
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.
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>.
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
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.
97 <h4>Hints, Tips and Exhortations</h4>
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.
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...
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.
118 <p><li>New (or altered) commands are available for test the moment you
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'.
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]).
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 :-
137 sub Emb_<cmdname>($self, $args)
145 <p><li>slash characters are replaced by '_' so the equivalent name for
146 'show/qth' is 'Emb_show_qth'.
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:-
153 my ($self, $line) = @_;
154 my @args = split /\s+/, $line;
155 my $call = $self->call;
156 my $user = $self->user;
160 return (1, $self->msg('e5')) if $self->priv < 5;
170 <li>$line (in this example) is the rest of the line after the command (as a string).
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!
177 <p><li>The privilege levels used in the standard code are:-
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
186 <p>9 - the do anything console privilege.
188 <p>The sysop privilege is for things that you are prepared for remote
189 sysops and clusters to do or see.
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).
194 <p>The set/priv command can only be executed by a console privileged
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
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.
207 <p>What you do instead is create a list using
211 and then <tt>push</tt> stuff onto it. Each element on the list will
212 become a line of output. For exmaple:-
215 # set a user's password
217 # Copyright (c) 1998 Iain Phillips G0RDI
220 # Syntax: set/pass <password> <callsign>
223 my ($self, $line) = @_;
224 my @args = split /\s+/, $line;
226 my $pass = shift @args;
231 return (1, $self->msg('e5')) if $self->priv < 9;
233 foreach $call (@args) {
235 if ($ref = DXUser->get_current($call)) {
238 push @out, $self->msg("password", $call);
240 push @out, $self->msg('e3', 'User record for', $call);
245 a more complicated example:-
248 # display the band data
250 # Copyright (c) 1998 - Dirk Koopman G1TLH
257 my ($self, $line) = @_;
258 my @f = split /\s+/, $line;
265 @bands = sort { Bands::get($a)->band->[0] <=> 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 < $#{$ref}; $i += 2) {
271 my $from = $ref->[$i];
272 my $to = $ref->[$i+1];
274 $s .= "$from -> $to";
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});
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:-
295 set/qra jo02lq - sets your own locator to JO02LQ
296 set/qra g1tlh jo02lq - sets G1TLH's locator (if you are allowed)
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
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>
312 <p><li>If you want to debug something, start the cluster.pl up thus:-
317 Then you can go into debug mode at anytime by using the command :-
321 or you can put the line:-
325 in an appropriate place in a command. This will only have an effect
326 if you are running in perl debug mode.
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
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).
336 <p><li>help is kept in <tt>/spider/cmd/Command_<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.
340 <p><li>PLEASE add your new commands to the Commands_*.hlp file so that
341 people know about and how to use them!
345 <h4>Editting the source</h4>
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:-
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.
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.
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)
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)
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:-
384 ;; -*- Mode: Emacs-Lisp -*-
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)
412 (remove-hook 'font-lock-mode-hook 'turn-on-fast-lock)
413 (remove-hook 'font-lock-mode-hook 'turn-on-lazy-shot)
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)
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>.
437 <p>XEmacs runs perfectly happily on the console as well as under X.
439 <!-- Standard Footer!! -->
442 <FONT COLOR="#606060"><hr></font>
443 <font color="#FF0000" size=-2>
444 Copyright © 1998 by Dirk Koopman G1TLH. All Rights Reserved<br>
446 <font color="#000000" size=-2>$Id$</font>