From 69003f56e5249357c746999c2feec5f44c258472 Mon Sep 17 00:00:00 2001 From: djk Date: Wed, 23 Dec 1998 18:35:55 +0000 Subject: [PATCH] added program.html --- html/program.html | 348 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 348 insertions(+) create mode 100644 html/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:- + + + + + + + + + + + + + + +
/spiderthe main directory
/spider/datawhere generated and/or reference data goes
/spider/data/spots/<year>/<day>.datone day's worth of spots
/spider/data/debug/<year>/<day>.datone day's worth of console debugging
/spider/data/log/<year>/<month>.datone month's worth of Logging info including things like rcmd, announces, talks etc
/spider/data/wwv/<year>/<month>.datone month's worth of WWV
/spider/msgthe messages directory
/spider/packclus/filesthe files directory
/spider/packclus/bulletinthe bulletins directory
/spider/perlwhere the issued program code lives
/spider/localwhere your experimental/site specific programs go
/spider/cmdwhere the issued command code lives
/spider/local_cmdwhere 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

+ +
    + +

  1. 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. + +

  2. 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... + +

  3. 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. + +

  4. New (or altered) commands are available for test the moment you + save them. + +

  5. 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'. + +

  6. 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]). + +

  7. 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
    +     ...
    +  }
    +		
    + +

  8. slash characters are replaced by '_' so the equivalent name for + 'show/qth' is 'Emb_show_qth'. + +

  9. 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);
    +		
    + +
  10. $line (in this example) is the rest of the line after the command (as a string). + +

  11. 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! + +

  12. 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. + +

  13. 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]). + +

  14. 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)
    +        
    +

  15. 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
    +        
    + +

  16. 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) + +

  17. 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. + +

  18. 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). + +

  19. 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. + +

  20. PLEASE add your new commands to the Commands_*.hlp file so that + people know about and how to use them! + +
+ + +

 

+

+


+ + Copyright © 1998 by Dirk Koopman G1TLH. All Rights Reserved
+
+ $Id$ + + -- 2.43.0