PPPWahl

Version, Copyright, Purpose, History -> see !Help

Lizense:
--------

Thanksware, that is whoever uses it is requested to send me a thanks mail to mailto:BinDabei@HQ.gag.de. Questions/suggestions etc. pleas to
mailto:HzN@HQ.gag.de.

The PPPWahl package may be passed on unchanged and complete only.


Prerequisites:
--------------

Acorn TCP/IP-Stack with PPP module and Acorns resolver Module (to be
found on the Acorn User 200 CD e.g.). Blockdrivers (Application
!SerialDev) and the module Serial Buffer from David Pilling.

Front- and Backend:
-------------------

This packages consists of two parts: The backend PPPWahl which does the
work and the frondend !PPPWahl which is based on The Menu. With the latter
you can launch star commands and thus call PPPWahl.


Calling the backend:
--------------------

PPPWahl is called with two parameters: the options and the parameter file.

Options:
L Log the activity on screen. Since this is done in a simple way the log
  goes to the task window or a command window depending on how it's called.
D This disconnects. In case no parameter file is stated the parameter file
  used for the last call will be taken (unless the system has been booted
  since this file name is stored in a system variable which disappears upon
  booting).
Q Queries the state of the PPP connection. This looks at the output of
  the command *PPPLog.

Parameter file: In thie file the parameters needed for connecting are listed
one by one in separate lines. (Lines starting with a ";" are comments.)

Blockdrivers name             (e.h. InternalPC for the interenal
                               interface using a standard PC wire)
Port of the block driver      (for the internal one always zero: 0)
Baud rate/speed               (e.h. 152000)
Modem reset command           (AT command to reset the moden,
                               e.g. ATZ)
Modem init command            (AT command to initialise the modem,
                               e.g. AT\N10%P1)
Modem disconnect command      (Command to hang up, usually +++ATH0)
Modem dial command            (Command to dial including the phone number)
Name server                   (List of the IP addresses of the name servers;
                               several separated by spaces are o.k.)
Parameter for *PPPConnect     (see below)
Star command to be called when connection is established
Star command to be called when connetion was dropped
Star command to be called upon error (e.g. *Error)

Sample parameter file:
InternalPC
0
152000
AT&F
AT\N10%P1
ATD0191011
+++ATH0
194.25.2.129
+ua <PPPWahl$Dir>.Userid noipdefault defaultroute crtscts modem mru 1524
<PPPWahl$Dir>.Start
<PPPWahl$Dir>.Stop
*Error


What it does:
-------------

If a connection shall be established PPPWahl does this:
0. Remember the name of the parameter file in the system variable PPPWahl$File.
1. initialize the block driver using the first three parameters from the
   parameter file (blockdriver, port, baud rate)
2. Reset the moden using the string from the parameter file. Here PPPWart
   just waits a short moment for a reply so that this command should be
   short.
3. Initialisze the modem using the respective string from the parameter file.
4. Dial ...
5. Issue of the command *PPPConnect with the interface parameters (block
   driver, port, baud rate) and the parameters for the *PPPConnect from the
   parameter file.
5. Check if the connection is established by analysing the output of the
   command *PPPLog (this check should be possible using the SWI PPP_Status,
   but I didn't find any docs on this).
6. Launch of the command to be issued upon connect according to parameter file.

In case an error occurred at some place the connection is droppend and the
error command is called with the error message.

If the connection is to be dropped, PPPWahl does this:
0. In case no parameter file has been specified use the one stored in the variable
   PPPWahl$File.
1. Check if the PPP connection is up (looking at *PPPLog's output).
2. If PPP is up it's disconnected issuing a *PPPDisconnect.
3. If no PPP is up the block drivers are initialised as usual and then the modem
   connection is dropped using the respective command from the parameter file.
4. Launch of the command to be issued upon disconnect according to parameter file.

In case of a query PPPWal does this:
0. In case no parameter file has been specified use the one stored in the variable
   PPPWahl$File.
1. Check if the PPP connection is up (looking at *PPPLog's output).
3. Output of the results.


The frontend:
-------------

The frontend !PPPWahl is based on The Menu (by me too by the way) so please
consult the documentation of that in case you want more infos. Here I'll just
look at the things needed for PPPWahl.


In !PPPWahl is a file names TheMenu containing the control data for The Menu:

The first line is the title of the menu which is displayed. I chose PPPWahl as title.

The next line is the first menu entry containing of the text to display, a tab, a "T",
another tab and then the star command to be launched. In further lines more of these
kinds of entries follow.


Example for freenet.de
----------------------

This example is no dummy by the way, but works in Germany - just the parameters
for the blockdriver and the modem commands might have to be amended. Freenet.de
offers a dialup without registration but if you want to stick with them you
should register to get email and reduced costs.

The parameter file for freenet.de is named PFreenet in !PPPWahl (this file can
certainly be put anywhere else) and contains this:

InternalPC
0
152000
AT&F
AT\N10%P1
+++ATH0
+ua <PPPWahl$Dir>.UFreenet modem defaultroute
<PPPWahl$Dir>.Start
<PPPWahl$Dir>.Stop
*Error

We obvously need three mor files in !PPPWahl for this since the parameter file
references them.

In the file UFreenet is the userid and in the line below the password - that is
the way *PPPConnect wants this info for PAP-Authorisation which is done due to
the parameter +ua.

The file Start in !PPPWahl can e.g. launch !POPStar, !Newshound, a browser or
the like (or not). It's called whenever the connection is established. Here
you can e.g. change the backdrop colour so show that you're online (thus your
phone bill is growing).

The file Stop is called upon disconnect and in case in Start you changed the
backdrop you should reset it to the default here.

Now let's look at the file TheMenu; the tab (it has to be a real tab, not spaces)
is shown here as underscore:

PPPWahl
Freenet_T_<PPPWahl$Dir>.PPPWahl L <PPPWahl$Dir>.PFreenet
Logoff_T_<PPPWahl$Dir>.PPPWahl DL
*PPPLog_T_*PPPLog

As you can see in the logoff entry the parameter file (and thus the priovider)
is not mentioned so that the last used one will be used. Please note that
PPPWahl is happy to cope with sevaral providers (that was one of the reasons
for me to write this) - all you need is the parameter files for each one.

Tips:
-----

Using !POPStar and !Newshound you can set up a parameter file which (I'll
use the one above for this) where news and email is picked up and after that
the connection automatically dropped.

1. In the aforementioned file !PPPWahl.Start you put the command line
   '<POPStar$Dir>.!Run' so that as soon as PPP is up !POPStar runs.
   Or you just put '<POPStar$Dir>.!Run' insted of '<PPPWahl$Dir>.Start'
   in the parameter file !PPPWahl.PFreenet but using the separate file
   enables you to launch !Newsbase, !Messenger etc. too.

2. You can configure !POPStar so that it runs a command upon completion.
   Here you put in '<NewsHound$Dir>.!Run' so that after !POPStar is done
   !Newshound is automatically launched.

3. You can configure !NewsHound likewise and here you put in the command
   '<PPPWahl$Dir>.PPPWahl D' to be called when !Newshound is finished.
   This will disconnect the modem.

In case you don't want to run !POPStar and !Newshound sequentially you can
launch both and set some counter (e.g. PPPWahl$Count) to "2" since you ran
two files. Then you need an obey file which is run when !POPStar and !Newshound
is doen like this:
*if "<PPPWahl$Count>" = "1" then <PPPWahl$Dir>.PPPWahl D
*if "<PPPWahl$Count>" = "2" then Set PPPWahl$Count 1

Just to keep things clean the file !PPPWahl.Stop should then issue a '*Unset
PPPWahl$Count'.


