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

Introduction

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

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!