@database MM_Poll.guide
@master MM:Rexx/MM_Poll.guide
@$VER: MM_Poll.guide v1.01 (2.10.96)
@author "Simon Speight"
@(c) "MM_Poll v1.01 © Simon Speight 1996"
@wordwrap
@index Index
@remark +----------------------------------------------------------+
@remark | Created with Heddley v1.1 (c) Edd Dumbill 1994           |
@remark | ...and edited by hand, by Simon, in GoldED to remove all |
@remark | the crap Heddley added of its own accord...              |
@remark +----------------------------------------------------------+

@node "Main" "MM_Poll v1.01 - © Simon Speight 1996"
@next "about"
                                      -=-
                             -+-+-+-+-+-+-+-+-+-+-
                                  MM_Poll.rexx
                                     v1.01
                              © Simon Speight 1996
                             -+-+-+-+-+-+-+-+-+-+-
                                      -=-
      **** Please read configuration chapter if upgrading from v1.0 ****

    @{"     About     " link "about" 0}  >> What is MM_Poll, and what does it do?
    @{" Requirements  " link "requirements" 0}  >> What do I need to use MM_Poll?
    @{" Installation  " link "installation" 0}  >> How do I install MM_Poll onto my system?
    @{" Configuration " link "configuration" 0}  >> How do I configure MM_Poll?
    @{"     Usage     " link "usage" 0}  >> How do I use MM_Poll?
    @{"    Errors     " link "errors" 0}  >> What went wrong?  What does it mean?
    @{"     Legal     " link "legal" 0}  >> What can I and can't I do with MM_Poll?
    @{"    History    " link "history" 0}  >> How did MM_Poll get to where it is now?
    @{"    Credits    " link "credits" 0}  >> Who do I have to thank for MM_Poll?
    @{"    Contact    " link "contact" 0}  >> How do I contact the author?

@endnode

@node "about" "About MM_Poll"
@next "requirements"
@prev "contact"

                                 @{u}About MM_Poll@{uu}


    MM_Poll is an ARexx script for use with Pino Aliberti's superb tosser @{i}Mail Manager@{ui}.

    It is designed to allow, and facilitate, polling from within @{i}Mail Manager@{ui}, whilst giving you a whole load of options and features as well.  Thus, it is primarily aimed at points, though there is no reason why nodes shouldn't use it.

    MM_Poll will:

* show the addresses of nodes for which you have mail waiting (Crash, FReq or FLO).

* also show you your (configured) Boss addresses.

* accept AKA addresses, and ignore any mail waiting for them.

* output 4D or 5D addresses.

* allow you to set pre-defined Options for any command you like.


    The idea was given to me by a Spot ARexx script called "Poll Handler" written by Per Jonsson.  However, I want to make it @{b}very@{ub} clear that this is a brand new script, and was written from the ground up.  This is @{b}not@{ub} a conversion of @{i}Poll Handler@{ui}, it was merely inspired by it, and actually offers many features @{i}Poll Handler@{ui} doesn't.

(Please also read the @{"Legal" link "legal" 0} chapter before using this script)

@endnode

@node "requirements" "System requirements"
@next "installation"
@prev "about"

                              @{u}System requirements@{uu}


    In order to run this script, you will need the following:

- a @{b}registered@{ub} copy of @{i}Mail Manager@{ui}.

- ARexx installed and running.

- the `rexxsupport.library' in your LIBS: assign.

- a properly set-up (see @{"Configuration" link "configuration" 0}) config file (example in this archive), called `MM:Config/MM_Poll.cfg'.

- [optional] an installed Traplist nodelist.

@endnode

@node "installation" "Installing MM_Poll"
@next "configuration"
@prev "requirements"

                                  @{u}Installation@{uu}


    Installing MM_Poll is very simple:

- copy the config file to `MM:Config/' and edit to your needs (see @{"Configuration" link "configuration"0}).

- copy the script itself to a directory of your choice, though `MM:Rexx/' seems the obvious choice.


    Here is a suggestion for how MM_Poll could appear in your @{i}Mail Manager@{ui} config file:

#AREASMENU      "MM_Poll"       "Sys:Rexxc/RX MM:Rexx/MM_Poll.rexx"      "P"


    This is how I have it set up, though obviously you may wish to change it.

@endnode

@node "configuration" "How to configure MM_Poll"
@next "usage"
@prev "installation"

                                 @{u}Configuration@{uu}


**** IMPORTANT: FMAILER from v1.0 is now called RMAILER. Read more below. ****


    And now we come to the heart of the matter - the config file.  This must be placed in MM:Config/ and be called MM_Poll.cfg.  It is simply a text file, so just load the example config in this archive into any text editor and edit it to your needs (and you will need to - the example config is unlikely to be any use to you as it is).

    Comments can be included, so long as a) they have their own line, and b) they do not begin with the # character (any line which doesn't begin with # is ignored, you see).  To be perfectly honest, comments only serve to slow down the config parsing stage of the script, so avoid them if you can.

    Please, @{b}please@{ub} stick rigidly to the command structures given in the chapters below for each keyword - failure to do so @{u}will@{uu} cause MM_Poll to go wrong.  I have done my best to trap any errors that might occur, but inevitably some will slip through.

    In particular, make sure that all keywords that require parameters (an address, perhaps) have the entire parameter surrounded with speech marks.  Also, all addresses given anywhere in the config @{b}MUST BE 4D@{ub}!  IE, @{b}2:259/65@{ub} is not acceptable - it must be @{b}2:259/65.0@{ub}.

    Keywords may appear in any order in the config file, though for reasons of sanity, I suggest you keep all BOSSes together, all AKAs together etc.

    For more info on the particular keywords, select one of the following:

    @{"     BOSS     " link "boss" 0}
    @{"     AKA      " link "aka" 0}
    @{"    OPTION    " link "option" 0}
    @{"    MAILER    " link "mailer" 0}
    @{"   BMAILER    " link "bmailer" 0}
    @{"   RMAILER    " link "rmailer" 0}
    @{"   CMAILER    " link "cmailer" 0}
    @{"   FMAILER    " link "fmailer" 0}
    @{" OUTBOUND_DIR " link "outbound_dir" 0}
    @{"    DOMAIN    " link "domain" 0}
    @{"      4D      " link "4d" 0}
    @{"  NONODELIST  " link "nonodelist" 0}

@endnode

@node "usage" "How to use MM_Poll"
@next "errors"
@prev "configuration"

                               @{u}How to use MM_Poll@{uu}


    Using MM_Poll is very simple.  Once you have @{"configured" link "configuration" 0} it, the hard part is done!  (This brief guide through using MM_Poll assumes you have configured it already.)

    There are no parameters to give to MM_Poll, so to get started just execute the script.

    Having done so (and assuming nothing goes wrong - see @{"Errors" link "errors" 0} for a list of what could go wrong) you will be presented with a window containing a listview and a couple of gadgets.  In the listview will be any @{"Options" link "option" 0} you have configured, the @{"Boss" link "boss" 0} addresses you have specified, and any Crash mails, File Requests or FLO files you have waiting in your configured @{"outbound directory" link "outbound_dir" 0} (if none of this makes sense, read the @{"Configuration" link "configuration" 0} chapter again!).  At the start of each entry in the list, you will see `@{b}[X]@{ub}', where X is one of five letters; `O', `B', `C', `R', or `F'.  This letter tells you what exactly that entry is; an @{u}O@{uu}ption, @{u}B@{uu}oss, @{u}C@{uu}rash mail, File @{u}R@{uu}equest or @{u}F@{uu}LO respectively.

    Select one of these with the mouse or cursor keys and then click on `OK'.  Depending on what you have selected, a number of different things could happen.

* if it was an Option, then the appropriate command will be executed, and the script exited (once the command returns).

* if it was a Boss, the address of that Boss is inserted into the @{"MAILER" link "mailer" 0} string (or @{"BMAILER" link "bmailer" 0} string if it has been configured) and executed.

* if it was a Crash, FReq or FLO (and if the @{"NONODELIST" link "nonodelist" 0} option @{b}hasn't@{ub} been set) then another window will appear with some information from the nodelist about the node you are about to call.  (setting NONODELIST skips this window)  Click on `Call' to call that node, or `Exit' to quit.  If you click `Call' your configured @{"MAILER" link "mailer" 0} command will be executed with that node's address in it (unless you have configured the @{"CMAILER" link "cmailer" 0}/@{"RMAILER" link "rmailer" 0}/@{"FMAILER" link "fmailer" 0} strings in which case they will be used instead).

    And that's all there is to it really!

@endnode

@node "errors" "Possible error messages from MM_Poll"
@next "legal"
@prev "usage"

                                 @{u}Error messages@{uu}


    Here is a list of all the error messages MM_Poll could come out with, and what they mean:

`@{b}Error:@{ub} @{i}Mail Manager ARexx port not found.@{ui}'

    Either Mail Manager is not running, or you have not enabled ARexx ports in your MUI preferences.

`@{b}Error:@{ub} @{i}rexxsupport.library not found.@{ui}'

    MM_Poll needs some functions from the rexxsupport.library.  If this error appears, it has not been found in your LIBS: assign.

`@{b}Error:@{ub} @{i}configuration file not found.@{ui}'

    MM_Poll looks for the file `@{b}MM:Config/MM_Poll.cfg@{ub}' - if it doesn't find it, you will see this error.

`@{b}Error:@{ub} @{i}Mail Manager iconified.@{ui}'

    Self-explanatory this one.  MM_Poll cannot operate if @{i}Mail Manager@{ui} is iconified, as it uses MUI requesters that are called through @{i}Mail Manager@{ui}.

`@{b}Configuration error:@{ub} @{i}OPTION #X is not correctly configured.@{ui}'

    There is a problem with your Xth configured @{"OPTION" link "option" 0}.  Check for speech marks, and correct positioning of square brackets.

`@{b}Configuration error:@{ub} @{i}BOSS #X is not a valid 4D FTN address.@{ui}'

    Your Xth configured @{"BOSS" link "boss" 0} is not a valid address.  All addresses in the config file @{u}must@{uu} be 4D, and be of the form @{b}<zone>:<net>/<node>.<point>@{ub}

`@{b}Configuration error:@{ub} @{i}AKA #X is not a valid 4D FTN address.@{ui}'

    Your Xth configured @{"AKA" link "aka" 0} is not a valid address.  See above.

`@{b}Configuration error:@{ub} @{i}DOMAIN #X is incorrectly configured.@{ui}'

    Your Xth configured @{"DOMAIN" link "domain" 0} is not in the right form.  It should be in the form `@{b}<domain name>/<zone value>@{ub}'

`@{b}Configuration error:@{ub} @{i}no MAILER string specified.@{ui}'

    You haven't told MM_Poll how to call out by giving it a @{"MAILER" link "mailer" 0} string.  This is a mandatory string, even if you plan to use @{"BMAILER" link "bmailer" 0}, @{"RMAILER" link "rmailer" 0} or @{"CMAILER" link "cmailer" 0} instead.

`@{b}Configuration error:@{ub} @{i}no OUTBOUND_DIR specified.@{ui}'

    You haven't told MM_Poll where to look for outgoing crash mails and file requests (see @{"OUTBOUND_DIR" link "outbound_dir" 0}).

`@{b}Error:@{ub} @{i}domain not recognised.@{ui}'

    The zone value of the address you have chosen has not been assigned a domain name (using the @{"DOMAIN" link "domain" 0} keyword) in the configuration file.  Without knowing what domain to append to the address, MM_Poll has stopped.

`@{b}Nodelist error:@{ub} @{i}Unknown Node.@{ui}'

    The node you selected has not been found in the nodelist.  MM_Poll has stopped here as if it couldn't find it, your mailer won't either :-)

`@{b}Nodelist error:@{ub} @{i}Unable to open Nodelist.@{ui}'

    A traplist nodelist could not be found.  If your mailer uses a different nodelist format, then you should specify the @{"NONODELIST" link "nonodelist" 0} switch in the config file.

`@{b}E R R O R !@{ub}  @{i}The command: @{b}<command>@{ub} returned @{b}<DOS return code>@{ub}.@{ui}'

    The command @{b}<command>@{ub} has returned a return code other than 0, which suggests that something has gone wrong.  Check your @{"config" link "configuration" 0}.

`@{b}Invalid option:@{ub} @{i}should never happen.@{ui}'

`@{b}Unknown type:@{ub} @{i}should never happen.@{ui}'

    Either of these would indicate an internal error in the script, and really should never occur.  If they do occur, and you are sure you have not altered the script in any way, then @{"contact" link "contact" 0} me immediately.

@endnode

@node "legal" "Legal matters"
@next "history"
@prev "errors"

                                 @{u}Legal matters@{uu}


    This archive may be spread freely as long as @{u}no@{uu} money is charged to obtain it, and it is kept in its @{b}original@{ub} form (including addition, removal or alteration of data, but excluding archiving method).

    MM_Poll is a @{b}Mailware@{ub} release.  That is the same as freeware (which means that it is free to use, free to obtain, and free to distribute, but I retain the right to be identified as the author of the script) but if you use it, I want you to mail me (see @{"Contact" link "contact" 0} to find out how).

    Pino Aliberti has permission to include this archive with future distributions of @{i}Mail Manager@{ui}, should he wish to do so.


    There is @{b}NO WARRANTY WHATSOEVER@{ub} with this script.  Whilst it has been tested to the best of my ability, I cannot and will not be held responsible for any problems that occur as a result of using it.  By executing the script, you indicate your willingness to accept the responsibility for @{b}all@{ub} outcomes.

@endnode

@node "history" "History of MM_Poll"
@next "credits"
@prev "legal"

                                    @{u}History@{uu}

v1.0 :   First public release.

v1.01:   Very minor update.  Added support for .FLO files.  This was actually incredibly easy to add - although MM_Poll picks up @{b}all@{ub} .FLO files, it ignores any being used to send mail archives without any redesign!  (Because, your boss and his/her AKA's should already be set up...)  Thanks to Torben Danoe for suggesting that one.

@endnode

@node "credits" "Credits and Thanks"
@next "contact"
@prev "history"

                               @{u}Credits and Thanks@{uu}


    My sincere thanks go out to the following people:

* @{b}Per Jonsson@{ub}

    For the Spot ARexx script @{i}Poll Handler@{ui}, the inspiration for MM_Poll.

* @{b}Pino Aliberti@{ub}

    For the superb @{i}Mail Manager@{ui}.

* @{b}Thomas Bickel@{ub}

    For the excellent @{i}Gotcha@{ui} Fidonet mailer, and the way it works, which inspired me (read: forced me :-) ) to add MM_Poll's OPTIONs.

* @{b}Adrian Maggs@{ub}

    For testing and ideas (some great, some impossible :-) ).

* @{b}Robert Hofmann@{ub}

    For the educational value of his scripts! :-)

* @{b}Dan Brooke@{ub}, @{b}Andy Dowds@{ub} and @{b}Alistair Knock@{ub}

    For answering my various and varied ARexx questions (and for coming up with different answers occasionally ;-).

* @{b}Torben Danoe@{ub}

    For suggesting the .FLO file addition.  Cheers Bilbo :-)


    MM_Poll was written entirely by Simon Speight (see @{"Legal" link "legal" 0} for more).

@endnode

@node "contact" "How to contact me"
@next "about"
@prev "credits"

                                    @{u}Contact@{uu}


    If you find this script useful, find any bugs, or have any suggestions to make about it, then I would love to hear from you.  Find me at any one of the following addresses;

    @{b}simons@telecall.co.uk@{ub}
    @{b}2:259/66.34@fidonet@{ub}
    @{b}39:137/12.34@amiganet@{ub}

    You can also find me in the Amiganet echo @{b}MM_AMY@{ub}.

    If anyone wants to see MM_Poll and/or this guide file in their own language and is willing to translate it, then please contact me!

@endnode

@node "boss" "The BOSS keyword"
@next "aka"
@prev "nonodelist"

                                @{u}The BOSS keyword@{uu}


Usage:  @{b}#BOSS "<4D FTN address>"@{ub}

Example: @{b}#BOSS "2:259/65.0"@{ub}


    This keyword specifies an address as one of your BOSS addresses.  What this means in practise is that this address will @{u}always@{uu} appear in the list, and any Crashes, FReqs or FLOs to this address will be ignored (as it would only waste space).

    You @{i}needn't@{ui} have any of these, but you can have as many as you like.

@endnode

@node "aka" "The AKA keyword"
@next "option"
@prev "boss"

                                @{u}The AKA keyword@{uu}


Usage:  @{b}#AKA "<4D FTN address>"@{ub}

Example:  @{b}#AKA "39:137/12.0"@{ub}


    This keyword is kind of the opposite to the BOSS keyword.  Whereas BOSSes always appear in the list, AKAs @{u}never@{uu} appear in the list, and any Crashes, File Requests or FLOs to AKA addresses will be ignored as well.

    As with BOSS, you @{i}needn't@{ui} have any AKAs set up, but you can have as many as you like.

@endnode

@node "option" "The OPTION keyword"
@next "mailer"
@prev "aka"

                               @{u}The OPTION keyword@{uu}


Usage:  @{b}#OPTION "[<label>][<command>]"@{ub}

Example:  @{b}#OPTION "[Run Fubar][Run <>NIL: Fu:Bar/Fubar]"@{ub}

(Please note the @{u}exact@{uu} structure of this keyword - if you get it wrong, it will @{u}not@{uu} work properly.)

    As you can see from above, this keyword has two parts - the label and the command.  The label is the text that you want placed into the list to represent this option.  The command is the actual command you want executed when you select the label from the list.

    No OPTIONs are required by the script, but you may have as many as you require.

@endnode

@node "mailer" "The MAILER keyword"
@next "bmailer"
@prev "option"

                               @{u}The MAILER keyword@{uu}


Usage:  @{b}#MAILER "<mailer command>"@{ub}

Example:  @{b}#MAILER "Trapdoor CALL %n"@{ub}

@{i}This keyword is mandatory.@{ui}

    This keyword specifies the command that should be used to call whichever address you select.  Use @{b}%n@{ub} to indicate where the selected address should be inserted into the command string.

    Please note that the text between the speech marks will be sent @{u}exactly@{uu} as you configure it, and the @{b}%n@{ub} replaced @{u}exactly@{uu} with the address - any spaces in or around it will be preserved, so include them where necessary.

@endnode

@node "bmailer" "The BMAILER keyword"
@next "rmailer"
@prev "mailer"

                              @{u}The BMAILER keyword@{uu}


For usage and example, see @{"MAILER" link "mailer" 0}.


    This keyword specifies a command string to use, instead of the MAILER string, when calling a configured @{b}Boss@{ub} address.

    It is entirely optional, and will only be used if found.

@endnode

@node "rmailer" "The RMAILER keyword"
@next "cmailer"
@prev "bmailer"

                              @{u}The RMAILER keyword@{uu}


For usage and example, see @{"MAILER" link "mailer" 0}.

[In v1.0 this command was known as FMAILER.]

    This keyword specifies a command string to use, instead of the MAILER string, when sending @{b}File Requests@{ub}.

    It is entirely optional, and will only be used if found.

@endnode

@node "cmailer" "The CMAILER keyword"
@next "fmailer"
@prev "rmailer"

                              @{u}The CMAILER keyword@{uu}


For usage and example, see @{"MAILER" link "mailer" 0}.


    This keyword specifies a command string to use, instead of the MAILER string, when sending @{b}Crash mail@{ub}.

    It is entirely optional, and will only be used if found.

@endnode

@node "fmailer" "The FMAILER keyword"
@next "domain"
@prev "cmailer"

                              @{u}The FMAILER keyword@{uu}


For usage and example, see @{"MAILER" link "mailer" 0}.

[This is @{b}not@{ub} the same FMAILER as appeared in v1.0.  That has been renamed as @{"RMAILER" link "rmailer" 0}.]

    This keyword specifies a command string to use, instead of the MAILER string, when sending a @{b}FLO@{ub} file (FLO files contain the name(s) and path(s) of files to be sent in a normal session - ordinarily, these would be your packed mail archives, but they can also be used to send any other type of file - almost like a file attach without the message!).

    It is entirely optional, and will only be used if found.

@endnode

@node "domain" "The DOMAIN keyword"
@next "outbound_dir"
@prev "fmailer"

                               @{u}The DOMAIN keyword@{uu}


Usage:  @{b}#DOMAIN "<domain name>/<zone value>"@{ub}

Example:  @{b}#DOMAIN "fidonet/2"@{ub}


    This keyword is MM_Poll's way of dealing with 5D addresses.  What it basically does is create a link between the given domain name and the given zone value.

    When you select the address to call (and if @{"4D" link "4d" 0} hasn't been set) MM_Poll will look at the zone value of the chosen address (the first number in the address, up to (but not including) the colon), and see if a DOMAIN has been set for that value.  If it finds one, it then appends the corresponding domain name to the address.

    For example, with the line `@{b}#DOMAIN "fidonet/2"@{ub}' in the config, were I to choose the address `@{b}2:259/65.0@{ub}', MM_Poll would append `@{b}@fidonet@{ub}', to give me my final, 5D, address of `@{b}2:259/65.0@fidonet@{ub}' which it would insert into the @{"MAILER" link "mailer" 0} string.

    The example config which came in this archive has been set-up for most major FTN networks anyway, so you may never need to change any of these.

    No DOMAIN lines are required if you are also going to set the @{"4D" link "4d" 0} option.  However, in 5D mode, MM_Poll will not call a domain it does not recognise, so you must have enough DOMAIN lines to cover your needs.

@endnode

@node "outbound_dir" "The OUTBOUND_DIR keyword"
@next "4d"
@prev "domain"

                            @{u}The OUTBOUND_DIR keyword@{uu}


Usage:  @{b}#OUTBOUND_DIR "<path of outbound directory>"@{ub}

Example:  @{b}#OUTBOUND_DIR "MAIL:Outbound/"@{ub}

@{i}This keyword is mandatory.@{ui}

    This keyword specifies the directory that you use as your outbound drawer (as specified in your mailer's preferences).  This is the directory that MM_Poll will scan in order to determine what mail you have waiting to leave.

    Please leave the trailing `@{b}:@{ub}' or `@{b}/@{ub}' on the end of the path name.

@endnode

@node "4d" "The 4D keyword"
@next "nonodelist"
@prev "outbound_dir"

                                 @{u}The 4D keyword@{uu}


Usage: @{b}#4D@{ub}


    This is a switch, and therefore no parameters are needed.

    Put simply, by including the 4D keyword, MM_Poll will pass a 4D address into your @{"MAILER" link "mailer" 0} string (ie, an address with no domain).  Without it, MM_Poll will pass 5D addresses.

    If you use this switch, you may safely delete all the @{"DOMAIN" link "domain" 0} lines in your config - this will speed up config parsing.

@endnode

@node "nonodelist" "The NONODELIST keyword"
@next "boss"
@prev "4d"

                             @{u}The NONODELIST keyword@{uu}


Usage:  @{b}#NONODELIST@{ub}


    This is a switch, so no parameters are needed.

    @{u}Without@{uu} this switch, MM_Poll will check your traplist nodelist for the address you selected (Crash or FReq only) and show you information about it (just so you know who you are about to call!).  Obviously enough then, @{i}supplying@{ui} the NONODELIST switch stops this check from happening.

    This was included for anyone who uses a mailer that uses a nodelist other than the traplist nodelist (@{i}Gotcha@{ui}, for example).

@endnode

@node Index "Index"
@remark Index auto-generated by Heddley
@remark ...and then changed a bit by Simon :-)


@{"About MM_Poll" link "about"}
@{"System requirements" link "requirements"}
@{"Installing MM_Poll" link "installation"}
@{"How to configure MM_Poll" link "configuration"}
    @{"The 4D keyword" link "4d"}
    @{"The AKA keyword" link "aka"}
    @{"The BMAILER keyword" link "bmailer"}
    @{"The BOSS keyword" link "boss"}
    @{"The CMAILER keyword" link "cmailer"}
    @{"The DOMAIN keyword" link "domain"}
    @{"The RMAILER keyword" link "rmailer"}
    @{"The FMAILER keyword" link "fmailer"}
    @{"The MAILER keyword" link "mailer"}
    @{"The NONODELIST keyword" link "nonodelist"}
    @{"The OPTION keyword" link "option"}
    @{"The OUTBOUND_DIR keyword" link "outbound_dir"}
@{"How to use MM_Poll" link "usage"}
@{"Possible error messages from MM_Poll" link "errors"}
@{"Legal matters" link "legal"}
@{"Credits and Thanks" link "credits"}
@{"How to contact me" link "contact"}

@endnode