Welmat Programming Language - WPL
               ---------------------------------


  General WPL script information
  ------------------------------

  A WPL script is a text file that is read in line by line by a routine that 
will try to analyse the line into a valid WPL statement.  When these lines 
are parsed, they are parsed into a format of:

[label:] command [parameter] [parameter] [parameter] ...

 where the 'label' is a string of alpha-numerics a maximum of 30
characters in length (and is terminated by a colon ':').  A command is
any WPL command that is known to the parser at the time the file is being
parsed, and the parameters are a given number of text strings where the
number is specific to each WPL command.

  Before looking up the command it first checks if the first character
is a ';' (semicolon) or a '#' (octothorp).  If it is, the rest of the
line is 'thrown out' as being a comment.  (NOTE: If there was a label on
the line before the comment, the label is valid).  A blank line, lines with
comments, or parameters beyond the number required by the function are just
thrown out as 'useless information' and are not kept by the WPL parser.

  Strings within WPL are a generic concept used by every function in the
language. When I say a function takes '3 parameters' I mean that it takes three
of these 'WPL strings'.

  Now, since the space character is used to separate parameters, if you want to
send an actual 'space' character, you must put your string within quotes. Now
that you're using the double quote " character to form the string, if you want
to put an actual QUOTE character within a string, you must escape it by doing
\"  (Yes, just like what was done in WCompile's config files). Now that you
have this escape character, if you want to put a '\' in the string, you must
escape the escape character and use \\.

  Some other special escape characters exist:

  \n   - Newline (Same as Linefeed)
  \r   - Return character
  \### - send the Octal (base 8) character given by the three digits following
the slash.


   WPL string variable substitutions:
   ----------------------------------

  There is a general function used to find the value of a string within
WPL (the WPI command is called wpi_getstring()) that allows for many
runtime substitutions of the value of various types of variables.

  Variable types are signified by the $ character, and then the variable
name is bracketed by a special set of characters, one to begin the
bracket, and one to end.  The bracketing character itself determines
what type of variable is used.  To add a '$' chracter itself to the string,
use two $ characters one after the other.

 $()  - WPL variable set with the 'Set' WPL command
 ${}  - AmigaDOS ENV: global variable, set with the 'SetEnv' WPL command.
 $[]  - AmigaDOS SHELL local variable, set with the 'SetVar' WPL command.
 $<>  - WPI read-only calculated variables.  These variables are calculated
        at the time that their value is requested.

 Currently, the calculated variables are as follows:

  $<abort>  - Counts the number of REXX abort messages awaiting WPL to
              exit.  This is used as a boolean that when true ( > 0) will
              signify that a WPL script should attempt to exit.  These
              messages will be replied to only once the last slave has closed.

  $<date>   - substitutes the date in dd-mm-yy format.  This will be 
              localized at a future point.

  $<port>   - substitutes the unique REXX compatible message port name that
              identifies the current slave.

  $<time>   - substitutes the current time in hh:mm:ss format.  This will 
              be localized at a future point.



  The variable substitution is recursive, which means that the value of
a variable might itself contain a variable name, and the variable name to
be looked up could itself be formed out of other variables.

  If this recursive calling is not desired, then a single tick character is 
used after the $ character to indicate that no further substitution is 
requested.  In this non-recursive mode, any $ characters in the value of
a variable will not cause further variable expansion.  The use of the single 
tick is very advisable to use when printing out variables typed in by a user,
so that the user can not attempt to print out passwords and other 
variable values.


  SetVar blah "hahahaha"
  set TestVar $$[blah]
  set LookupVar Var
  print "a:$'(test$(lookupvar))\n"
  print "b:$(test$(lookupvar))\n"

This would print:

a:$[blah]
b:hahahaha


  Note: single-tic ' characters are not equivalant to a double quote " character,
as they are in AREXX, and are added untouched to the string.  One should note
that they DO have a significance to REXX so are useful to avoid having to 
'escape the quote' when sending messages to REXX.

  If a variable is being read as a boolean, it is considered true if it's
'numeric value' is not '0', or if the first character is upper or lower case
't'.  Otherwise, it is considered false.

  TRUE == -1 == 1 == touch == 9999
  FALSE == 0 == Charles == false


  Addresses
  ---------

  WPL makes use of the XferQ shared library in order to handle all of it's
Text<->Address conversions, and thus WPL will be able to understand any
address type that XferQ understands.

  All commands that accept addresses are designed to accept a list of
addresses.  Many of the older commands only act upon the first address, but
all commands are being designed to accept a list of addresses regardless of
how many of them are used.

  In order to keep a standard among all utilities that use XferQ, the 
standard set forth in the Seen-By, Path, EMSI, SPTH, and other such 
specifications of using a whitespace  (Space, Tab, Return, Linefeed) as 
a separator between specific addresses was used.  For this reason one can
obviously not have a space character within an address without having it
escaped in some way.

NOTE: Some method to 'quote' an address, or escape a whitespace will be 
added in the future, but is currently not supported by WPL or XferQ.
  
------------------------------------------------------------------------------

  Here is a very general rundown of the commands currently available within
WPL.  I will be trying to keep this updated and as accurate as possible, so 
let me know about any incorrect, or unclear commentary.  I will later on
be basing the WPL programmers manual on this text.

  The format of this command list gives the following information:

  Command Name,  Number of argument STRINGS
  - WPL variables read
  - WPL variables modified
  - General description of the command.

------------------------------------------------------------------------------

  The first type of commands are the control commands.  These commands are
only available from within a WPL script, and are not available via the REXX
port.  These are also the only commands that do not follow the same rules for
their parameters.  Unlike other commands, a variable is a hard-coded
text value and cannot include any type of variable.  Also note that all labels
are currently *case insensitive*.

  NOTE: If a label is not found, this statement will just continue with the
        next statement.  A program called 'WLint' will detect and warn about
        these types of things, but one should be careful until that
        program is written.

  Return         0
  - No WPL variables read or modified
    This command will return to whatever called the sub-routine.  If the
    sub-routine was called by the 'SubJump' command, it will continue with
    the statement following the 'SubJump'.  The last 'RETURN' statement
    within a WPL script will cause the SLAVE to exit.

  TrueReturn     0
  - Reads the $(RC) variable as a boolean.
  - Does not modify any variables.
    This will do a return only if the $(RC) variable is True.

  FalseReturn    0
  - Reads the $(RC) variable as a boolean.
  - Does not modify any variables.
    This will do a return only if the $(RC) variable is False.

  Jump           1
  - No WPL variables read or modified
    This command will search for the given label and will unconditionally jump
    to that location in the script.  No return address is saved.

  TrueJump       1
  - Reads the $(RC) variable as a boolean.
  - Does not modify any variables.
    Will only jump if the $(RC) variable is True.

  FalseJump      1
  - Reads the $(RC) variable as a boolean.
  - Does not modify any variables.
    Will only jump if the $(RC) variable is False.

  SubJump        1 
  - No WPL variables read or modified
    This command will search for the given label and will unconditionally jump
    to that location in the script saving the return address.  When the next
    'return' statement is hit, control will return to the statement
    immediately following the SubJump command.
    SubJump also accepts script!label in order to jump to a sub-routine
    within another WPL script.

  TrueSubJump    1
  - Reads the $(RC) variable as a boolean.
  - Does not modify any variables.
    Will do a SubJump call only if the $(RC) variable is True.
    TrueSubJump also accepts script!label in order to jump to a sub-routine
    within another WPL script.

  FalseSubJump   1
  - Reads the $(RC) variable as a boolean.
  - Does not modify any variables.
    Will do a SubJump call only if the $(RC) variable is False.
    FalseSubJump also accepts script!label in order to jump to a sub-routine
    within another WPL script.

----------------------------------------------------------------------------

  The following commands are both within a WPL script, and via the
REXX port of a specific slave.  All parameters can be built up of fixed text
and any type of variable.

  With the proposed new 'wplcmd.library' and 'wplext.library' function
libraries, I am attempting to organize commands into one one of the two
libraries.  The 'wplcmd.library' is the required library, and will house
all the commands that are required for operation.  'wplext.library' will
house any extension commands that might be useful for WPL programmers,
but who's usage in 'Config File Generators' will be discouraged in order to
keep RAM requirements down.  Please let me know if you disagree with my
organization.

  (*) - indicates a 'wplcmd.library' command
  (+) - indicates a 'wplext.library' command
  (-) - indicates a temporary command that might be removed.


(*)AddResponse    PAIRS
  - Does not read or modify any variables.
    Takes a pair of parameters.  The first is an 'event' name, and the
    second parameter is a pattern.  Three special cases exist:
    a) The event is the word 'find'.  In this case the second parameter
      is not a 'pattern', but is a string that will be case insensitive compared
      to the response string.  If the string matches, it will then look
      at the next character looking for a baud rate number.
      An example would be:  Addresponse FIND "CONNECT "
      The event type as returned from GetResponse will actually be 'CONNECT',
      and the baudrate is changed to the number grabbed after the string.
      NOTE: The space is important!  The next letter after the string comparison
      must be an actual digit of the baud rate in decimal.
    b) The event is a number.  In this case the second parameter is a 
      case insensitive AmigaDos wildcard.  If it matches the incoming
      string, the event is set to 'CONNECT', and the baudrate is changed to
      the given number.
    c) The even it just text, in which case the second parameter is a
      case insensitive AmigaDos wildcard.  If the wildcard matches, the
      event is set to the value given by the first parameter.

(*)Address        2
   - does not read any variables
   - sets $(Result1), $(Result2), $(RC)
   The first parameter is a CASE SENSITIVE AREXX port name, and the second
   parameter is a command to be sent to that port.  The result from the
   command is set into $(Result1).  If the result was 0 and a secondary
   result was returned, it will be placed into $(Result2).
   Return values in $(RC) are as follows:
     0 - Message sent OK.
    19 - Couldn't find Port.
    20 - Memory for message couldn't be allocated.


(*)BeginSession   1
  - Does not read or modify any variables
  The parameter given is a single parameter string which lists all the network
  addresses that outbound mail should be searched for during the current.
  (See: EndSession)

(*)CallForward    1
  - does not read any variables.
  - Sets $(RC) as a boolean.
    This command will take a call found with the 'CheckCall' command and will
    forward it to an alternate slave/message port. The parameter given is 
    the REXX message port name of an active REXX host, such as a WPL slave.
    If the port is found, the REXX message (Exactly as it was sent to
    this slaves port) is forwarded to that port, the 'active call' pointer
    used by 'ReplyCall' is cleared, and the variable $(RC) is set to TRUE, 
    otherwise $(RC) is set to FALSE (And the call is not cleared or forwarded).

    Note:  If one wishes to re-queue a call to be processed at a later time, one
       would just forward it back to the same slave  by saying 
       'CallForward $<port>'.
       Also note that the REXX port that this forwards the REXX message to
       can be *ANY* valid AREXX port on the system, not just the WPL ones.
       If one is running a mailer other that WPL, they could even forward
       a call to this other program's REXX port.


(*)CheckCall      0
  - Does not read any variables.
  - Sets the $(RC) variable as a boolean.  Also sets the stem variable 'remote'.
    This command will check the call queue and will return the address list
    information of the call (in the stem variable 'remote') and set the $(RC)
    to TRUE if a call exists.  If there are no pending calls, $(RC) will be
    set to FALSE.
    The stem variable 'remote' includes: remote.address , remote.network,
         remote.domain,remote.zone, remote.net, remote.node, remote.point,
         remote.text .
    The remote.address is a full nDimensional address list as specified by 
       Xferq.
    The remote.network is currently one of 'FIDO', 'UUCP', 'FQDA', 'TEXT' as
    per XferQ.
    The remote.text is the exact text that was given in the string when the
    'CALL' command was issued to the REXX port.

(*)CheckCarrier   0
  - Does not read any variables.
  - Sets the $(RC) variable as a boolean.
    This command is used to check to see whether or not there is a carrier
    present on a specific slave.

(+)Clear          NO LIMIT
    Will remove a WPL style variable from the list of variables.  
    This command is equivalent to 'set <var> ""'

(*)ClearResponse  0
  - Does not read or modify any variables.
    Will clear all the response strings for a slave.

(*)Cmp            2
  - Does not read any variables.
  - Will set the RC variable as a boolean.
    This function does a case sensitive string compare on the two parameters.
    The two parameters must match character by character (Spaces included) in
    order to set RC to 'TRUE'.  

(*)CmpI           2
  - Does not read any variables.
  - Will set the RC variable as a boolean.
    This function does a case INSENSITIVE string compare on the two parameters.
    The two parameters must match character by character (Spaces included) in
    order to set RC to 'TRUE'.

(*)Delay          1
  - does not read any variables.
  - Sets the $(RC) as a boolean.
    This command will wait for the number of seconds given as the
    parameter, during which time it will handle any incoming message
    for the public REXX port.

(*)EndSession     1
  - Does not read or modify any variables
  The parameter given is a single parameter string which lists all the network
  addresses that should be removed from the list of addresses that outbound 
  mail should be searched for during the current network session.  The special
  case of "ALL" means that all addresses in the list will be removed.
  (See: BeginSession)

(*)FindFreq       1
  - Reads $(outbound) 
  - Sets the return code $(RC) as a boolean
    Takes a single XferQ address as the parameter and will look for 2-D or 
    4-D request files in the outbound directory.  If found, it will add them 
    to the outbound list and will return $(RC) as true.  This command will be
    expanded to accept an address list in the future.

(-)FlushLog       0
  - reads $(LogPort)
  - does not modify any variables.
    flushes current log via LogProc (Rexx port "$(LogPort)")
    Equivalent to:
       Address "$(LogPort)" "FlushLog"

(*)GetInbound     2
   -  'SayHello' reads WPL variables: host.wzdomain, host.sitename, host.sysop, 
      host.zone, host.net, host.node, host.point, remote.password, host.wzcap,
      freq
   - wpl variables set: remote.zone, remote.net, remote.node, remote.point,
     remote.wzdomain, remote.domain, remote.password, remote.address,
     remote.wzcap, host.wzcap (Modified to chosen protocol),
     remote.sitename, remote.sysop, remote.product, remote.product_maj,
     remote.product_min, EVENT

   Gets inbound (Someone called in) negotiation (Login, FTS1, YooHoo, etc)

   First parameter given is a flags string, with each flag separated by
   a comma:
      G1      - Scan for TSYNCH character for FTS1 transfer.
      G6      - Scan for YOOHOO character for FTS6 transfer.
      GE      - Scan for any EMSI Sequences (Not currently active)
      E0      - Echo all printable characters to remote.
      E1      - Echo dots rather than actual character.
      E2      - Do not echo.

   Second parameter is the timeout in seconds.


   $(EVENT) has the following values:
     "FTS1" - TSYNCH received - $(FTS1)==TRUE, $(WAZOO)==FALSE
     "GOTYOOHOO" - Hello greeting received OK.
         wpl variables set: remote.zone, remote.net, remote.node, remote.point,
             remote.wzdomain, remote.domain, remote.password, remote.address,
             remote.wzcap, host.wzcap (Modified to chosen protocol),
             remote.sitename, remote.sysop, remote.product, remote.product_maj,
             remote.product_min
     "EMSI"      - "**EMSI_" string received - Full line of text in $(namebuf)
     "LOGIN"     - Line of text in $(namebuf).  If $(namebuf)=="bbs" then
                   <esc> may have been hit twice.
     "CARRIER"   - Carrier Dropped.
     "TIMEOUT"   - A timeout occurred.

    
(*)GetOutbound    1
   - 'SayHello' reads WPL variables: host.wzdomain, host.sitename, host.sysop, 
      host.zone, host.net, host.node, host.point, remote.password, host.wzcap,
      freq
   - wpl variables set: remote.zone, remote.net, remote.node, remote.point,
     remote.wzdomain, remote.domain, remote.password, remote.address,
     remote.wzcap, host.wzcap (Modified to chosen protocol),
     remote.sitename, remote.sysop, remote.product, remote.product_maj,
     remote.product_min, EVENT,  FTS1, WAZOO

   Parameter given is a flags string, with each flag separated by
   a comma:
      G1      - Scan for double 'C' or double <NAK> for FTS1 startup,
      D1      - Send TSYNCH character.
      G6      - Scan for ENQ for FTS6 startup.
      D6      - Send YOOHOO character,
      GE      - Scan for any EMSI Sequences (Not currently active).
      DE      - Send an EMSI_INQ as part of negotiation.  May cause 
                negotiation problems with non EMSI sites and should
                not be required (And is actively discouraged!)
                (Not currently active).

   Gets outbound (We called out) negotiation (Login, FTS1, YooHoo, etc)

   $(EVENT) has the following values:
     "NOANSWER" - No return character came back from the <space> <return>
                  stage of negotiation
     "NOCLEAR"  - Line didn't clear after banner.
     "CARRIER"  - Carrier Dropped.
     "FTS1"     - Two Consecutive 'C' or <NAK> characters received, indicating
                  FTS1 transfer desired. $(WAZOO)==FALSE, $(FTS1)==TRUE
     "NOSYNCH"  - Timeout before any negotiation successful.
     "NOHELLO"  - Remote didn't acknowledge our Hello Message.
     "NOYOOHOO" - Remote didn't send their Hello.
     "BADYOOHOO"- Received YooHoo was bad.
     "WAZOO"    - YooHoo properly received. $(WAZOO)==TRUE, $(FTS1)==FALSE

    During a YooHoo sequence our "Hello" is sent.  At that point the equivalent of
    the 'WazooRespond' is executed.  Then their Hello is received, and the
    variables indicated in GetInbound for YooHoo are then set.

(*)GetResponse    1
  - reads $(CALLINTERUPT), $(OWNDEVUNIT)
  - Will set the variables $(LastResponse), $(Event) and possibly
    set $(BAUD) (If $(event) was CONNECT).

    This command makes use of the Response strings set up with the
    'AddResponse' command.  Will wait for a maximum of seconds given by the
    argument for a line of text (Which is then placed in $(LastResponse).
    The text is checked against the response strings and if a match
    is made, then $(EVENT) is set to the EVENT part of the response pair,
    otherwise $(EVENT) is cleared to "", or it's set to one of the internal
    events (Listed below).
    $(OWNDEVUNIT) is read as a boolean variable indicating whether an attempt
    to exit should be made if a request of the port is made.
    $(CALLINTERUPT) is a boolean variable indicating whether a new
    REXX 'CALL' command should cause this command to exit.

    $(EVENT)
      NOMODEM    - MOpen was not done before this command - it exited 
                   immediately
      OWNDEVUNIT - Someone else wants the device (Only active when
                   $(OWNDEVUNIT) boolean variable is true)
      TIMEOUT    - A timeout occurred
      CARRIER    - Carrier 'dropped' during command
      CONNECT    - From Response ### or response find

(*)Launch         4
   - Does not read any variables
   - sets $(RC)

   launches a slave where the five parameters are
   1) Slave name - This is a string (Max 100 chars) that is used as the
      REXX port name, and the CLI name for the process.
      This name must be unique for the system.
   2) script!Label to start execution at.
   3) Process priority.
   4) Process Stack size - WPL is a stack hog, so try to make this fairly high.
      I myself usually use about 30K.

   The return codes set in $(RC) are as follows:

     0 - All OK so far.
     1 - Can't create public port.
     2 - Can't open timer.
     3 - Can't allocate vars structure.
     4 - Can't open xferq.library
    99 - No memory in slave.
   101 - No memory for structure.
   102 - Error in new process launching.

(*)LoadScript     2
   - Does not read any variables
   - sets $(RC)

   The first parameter is a script name.  This is a unique word that is used
   whenever referencing the script with a Launch, SubJump, or other similar
   commands.  The second parameter is the full pathname to the file to read.

   Return code is a boolean:
      TRUE - The script was loaded (Or , if the pathname given was "", the
             old script was purged).
      FALSE - The script had an error in it, or the script name was busy.

(*)ModemClear     0
  - does not read or set any variables.
    This command will clear both the inbound and outbound serial buffers.
    This command is ignored if no modem is opened.

(*)ModemClose     0
   - Does not read or modify any variables
     Closes modem previously opened with ModemOpen

(+)ModemInit      0
  - Reads $(BaudLocked), $(InitWait), $(InitLoop), $(HangupString)
    , $(initString), $(Atten), $(Prompt)
  - Sets $(Baud) to the same value as $(BaudLocked). Sets the $(RC) variable 
    as a boolean.

    This command goes into a loop that looks like the following:

      while I've looped less than $(initloop) times
        Is there a carrier?
          Send The $(HangupString) string
        otherwise, Have we gotten an 'OK' from the modem last loop?  If not
          Send The $(Atten) string
        otherwise
          Send the $(InitString)

        Wait for a maximum of $(InitWait) seconds for the $(Prompt) to come
        back from the modem.
      if we still have a carrier, or didn't get the $(Prompt), then loop.


    The boolean $(RC) is set to FALSE if a carrier still exists after the system
    tries to initialize the modem, otherwise it is set to TRUE.

(*)ModemOpen      0
   - Reads: unit, device, serflags, locked, baud, baudlocked,
     SerReadBuf, SerWriteBuf, OwnDev
   - sets RC as a boolean
     Will open a modem on this slave using the settings in the above variables.
     Will automatically close an old modem that may have been opened previously.

     If the modem is already owned by another program (via OwnDevUnit.library),
     then the subroutine pointed to by the variable $(OwnDev) will be be 
     "SubJump'd" to.  The variable $(Owner) is set to the string name of 
     the program that owns the device.  If $(RC) is set to TRUE after the 
     return, then ModemOpen will wait for the device to be available.  If 
     $(RC) is set to FALSE, then the ModemOpen call will immediately return 
     with a failure, and not wait.

     $(unit)     - Unit number of the device.
     $(device)   - Device name string.
     $(serflags) - Serial flags (Remember to use SHARED mode if required!)
     $(Locked)   - Boolean to signify if the baud rate should be locked.
     $(baud)     - The Modem<->Modem bps speed (Does not have to match the
                   speed the serial port is running at.
     $(BaudLocked)  - The Computer<->Modem bps speed.  This is the actual
                   speed the serial port is running at.
     $(SerReadBuf)  - Serial Receive buffer in K. This is a value given to
                   the particular serial driver, and the driver itself
                   allocates this buffer.
     $(SerWriteBuf) - Serial Write buffer in K.  This is the switch to turn
                   on the double buffered writes to the serial port.  The
                   value has to be greater than the size of the largest
                   single write that would be made. For example, a 9600bps+
                   modem uses an 8K block to write, so some value LARGER than
                   this (Say 10) should be used.  Two buffers of this size are
                   allocated.
                   *NOTE* : This feature separates the good serial drivers
                   from the bad.  If your system does not work with this
                   turned on, a value of 0 can be used to turn this feature
                   off.


(*)Pattern        2
  - Does not read any variables.
  - Will set the RC variable as a boolean.
    This function does a case insensitive amigados style pattern match on
    the two strings.  The first string is the source string, and the second
    string is the AmigaDos pattern.
    Examples:
       Pattern "This iS a TesT"  "this ???a test"   
          returns TRUE
       Pattern "this ???a test" "This iS a TesT"
          returns FALSE
       Pattern "This iS a TesT "  "this ???a test"   
          returns FALSE
       Pattern $(some_Variable) "#(1|3|5|7|9)"
          returns TRUE if the WPL variable some_variable is composed totally of
          a string of odd numbers.
       Pattern $(remfile) "#?.REQ"
          returns TRUE if the WPL variable remfile has a string that ends in
          the letters '.req' (Such as an incoming file request!)

(*)Print          1
  - Does not read or modify any variables.
    This command will print the given parameter to the slaves active status
    console as set by 'SetStatus'.

(+)PutLog         1
  - Does not modify any variables.
  - reads $(CurrentLog), $(LogPort) variable
    sends text to current log via LogProc (REXX port "$(LogPort)").
    Equivalent to:
       Address "$(LogPort)" "PutLog $(CurrentLog) <text>"

(*)ReplyCall      1
  - Does not read or modify any variables.
    This command replies to a REXX call found by the CheckCall command.  The
    parameter accepted is the result of the REXX 'CALL' command.
    If the 'numeric value' of the result is 0 (IE: Eithor the number 0, or
    sone non-digits), and the host requested a result string, the
    parameter given to ReplyCall is passed back as a string.  This allows the
    passing of non-numeric results back to the originating script.
    (See Also: CallForward, CheckCall)

(*)RexxMsg        3 - 18
   - does not read any variables
   - sets $(Result1), $(Result2), $(RC)
   The first parameter is a series of flags:

   EG:
    FN,TN,IN,SN,RY,NN
   
     The first letter in each pair is the flag, and the second is the
     value (Y for Yes/True, N for No/False).  A value is by default
     FALSE.

   F:  Determines whether a RXFUNC function or a RXCOMM command type is
     to be used.
   T:  Determines whether the RXCOMM type will be tokenized before being
     sent.
   I: Determines whether or not the automatic inheritance of the
     host input/output streams will be suppressed.
   S: Determins whether the argument given is a 'string file' rather than
     a file name.
   R: Determines whether a string result (To be put in Result2) will be
     asked for.
   N: Determines whether we want the message to be non-returning.  This
     parameter assumes that the REXX port being sent to is capable of
     recycling the message, and should never be used unless this knowledge
     is known about the given REXX port.

     The second parameter is a CASE SENSITIVE AREXX port name, and the 
   remaining parameters are the arguments to the message, with the first
   argument usually being the command itself.  The result from the
   command is set into $(Result1).  If the result was 0 and a secondary
   result was returned, it will be placed into $(Result2).

   Return values in $(RC) are as follows:
     0 - Message sent OK.
    19 - Couldn't find Port.
    20 - Memory for message couldn't be allocated.
    99 - Invalid number of parameters.

(*)Send           1
   - does not read or modify any variables
     sends an un-interpreted string out the current modem.

(*)Set            PAIRS
    Sets local WPL style variables.  Pairs of 'variable' 'value' are
    accepted.

(*)SetA            2
  - Does not read any variables.
  - Sets the given stem variable.
    This command accepts a 'stem variable' as the first parameter, and an
    address list as the second.

   eg: seta remote 1:163/109

    Would set the same variables as CheckCall would if someone did a 
    'call 1:163/109'

    The stem variable includes: <stem>.address , <stem>.network,
         <stem>.domain, <stem>.zone, <stem>.net, <stem>.node, <stem>.point,
         <stem>.text 
    The <stem>.address is a full nDimensional address list as specified by Xferq.
    The <stem>.network is currently one of 'FIDO', 'UUCP', 'FQDA', 'TEXT' as
    per XferQ.
    The remote.text is the exact text that was given in the parameter.

(+)SetBaud        1
  - does not read any variables.
  - Sets $(Baud) and $(BaudLocked) to the value of the given parameter.  Will
    also set the $(RC) variable as a boolean.
    This command will set the baud variables, and then attempt to change the
    device's baud rate.  Will set $(RC) to FALSE if this line did not have 
    it's modem opened, otherwise it will be true.

(*)SetEnv         PAIRS
    Allows one to set a global ENV: variable.  Pairs of 'variable' 'value' are
    accepted

(*)SetMailerFlags 1
  - does not read or modify any WPL variables.

    Changes the General mailer flags for this slave. Options not specified here
    will be left unchanged.  Please do not ever rely on the system 'defaults'
    for these values.

    Flag     Value               Meaning

      D        Y        Generate and send a Dummy poll packet.
      D        N        Do not generate or send a Dummy poll packet.
      D        E        Generate and send a Dummy poll packet only if no other
                        files are to be sent. 

     Example:  For FTS-1 sessions, one would use:
       SetMailerFlags "DY"

(*)SetPri         1
  - Does not read or modify any variables.
    Will set the priority of a slave to the given value. For further
    information on this command, please refer to the AmigaDos 
    shell command 'ChangeTaskPri'.

(*)SetStatus      1
   - does not read or modify any variables
    Will set the standard out of a slave to a given file specification.
    Many different error messages and runtime status information (As well
    as the output of the 'PRINT' WPL command) go to this file handle.
    Usually specifies a RAW:

(+)SetUpdate      1
   - does not read or modify any variables
     Takes a parameter that can be one of three types:
     "SetUpdate NULL"   - Turns this feature off (default)
     "SetUpdate status" - Use the existing status window (Not recommended)
     "SetUpdate <filename>" - Use the given filename (RAW: usually) for the
                         XPR transfer status window.

(*)SetVar         PAIRS
    Allows one to set AmigaDOS SHELL local variables.  Pairs of 
    'variable' 'value' are accepted.  When a command is ran via
    the SYSTEM command from WPL, these variables are available in a
    read-only fashion (A copy is made by AmigaDOS).

(*)SignalSlave    PAIRS
   - does not read or modify any variables
     Given a slaves message port name, it will send the given signals to the slave.
     The signals are as follows:
       "c" - BREAKC
       "d" - BREAKD
       "e" - BREAKE
       "f" - BREAKF
       "m" - Message Port Signal
     
     Signals are most often sent to a slave in order to 'wake it up' to check
     other variables/etc.

(*)SmartSend      1
   - reads $(SlowModem)
   - does not modify any variables
     Sends interpreted modem string to the serial port.  The interpreted
     characters are as follows (Note: one would precede these characters
     with the '\' escape character if the special character needed to be
     sent out the modem):
       ^ - Raise DTR.  See $(DTR_CONTROL)
       v - Lower DTR.  See $(DTR_CONTROL)
       ~ - Wait 240ms.
       ` - Wait 60ms.
       | - Send a return character.
     If the variable $(SlowModem) is TRUE, a 60ms delay will be placed
     between each character sent.

(*)System         1
  - Reads the WPL variables: stack, ShowSystem
  - Sets the variable RC with the return code of the AmigaDos command.
    The WPL variable 'stack' is used to change the default stack (taken from
    the stack size of the slave itself).  If the variable 'ShowSystem' is
    TRUE, the full 'execute' command is dumped to the status console.
    The command takes an AmigaDos function as the parameter and will
    synchronously execute the command.

(*)XprClose       0
   - does not read any variables
   - modifies $(RC)
     Ends session with XPR library and free's associated resources.
     The XProtocolCleanup() function is called, and any files left in
     the XPR transfer list are marked as having 'failed'.  Any
     outbound management at end of session is handled.
     The variable $(RC) is set to false if the modem was not given,
     otherwise it is true.

(*)XprReceive     1
   - does not read any variables
   - sets $(RC)
     Receive single file (Specify name - Not yet supported)
     Receive batch files to $(inbound) (Specify "")
     This function will call the XPR receive function.  During a transfer
     various WPL subroutines such as $(PostInbound), $(PreInbound),
     $(PostOutbound), $(PreOutbound) could be called.  See "XPR Interface"
     section of the manual for more details.

(*)XprSend        1
   - does not read any variables
   - sets $(RC)
     Send single file (Specify name - not yet supported)
     Send batch files from list in outbound manager. (Specify "")
     This function will call the XPR send function.  During a transfer
     various WPL subroutines such as $(PostInbound), $(PreInbound),
     $(PostOutbound), $(PreOutbound) could be called.  See "XPR Interface"
     section of the manual for more details.

(*)XprSetFile     3
   - does not read any variables.
   - sets $(RC) boolean for success/failure.

    Sets up a pathname/asname/flags mapping for a file that will be able to
    be referenced within an XPR protocol.
    The first parameter is a full pathname to any file on your system.  This
    can be a file that already exists (for outbound transferring), or a file
    that does not exist that you wish to receive.
    The second parameter is the name that the XPR Protocol will refer to the
    file as.  This name has no 'path' part to it, and may not even in any way
    relate to the pathname.
    The third parameter is a series of character flags.  At the moment, three
    flags are defined:
      D - Delete the file after transmission, if successful.
      K - Delete the file after transmission, regardless of success/failure.
      T - Truncate the file after transmission, if successful.

(*)XprSetup       2
   - does not read any variables
   - sets $(RC), $(XprSetup)

   Sets up an XPR library ready for a transfer.  The first parameter
   given is the xpr library name, and the second parameter is a string
   passed to the xpr library with  XProtocolSetup().  The variable
   $(XprSetup) is set to the numeric return of XProtocolSetup(). A value
   of 0 indicates a failure, otherwise the setup was successful.  Since
   only one library can be opened at any one time, any previous libraries
   are first closed.

   Return values in $(RC) are as follows:
      0 - All OK.
      1 - XProtocolSetup returned FALSE.
      2 - Library not able to be opened
      3 - Out of memory.
      4 - Wasn't given required modem.
      

(-)WaitEvent      1
  - reads $(CALLINTERUPT)
  - modifies $(BREAKT), $(BREAKC), $(BREAKD), $(BREAKE), $(BREAKF)
    The given parameter is a timeout in seconds.  This command waits for any
    of the 4 signals and sets the appropriate boolean variable to 'true'.
    $(BREAKT) indicates that a timer event occurred.  During the wait the
    slave will process messages on it's REXX port.
    $(CALLINTERUPT) is a boolean variable indicating whether a new
    REXX 'CALL' command should cause this command to exit.

(*)WazooRespond   0
  - Reads WPL variables host.wzdomain, host.sitename, host.sysop, host.zone, 
    host.net, host.node, host.point, remote.password, host.wzcap, freq
  - Sets $(event)

    Used after a GetInbound to respond to the remotes hello packet with one of
    your own.  Will read the listed variables to properly set the YooHoo hello.

    Possible values set to $(event) are:
    "CARRIER"  - Carrier dropped.
    "NOYOOHOO" - Required response character not found.
    "2U2"      - Success - Hello response sent.
    "TIMEOUT"  - A timeout occurred.

---------------------------------------------------------------------------------

  These commands exist for debugging/etc and are known to be being removed in the
future

(-)-ListResp      0
  - Does not read or modify any WPL variables.
    Lists modem responses to console (from AddResponse).

(-)-ListVars      0
  - Doesn't change any variable.
  - Will list out all the active variables in a particular slave to the
     slaves console.

(-)-ListConfig      1
  - Doesn't change any variable.
    Lists out the current 'memory' version of script.  The parameter given
    is a script name.

(-)-Debug      1
  - Doesn't change any variable.
    Outputs string to debug console via KPrintF() function (Sushi used to
    redirect).

-------------------------------------------------------------------------------
  The following commands are available exclusively from the REXX port.

  ABORT 0
    This message, sent to a specific slaves message port, is intended to
    abort a specific slave.  The REXX message will wait until the slave has
    exited before it will return.   A WPL developer would check for the
    existence of an ABORT rexx message via the $<abort> calculated variable.
 
  CALL 1
    This message, sent to a specific slaves message port, takes an address list
    (Of any currently understood network type) and will add it to the list of 
    sites that a specific slave will attempt to dial.  This message will be 
    replied to via the 'ReplyCall' WPL which sets it's return code.
    Please see the  documentation of the WPL instructions 'CheckCall', 
    'CallForward' and 'ReplyCall' for further information.

  STRING 1
    This message, sent to the specific slaves message port, is used to make use
    of the internal STRING generating routines.  This message will return a
    message in RESULT (Make sure you have REXX set up with 'options results')
    which is the string created by sending the supplied parameter through the
    internal STRING handler.  Any $(), ${}, $[], $<> style variable 
    substitution is available via this method and is a clean way to get 
    information back from WPL.
    (Note: as an example, call.rexx makes use of this to check the status of a 
    specific slave)


----------------------------------------------------------------------------

  In order to facilitate standard features in all 'setups' of WPL, certain
constructs are being strongly suggested to include.  While these are optional,
they will make interfacing with external programs written for use with WPL
much more transparent.

  One of the issues relates to the use of the $(STATE) variable.  Since Robert
has been playing with this longer, I'll just add his latest thoughts:

From: Robert Williamson on 1:167/104.0
Date: Friday, 25-Sep-92 22:38  (29-Sep-92)

The WPL variable $(STATE) should be set to one of the following values.  The
values are case insensitive:

    WAITING     Waiting for commands/waiting for ring/etc
    DIALING     CheckCall to event CONNECT
    ANSWERING   event RING to event CONNECT
    SESSION     inbound or outbound session
    EXTERNAL    system/rexx/login/bbs
    BUSY        anything else
    EXITING     obvious

 When reading $(state), the user should be aware that a string is returned, and
in some implementations only the first word of this string is one of the above. 

For example,in arexx, if doing a comparision, to be safe, one should :
  if upper(word(RESULT,1)) = "DIALING" then do ....whatever

 At present the Roof implementation returns the following extensions:
 DIALING $(remote.address)
 SESSION [$(remote.address)|"unknown"] [INBOUND|OUTBOUND]
 SESSION unknown FTS1
 SESSION [BBS|LOGIN] $(username)

 I'm setting BUSY from waitring:  to just after setglobals in waitring1: where
I set WAITING. In other words, modem stuff.

  I set ANSWERING at my own answer: label (entry point for answer when NO DIAL
TONE on dial), just before sending answer string.

 For EXTERNAL, I save and restore the previous state.

 I've added an additional in the Slave Startup, "LAUNCHING $(line)"

  I'm still refining this and may remove or add stuff. :)

From: Robert Williamson on 1:167/104.0
Date: Saturday, 22-May-93 17:26 

 Once again, I propose we standardize a basic set of RC's for the Call command
so that such conflicts will not arise.

 Perhaps we can reserve and standardize the values 0-20 and let wpl developers
use the higher value for there own particular applications.

         ; $(dialrc) values used in ReplyCall:
         ; 0 - ok
         ; 1 - owndevunit
         ; 5 - busy
         ; 6 - no number
         ; 10 - no modem
         ; 11 - carrier lost
         ; 12 - Modem response timeout
         ; 15 - badline
         ; 99 - wazoo failed

From: Russell McOrmond
Date: Tuessday, 25-May-93

    I myselt treat 'ReplyCall' returns as
     0 - Success.
     5 - Busy, retry later.
anything else - Error, don't bother trying again.


----------------------------------------------------------------------------
XPR Interface:

  During an XPR transfer, various WPL subroutines could possibly be called.
These WPL subroutines are figured out at the time when XprSetup is called,
and the variables should not be changed during an XPR transfer.  They are
subroutines, and thus one must do a RETURN to return control back to the
XPR.  It is intended for simple 'display' purposes and no large amount of
logic should be done in these subroutines.

*UNDER NO CIRCUMSTANCES SHOULD ONE OPEN OR CLOSE AN XPR DURING THESE SUBROUTINES*

As of 0.89 of wpl.library, a script name must also be shown.  The variables
would contain values such as "atronx!preinbound" which would mean to look
for the label preinbound: within the script called "atronx".

The subroutine variable names are as follows:

  $(PreInbound)  - Called first time an Inbound file is opened.
                   $(RemFile) - Filename as given by remote
                   $(TempFile) - full pathname to temporary inbound name.
                   $(FileSize) - The file size (from protocol, 0 if not known yet)

  $(PreOutbound) - Called first time an Outbound file is opened.
                   $(RemFile) - Filename as given by remote
                   $(LocalFile) - full pathname to local file.
                   $(FileSize) - The file size (from disk).
                   
  $(PreFullName) - Called first time a 'FullName' file is opened.
                   $(RemFile) - Filename as given by remote
                   $(LocalFile) - full pathname to local file.
                   $(FileSize) - The file size (from disk).
                   
  $(PostInbound) - Called after an Inbound files status is known.
                   $(FileStatus)=="Received","Failed"
                   $(RemFile) - Filename as given by remote
                   $(TempFile) - full pathname to temporary inbound name.
                   $(InFile) - Full pathname to final name (After rename if
                     successful transfer)
                   $(FileSize) - The file size (from protocol)
                   $(CPS) - Characters per second rating.
                   $(CPSP) - Characters per second rating (Percentage)

  $(PostOutbound) - Called after an outbound files status is known
                   $(FileStatus)=="Sent","Deleted","Truncated","Failed"
                   $(RemFile) - Filename as given to remote (asname)
                   $(LocalFile) - full pathname to local file.
                   $(FileSize) - The file size (from disk)
                   $(CPS) - Characters per second rating.
                   $(CPSP) - Characters per second rating (Percentage)

  $(PostFullName) - Called after a 'FullName' transfer status is known
                   $(FileStatus)=="Sent","Deleted","Truncated","Failed"
                   $(RemFile) - Filename as given to remote (asname)
                   $(LocalFile) - full pathname to local file.
                   $(FileSize) - The file size (from disk)
                   $(CPS) - Characters per second rating.
                   $(CPSP) - Characters per second rating (Percentage)


  XPR Filename Issues
  -------------------

  When an XPR is first opened (XprSetup), WPL knows absolutely nothing about
any file that might be transfered during that current session.  It hopefully
has had a BeginSession done on a particular site so that when the XPR asks for
files to send, it will know where to go look.

  WPL is a secure environment, so it doesn't allow an XPR to play with files
that the WPL developer doesn't want it to play with.  For this reason a list of
files that the XPR can 'play with' is maintained by WPL once the protocol is
set up (XprSetup).  This list contains:

  a) The name that the XPR will use to refer to the file.  This name does NOT
have a path in it, and whenever the XPR refers to something by a full pathname,
the 'path' part is removed before looking the file up in this list.

  b) The full AmigaDOS pathname of the file on disk.  This pathname can refer
to an actual file that already exists on the disk, or to a name that the XPR is
now allowed to 'create'.

  c) An indicator of what to do with the file when the XPR is finished
manipulating it.  These are usually only used for outbound files, and
include things such as:
   0 - Delete always, regardless of whether it was sucessful or not.
       This is used for the temporary '60 byte files' as an example.
   1 - Truncate to 0 length if file was successful.
   2 - Delete the file if the file was successful.

  d) A 'type' field which corresponds to the 3 different ways that a file can
be added to the list:

     0 - mapping was created when an 'open' occured for an unknown file.  The
pathname is set to a temporary filename in the directory pointed to by the
$(INBOUND) WPL variable, and this file will be renamed to a file by the given
name in the inbound directory if the receive was successfull.
  For instance, if an XPR tried to open a file called "Testing.txt", and this
file was not already known about by the WPL filename list, a pathname such as
"$(INBOUND)in.$<port>.0" is created.  If a file by that name already exists,
the number at the end is incremented.
  If the file failed at the end, the created file would be left with the
"in.$<port>.0" name.  If the file was successfull, it would be renamed to
"$(INBOUND)Testing.txt".
   A mapping of this type is 'usually' for an inbound file, ulthough it could
also be created because the XPR wanted to reference a file that the WPL author
did not grant it access to.  Notification at the beginning of a transfer of
this type if done via the subroutine pointed to by $(PreInbound) and
notification of success or failure after the file is finished being manipulated
is done via $(PostInbound).

     1 - Mapping was created from an entry in xferq.library.  A batch file
transfer is accomplished within an XPR by calling a specific set of routines
that will find 'the next file to send'.  In order to find the first file, the
XPR would call a function called xpr_ffirst() which would tell it the filename
of the first file to send.  Once that file is successfull, it would call
xpr_fnext() to find the next file to be sent. Whenever a file is found this
way, a mapping between the name given to the XPR (The 'asname' that XferQ
stores) and the full pathname on disk (The 'filename' that XferQ stores) is
made.  Whenever the XPR then tries to open, or otherwise manipulate the file,
it is going to know what actual 'disk file' to allow it to manipulate.
   A mapping of this type is always for an outbound file since the  information
came from XferQ which lists only outbound files. Notification at the beginning
of a transfer of this type if done via the subroutine pointed to by
$(PreOutbound) and notification of success or  failure after the file is
finished being manipulated is done via  $(PostOutbound).

     2 -  Mapping was created by the XprSetFile command which directly gives
the full disk pathname as the first parameter, the 'name that the XPR will
refer to this file as' as the second parameter, and an indicator of what to do
if the file was successfull as the third parameter.
   A mapping of this type can be eithor inbound or outbound, and which one is
being used depends on how the XPR itself wishes to manipulate the file.
  Notification at the beginning of a transfer of this type if done via the
subroutine pointed to by $(PreFullName) and notification of success or  failure
after the file is finished being manipulated is done via  $(PostFullName).



  This list does not in any way determine what the XPR is 'allowed to do with
the file'.  If the XPR wants to delete a file who's name was given to it by
XferQ, then that is it's own buisiness (Ulthough you should probably not use
that XPR any more ;-).  All this list does is determine 'which files can be
manipulated', and provide a mapping between the name that the XPR will use to
manipulate the file, and an actual AmigaDOS pathname to the file it will be
manipulating.


  A typical flow of trying to send a text file with the xprascii library might
be:

  XprSetup "xprascii.library" ""
  XprSetFile network:wpl.language textfile ""
  XprSend textfile
  XprClose


NOTE: The Xpr only knows the filename 'textfile', and when it attempts to open
that filename on the disk, WPL will actually open a file called
'network:wpl.language' instead.




  Mailing List
  ------------

  There is ongoing work with group in mailing list towards a possible XPR 3.0 
specification.  Some full bi-directional transfer will be worked on.

    To join the list, send an Email to:
      xpr-request@aldhfn.akron.oh.us    with "subscribe user@site" as the body
    
     For posts to the list:
       xpr@aldhfn.akron.oh.us


----------------------------------------------------------------------------

  Support Utilities
  -----------------

  The latest versions of these utilities will be file requestable from
the WPL support site, and the list is available via the magic name 'WPL'.


  JBundle  - The latest release of JBundle (Jbun2.rexx) now makes use
      of XferQ to manage the outbound list.  This script will take 4
      dimensional zone.net.node.point.OUT files generated by many mailers
      and do all the required manipulations to compress and add the files
      to XferQ in a very multi-tasking friendly way.

  JTick - A grouping of REXX scripts and AmigaDos binaries to handle
      file echo distribution, file posting, and other related functions.
      Makes use of XferQ for outbound lists.

  Login - A program that allows Welmat/WPL to act as a 'getty'.  Login takes 
      a user name, and will prompt for a users password.  If the password
      matches it will run the given command.  Reads a password file very
      similar to a Unix PASSWD file (Similar to the AmigaUUCP GETTY command).

  LogProc - a REXX message port host that handles multiple logging sessions.
      Currently used as logging system for many WPL based mailers.

  Lookup - A nodelist.library [Igen - a recompile is required for traplist
      support] based utility that will do a nodelist lookup and stick the
      results in environment variables in a form used by many WPL scripts.

  ROOF - Robert Williamson has written many useful scripts including
      a full mailer in WPL, a 'download without having to log into the BBS',
      a WLint program to check WPL programs for correctness, a master files
      list program, and many more.  The file ROOF_WPL.lha is in the WPL
      support files area, and is updated weekly.  More up-to-date versions
      are available directly from it's author.

  xferq.library  - WPL has now completely moved over to XferQ support,
      including all address handling.  The 'seta', 'call' and 'connected'
      functions can accept any address type that XferQ itself can handle.
      WPL programmers should probably file request the complete XferQ
      documentation so that they can make use of the library and AREXX
      interfaces to this shared library in their software.

  XFreqSH - This is a replacement for the old WNotify program [which does not
      work with WPL any more] for use with XferQ based mailers.  Source has 
      been released to the public domain in the hopes that better file 
      request handlers can be written, and that XferQ support will be added 
      to the already existing file request handlers.

  XTool  - This utility allows one to do the bare minimum queue maintenance
      with XferQ.  It does replace most of the functionality of what FloAdd,
      FloEdit and FloList did for flow.library.

  xprclock.library  - A sample library used to get set the Amiga's clock from
      an atomic clock such as the one ran by the NRC in Ottawa, Canada.
      Sources are released as a simple example to people wanting to write
      XPR libraries for non file-transfer usage.

  xprfts.library - Now documented in the separate archive, I am still looking
      for a volunteer to take over the development of this library while I
      take care of other things.  The XPR Update handling is basically
      non-existent, and the display looks extremely poor during an FTS1 or
      DietIFNA session.

  xprzedzap.library - Yves is the current 'Keeper of Sources' to this library
      that is becoming very robust.  The latest version I have seen was
      sent out as zzbin100.lha into ADSCOMM.