html/program.html

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