Programming New Commands

From: djk Date: Wed, 23 Dec 1998 18:35:55 +0000 (+0000) Subject: added program.html X-Git-Tag: R_1_16^0 X-Git-Url: http://dxcluster.org/gitweb/gitweb.cgi?a=commitdiff_plain;h=69003f56e5249357c746999c2feec5f44c258472;p=spider.git added program.html --- diff --git a/html/program.html b/html/program.html new file mode 100644 index 00000000..6217a198 --- /dev/null +++ b/html/program.html @@ -0,0 +1,348 @@ + + + + Programming New Commands + + + + + + + + +

Programming New Commands

+ + + +

Dirk Koopman G1TLH

+ + +Last modified: Wed Dec 23 18:27:06 GMT 1998 + +

Introduction

+ + All the commands in the DXSpider system are 'soft', that is they are bits of + perl code that are put into specific places in the /spider directory tree. + +

By putting them in a specific place and calling them <command>.pl, they become + commands - in real time. Such is the magic of + perl. + +

Directory Structure

+ + The directory structure is very simple:- + + + + + + + + + + + + + + +

/spider	the main directory
/spider/data	where generated and/or reference data goes
/spider/data/spots/<year>/<day>.dat	one day's worth of spots
/spider/data/debug/<year>/<day>.dat	one day's worth of console debugging
/spider/data/log/<year>/<month>.dat	one month's worth of Logging info including things like rcmd, announces, talks etc
/spider/data/wwv/<year>/<month>.dat	one month's worth of WWV
/spider/msg	the messages directory
/spider/packclus/files	the files directory
/spider/packclus/bulletin	the bulletins directory
/spider/perl	where the issued program code lives
/spider/local	where your experimental/site specific programs go
/spider/cmd	where the issued command code lives
/spider/local_cmd	where your experimental command code goes

+ +

A command is put in full as a file under the 'cmd' directory tree, for example, + announce lives in /spider/cmd/announce.pl and show/dx lives + in /spider/cmd/show/dx.pl. + +

In general terms I don't like the habit of the standard packet cluster software has + of taking the DEC VMS command paradigm to the extreme that it has. So I have adopted + the convention of separating commands from arguments. So sh/dx/10 20 is input + on the DXSpider system as sh/dx 10 on 20m. This is rather contentious. + +

In order to maintain a larger level of compatibility, there is an Aliases which + lives in /spider/cmd (or can be overidden by one in local_cmd). This file + takes standard expressions, parses command lines and produces DXSpider compatible versions + of the old Packet Cluster commands. Currently, however, it doesn't do a 100% job because + the functionality of the new commands is different (and hopefully better). + +

In addition, in the /spider/perl directory (overidden by ...) there is + the Messages file. This is the file where all the system messages will be stored + (because of laziness on my part this isn't currently the case). You will see instances + of its use like $self->msg(<string> [,$arg..]). This call uses + $self to determine what language you are in, to return you the correct message. + The way arguments are passed to the routine, mean that you can reorder the arguments + in your message to suit your language without changing the actual code. + +

When you roll your own commands, put + your messages in your own copy of the Messages file and don't forget + to send me the patches for that as well the command itself. + +

When I issue a new version or patches for an existing version then only files in + the /spider/cmd and /spider/perl directories will normally be altered. + Occasionally, one or two of the reference files in /spider/data may be altered. + The only files likely to be affected are bands.pl and prefix_data.pl. + +

As it says in the next section, PLEASE experiment in the local directories! It will + save a lot of pain when patching code. Having said that, if you have been playing, then + remember to remove or rename any files with new releases that claim to have incorporated + your modifications, otherwise it will continue to use the old ones in your local + directories! + +

Hints, Tips and Exhortations

+ +

Every command that can used on the command line lives in either + this directory ('cmd') or in a local version ('local_cmd'). You are + cajoled or ordered not to and generally discouraged from altering the + commands in the 'cmd' directory. You can put local copies in the + 'local_cmd' directory and they will override the standard ones. + +
If you want to play, do it in the 'local_cmd' directory. It's + very easy and reasonably safe. You can override a command whilst the + cluster is running. Compilation errors will simply give you error + messages, it won't stop the cluster running - this only happens if you + mess with the internals to the extent that it gets confused... + +
A command is a piece of perl, it is simply a small snippet of + program that is dynamically loaded into the cluster on invocation from + the command line. The last modification time is used to determine + whether to reload it. + +
New (or altered) commands are available for test the moment you + save them. + +
A command is placed into the appropriate directory with a '.pl' + appended to the end. So the 'show/qra' command lives in + 'cmd/show/qra.pl' (or a local version would be in + 'local_cmd/show/qra.pl'. + +
For the security conscious, potentially dubious + characters command line args (i.e. not [A-Za-z0-9_/]) are + converted to their hex equivalents. This will almost certainly + mean that the user will get an error message (unless you have + your secret squirrel hat on and have deliberately put such + commands up [in 'local_cmd' of course]). + +
The snippets of program you put here are wrapped in an eval { } + and are subroutines derived from the DXChannel class. They effectively + the following declaration :- +
```
+  sub Emb_($self, $args)
+  {
+     ...
+     your code here
+     ...
+  }
+		
```
+ +
slash characters are replaced by '_' so the equivalent name for + 'show/qth' is 'Emb_show_qth'. + +
you would normally do a 'my ($self, $line) = @_;' as the first + thing. There are a complete set of accessors for DXUser, DXCommandmode, + DXChannel and most other classes and these are the recommended way of getting at + the contents of these classes. A fairly standard start might be:- +
```
+  my ($self, $line) = @_;
+  my @args = split /\s+/, $line;
+  my $call = $self->call;
+  my $user = $self->user;
+  my @out;
+
+  # check privileges
+  return (1, $self->msg('e5')) if $self->priv < 5;
+
+  ....
+  ....
+  some perl code here
+  ....
+  ....
+  return (1, @out);
+		
```
+ +
$line (in this example) is the rest of the line after the command (as a string). + +
You are responsible for maintaining user security. If you have + a command that does something a normal system shouldn't be allowed to + do or see, there is $self->priv (using the above example) which gives + you the running privilege level of the channel. USE IT! + +
The privilege levels used in the standard code are:- + +
0 - is the normal user privilege. +
1 - is the remote user privilage (you need to be at least 1 to get + any output from an rcmd). +
5 - is the normal external sysop privilege, give this to commands that + you are prepared to let non-local sysops use. +
8 - a very trusted, probably internet rather than radio connected + remote sysop. +
9 - the do anything console privilege. + +
The sysop privilege is for things that you are prepared for remote + sysops and clusters to do or see. + +
A console privilege can only be executed locally (at least if you have + correctly installed the client program in inetd or ax25d). + +
The set/priv command can only be executed by a console privileged + session. + +
You must return a list with a 0 or 1 as the first element. 1 + means success and 0 means fail. Each element of the list which follows + is assumed to be one line for output. Don't put \n characters at the + end of an element (the client will put the correct one in if required + [but see below]). + +

DO NOTsend output direct to the user unless you really + mean it (i.e. it is never appropriate for this command to be used remotely + as an rcmd or from some kind of batch or cron file. + +

What you do instead is create a list using +

+my @out;
+

+ and then push stuff onto it. Each element on the list will + become a line of output. For exmaple:- +

+#
+# set a user's password
+#
+# Copyright (c) 1998 Iain Phillips G0RDI
+# 21-Dec-1998
+#
+# Syntax:	set/pass <password> <callsign>
+#
+  
+my ($self, $line) = @_;
+my @args = split /\s+/, $line;
+my $call;
+my $pass = shift @args;
+my @out;
+my $user;
+my $ref;
+  
+return (1, $self->msg('e5')) if $self->priv < 9;
+  
+foreach $call (@args) {
+    $call = uc $call;
+    if ($ref = DXUser->get_current($call)) {
+        $ref->passwd($pass);
+  	    $ref->put();
+  		push @out, $self->msg("password", $call);
+  	} else {
+  		push @out, $self->msg('e3', 'User record for', $call);
+  	}
+}
+return (1, @out);
+

+ a more complicated example:- +

+#
+# display the band data
+#
+# Copyright (c) 1998 - Dirk Koopman G1TLH
+#
+# $Id$
+#
+
+#$DB::single = 1;
+
+my ($self, $line) = @_;
+my @f = split /\s+/, $line;
+my @bands;
+my $band;
+my @out;
+my $i;
+
+if (!$line) {
+	@bands = sort { Bands::get($a)->band->[0] <=> Bands::get($b)->band->[0] } Bands::get_keys();
+	push @out, "Bands Available:-";
+	foreach $band (@bands) {
+		my $ref = Bands::get($band)->band;
+		my $s = sprintf "%10s: ", $band;
+		for ($i = 0; $i < $#{$ref}; $i += 2) {
+			my $from = $ref->[$i];
+			my $to = $ref->[$i+1];
+			$s .= ", " if $i;
+			$s .= "$from -> $to";
+		}
+		push @out, $s;
+	} 
+	push @out, "Regions Available:-";
+	@bands = Bands::get_region_keys();
+	foreach $band (@bands) {
+		my $ref = Bands::get_region($band);
+		my $s = sprintf("%10s: ", $band ) . join(' ', @{$ref}); 
+		push @out, $s;
+	}
+}
+
+return (1, @out)
+

As this is perl and it is very easy to alter stuff to get it + correct, I would like to see some intelligent argument processing, + e.g. if you can have one callsign, you can have several. Interpret + your arguments; so for example:- + +

+  set/qra jo02lq       - sets your own locator to JO02LQ
+  set/qra g1tlh jo02lq - sets G1TLH's locator (if you are allowed)
+  or
+  show/qra in92jo      - displays the bearing and distance to 
+                         IN92JO using your lat/long or locator
+  show/qra jn56in in92jo  - bearing and distance between two
+                            locators
+

+ +

It is important that you remember when you have tie + hashes using MLDBM et al. If you do a + DXUser->get($call) you will get a different (older) + thing than the one in $self->user. This is almost + certainly NOT what you want if want to modify a user that is + currently connected. Either use $self->user or, if + you want another user, use DXUser->get_current($call) + +
If you want to debug something, start the cluster.pl up thus:- +
```
+  perl -d cluster.pl
+  dbg> r
+		
```
+ Then you can go into debug mode at anytime by using the command :- +
```
 
+  debug
+        
```
+ or you can put the line:- +
```
+  $DB::single = 1;
+		
```
+ in an appropriate place in a command. This will only have an effect + if you are running in perl debug mode. + +
If all else fails (actually it is very simple), just stick print + commands in everywhere and the output will appear on the cluster.pl + screen. + +
Anything you output with a > as the last character is taken to + mean that this is a prompt and will not have a \r or \n appended to + it in the client for telnet sessions (only). + +
help is kept in /spider/cmd/Command_.hlp files. + The format of the help files should be self explanatory, but they are + explained further in the files themselves. + +
PLEASE add your new commands to the Commands_*.hlp file so that + people know about and how to use them! + +

+ + +