ScriptHelp
==========

This help file applies to R.Orwin/A.P. Fitch slipdial script.
Script file Revision 950218

Contents
--------

1.0 Introduction

2.0 Using the script

3.0 Script Requirements
 3.1 Modem Driver
 3.2 Setting up your modem to transmit status messages
 3.3 Making sure that TTFN etc have been "seen".

4.0 Customizing the script
 4.1 To change the default dialler to Mercury.
  4.1.1 To remove your Mercury PIN from a local number.
 4.2 To Alter the Dialler Menu.
 4.3 To Alter the List of Numbers
 4.4 To Alter the Number of Retries.
 4.5 To Add a New Telephone Number.
 4.6 To Change the Local Dialler Icon Number. 
 
5.0 Some Frequently Asked Questions.
 
6.0 Conclusions and Acknowledgements. 
 
1.0 Introduction
================

This script was originally written by Rob Orwin.  I initially modified 
to make it more readable, and also to learn the script language
myself. Recently it has been customised to work with TTFN/Newsbase,
and included in Dr. Alan Hassey's Internet Starter Pack for Acorn 
Computers.

This version of the script incorporates an extra icon bar icon which
can attached to your normal (local) number.  

2.0 Using the script
====================

The script is placed in the !SlipDial.scripts directory.  You can either
load it by dragging it and dropping it on the SlipDial icon bar icon, or
you can set SlipDial up to run the script automatically.  You should read the
SlipDial documentation file !SlipDial.!Help to understand this.

For the default setup with the starter pack, the scriptfile should be named

demon

When the script is run for the first time, it asks for setup information
and stores it in a configuration file.

There are a number of requirements for getting the script to work in
the best way.  In particular, you need to

1) make sure you are using the correct modem driver file
2) set up your modem to return certain messages
3) make sure that TTFN, NewsBase, and TCPIP have been "seen" by the filer

There are also a number of ways you can customise the script.  The
simplest ones are 

1)  to change the default dialler to Mercury
2)  to alter the entries that appear on the menu for dialling
3)  to alter the default entries when dialling a list of phone numbers
4)  to alter the number of times SlipDial retries each number if the
line is busy 
5)  to change the local number 

Slightly more complicated is...

6)  to add a new telephone number

Note that to make changes to the script, you simply have to edit it in 
a normal text editor, e.g. Edit.

With !SlipDial, there is a file called !SlipDial.scripts.DemonSpr,
which  contains sprite definitions.  You must make sure you have the
most up-to-date version of these sprites. If the file contains three
sprites, you are ok - if it only contains 2, you should update it to
the latest one by download it from demon ftp.

3.0 Script Requirements
=======================

3.1 Modem Driver
----------------

The modem drivers are stored in the directory !SlipDial.Drivers. 
There are examples for US Robotics and Hayes modems.  To select the
driver,  look in the script file for the string "driver".  You should
find part of the script like this

#-----------------------------------------------------------
# Subroutine: setserial
# Set Serial Port/Driver Parameters
#-----------------------------------------------------------
:setserial
driver USR
port %wport %prtnum
speed %speed
set protocol slip
return 1
        
To use the Hayes driver, change the line 

driver USR

to 

driver Hayes

3.2 Setting up your modem to transmit status messages
-----------------------------------------------------

If you run the script, and it appears to hangup after the call has got
through but before TCPIP has started; or it doesn't recognise that the
line is busy; then you need to make sure that the modem is returning
messages indicating its (the modem's) status.  These messages are text
strings, and their meaning is defined in the  driver file.  For
instance, with the US Robotics Sportster modem, you need to send the
setup string "X4" to enable all messages.

This means that when the modem detects the line is busy, it will
return the string "BUSY".  You can tell the script to expect the
string "BUSY" to indicate engaged by putting it in the modem driver
file and assigning it to the script variable $busy. When dialling the
modem looks for the string to see if it is equal to the contents of
$busy and uses this to detect engaged lines.

The various possible strings, and their setups for a USR modem are
shown in the example driver file below

set $init "ATB0&M4&H1&R2&I0&K3 AT&B1&N0&S0&Y1&D2&C1 ATV1Q0X4&A2E1F1M1"
set $busy "BUSY"
set $conn "CONNECT"
set $nocarr "NO CARRIER"
set $nodial "NO DIAL TONE"

The $init string is sent to the modem to set it up.  You will notice that
the example above has X4 enabled.     

If you have a modem which returns different strings, you would have to 
create your own modem driver.  For instance, if your modem returned
"ENGAGED", you would have to modify the driver file to contain

set $busy "ENGAGED"

3.3 Making sure that TTFN etc have been "seen".
-----------------------------------------------

The script runs TTFN, Newsbase, and TCPIP automatically.  To do this,
it needs to know where they are.  It can find them if you have opened
a filer window with these programmes visible.  The  simplest way to
ensure that they have been seen is to put all the internet related
programmes in one directory.  Then when you open the directory in
order to double-click SlipDial, you  know that all the other
programmes have been seen.

4.0 Customizing the Script
==========================
                                 
4.1 To change the default dialler to mercury.
---------------------------------------------

Edit the script, and search for the subroutine call

call mercury_off

(it's quite near the top of the script).

Change the line to read

call mercury_on

4.1.1 To remove your Mercury PIN from a local number.
-----------------------------------------------------

If you have a Mercury PIN which is only required for long distance
calls, you will have to remove the PIN from your local number.  By
default the script is set up to use the Isle of Wight as the local
number.
 
To change this, you must modify the makeNumbers subroutine.  The steps
are as follows

a) search for the string :makeNumbers to find the subroutine
b) look through the subroutine for your local number
c) delete the string
   
       %mercury_pin\

   from the front of the number
d) put the above string in front of the old local number (which would
have  been the Isle of Wight in the default case).

As an example - to change your local number from Isle of Wight to
Edinburgh :-


Original (default Isle of Wight) makeNumbers subroutine...

#-----------------------------------------------------------
# Subroutine: makeNumbers
# Make a set of variables to hold the phone numbers.
# By default, this is set up for Mercury users near the Isle
# of Wight. You should of course edit this if you are local
# to somewhere else.
#-----------------------------------------------------------
:makeNumbers
set Birmingham %mercury_pin\01212754848
set Bradford   %mercury_pin\01274755066
set Bristol    %mercury_pin\01179814848
set Cambridge  %mercury_pin\01223576010
set Cardiff    %mercury_pin\01222274848
set Coventry   %mercury_pin\01203284848
set Edinburgh  %mercury_pin\01315528883
set Gloucester %mercury_pin\01452354848
set Hull       %mercury_pin\01482495580
# local number - don't prefix with mercury_pin
set IsleOfWight 01983523306
set Leeds      %mercury_pin\01132984848
set Leicester  %mercury_pin\01162904848
set Liverpool  %mercury_pin\01512104848
set London     %mercury_pin\01813384848
set Luton      %mercury_pin\01582644848
set Manchester %mercury_pin\01613854848
set Newcastle  %mercury_pin\01912474848
set Nottingham %mercury_pin\01159544848
set Preston    %mercury_pin\01772484848
set Reading    %mercury_pin\01734284848
set Saffron    %mercury_pin\01799506010
set Sheffield  %mercury_pin\01142384848
set Sunderland %mercury_pin\01915225005
set Wolverhampton %mercury_pin\01902464848       

Modified (Edinburgh) makeNumbers subroutine...


# local number - don't prefix with mercury_pin
set Edinburgh 01315528883
set Gloucester %mercury_pin\01452354848
set Hull       %mercury_pin\01482495580
set IsleOfWight %mercury_pin\01983523306


4.2 To Alter the Dialler Menu.
------------------------------

The dialler menu has a selection of 'phone numbers from the available
numbers at the time the script was written.  Unfortunately, this leads
to a very long menu!  Also, your particular number may not be on
there, so you may want to modify the menu by searching for the
subroutine

:makemenus

The default subroutine looks like this

#-----------------------------------------------------------
# Subroutine: makemenus
# Defines the menus for dialling etc.  Note menus must be
# less than 255 characters, hence the squashed names.  Also
# this menu does not contain all possible Pops, again due
# to length restrictions.
#-----------------------------------------------------------
:makemenus
menu "Bir:call Bi" "Bri:call Bri" "Car:call Car" "Edin:call Ed" "IoW:call Iw" "Leed:call Le" "Liv:call Liv" "Lond:call Lon" "Lut:call Lu" "Man:call Ma" "New:call Ne" "Not:call No" "Read:call Re" "Shef:call Sh" "Wol:call Wo" "List:call Lis"
menu /icon="Mercury" "Mercury On:call mercury_on" "Mercury Off:call mercury_off"
menu /icon="Local"   "Local call:call Iw" 
return 1

If you wanted to use only Sheffield, Leeds, London, and the list of 
numbers, you could change it to 

:makemenus
menu "Sheffield:call Sh" "London:call lo" "Leeds:call Le" "Shef:call Sh" "List:call Lis"
menu /icon="Mercury" "Mercury On:call mercury_on" "Mercury Off:call mercury_off"
menu /icon="Local"   "Local call:call Sh" 
return 1
                          
Note that the total menu string for any one menu must be less than 255
characters.  Because you have shortened the total menu length, it is
possible to use longer menu entry names (i.e. "Sheffield" instead of
"Shef").

But you must not alter the subroutine names (e.g. don't change
"Shef:call Sh" to "Shef:call Sheffield", because there isn't a
subroutine named Sheffield, only one called Sh).

Note also in the example above, the Local icon bar icon has been
altered to setup Sheffield as the local number (see below).

4.3 To Alter the List of Numbers
--------------------------------

The script has a dialler menu option "List" which dials a sequence
of phone numbers.  For instance, if you normally dial Reading, but
after a number of tries want to try London instead, you can edit
the List menu definition.

To change the List, look for the subroutine makeNumbers.  This is
quite close to the bottom of the file.

The default setup is 

#
#Edit the following line to customise the list of numbers which
# slipdial dials in sequence.  Note that the list is made up
# names defined above, preceded by a '%'.  Note that the spaces
# between the names in the List must be included.
#
# Example - to call hull, bradford, saffron walden in that order
# you would use
#
# set List "%Hull %Bradford %Saffron"
#
# Note that the number of retries made at each number is
# set in the subroutine :Lis
#
set List "%IsleOfWight %London %Reading"
return

Suppose that you want to dial Sheffield first, Leeds second, and
London third.  Then you would modify the second from last line
from

set List "%IsleOfWight %London %Reading"

to

set List "%Sheffield %Leeds %London"

You must include the "%", and also the spaces.


4.4 To Alter the Number of Retries.
-----------------------------------

For each phone number, there is a subroutine.  For instance, for
Bradford, there is a subroutine called Br.  To find this, search
for the string ":Br".

The subroutine looks like this

#-----------------------------------------------------------
# Subroutine: Br
# calls Bradford demon phone number
#-----------------------------------------------------------
:Br
set nRetries 50
set phonenum %Bradford
goto dodial

If you want to alter the number of retries (i.e. how many times 
SlipDial will attempt to dial a number and finding it is engaged
before giving up), change the line

set nRetries 50

For instance, suppose you want to retry 100 times.  Change this line
to 

set nRetries 100

Note: there is a separate number of retries for each phone number in 
the script, and also for the "List" list of numbers.  To change
the number of retries for the List, search for ":Lis".

Note that in the case of the list, the number of retries defined will
be the same for each number in the list.  So if you dial Sheffield, 
Leeds, and London in the list, and set nRetries to 5 in the :Lis
subroutine, SlipDial will

a) dial Sheffield 5 times maximum
b) if Sheffield was engaged, dial Leeds 5 times maximum
c) if Leeds was engaged, dial London 5 times maximum.
d) give up in disgust

The default setup is that all menu items are tried up to 50 times,
except for the list where each number is tried 5 times.  The idea
behind this is that you would only use the List if you were trying
to get through quickly.


4.5 To Add a New Telephone Number
---------------------------------

This is the most tricky one, as you would have to edit the script.  If
you are doing this, you could either

a) copy exactly how one of the other numbers is set up, just change
the number and the subroutine names

b) contact me
       alan@cycle.demon.co.uk
       
and ask me to update the script.   

If you want to do it yourself, remember

1) don't exceed 255 characters in the menu definitions
2) don't use a variable or subroutine name that's already in use
3) remember that the subroutine names are case-sensitive
   
For instance, if Demon opened a line at Lowestoft, you can't use

:Lo 

for the subroutine name, as it has already been used for London.

4) Don't forget to add the new phonenumber to the 

    makeNumbers 
    
subroutine.

4.6 To Change the Local Dialler Icon Number.
--------------------------------------------

This version of the script allow your favourite number to be attached
to an icon on the icon bar. This allows you to dial that number
without having to use the menu item.  However to be useful you must

a) make sure you have the correct version of the file
!SlipDial.scripts.DemonSpr

b) edit the makeMenus subroutine so that clicking on the icon calls
your number, and not the default (which is the Isle of Wight)

c) edit the initMain subroutine to make sure clicking on the icon 
dials the number you want.

For a), you should be ok if you download the up-to-date version of the
script file, as contained in the Acorn Starter-Pack.  If you have a
demonspr file with only two sprites in it, you have got the wrong
version - you can overcome this temporarily by creating a dummy sprite
in the DemonSpr file called loc (short for local).

For b) you need to find the makeMenus subroutine - search for
:makeMenus.  It looks like this by default 

:makemenus
menu "Bir:call Bi" "Bri:call Bri" "Car:call Car" "Edin:call Ed" "IoW:call Iw" "Leed:call Le" "Liv:call Liv" "Lond:call Lon" "Lut:call Lu" "Man:call Ma" "New:call Ne" "Not:call No" "Read:call Re" "Shef:call Sh" "Wol:call Wo" "List:call Lis"
menu /icon="Mercury" "Mercury On:call mercury_on" "Mercury Off:call mercury_off"
menu /icon="Local"   "Local call:call Iw" 
return 1

This sets up three menus.  The last one is attached to the local icon
on the icon bar.  To make Edinburgh your local number, change the line

menu /icon="Local"   "Local call:call Iw" 

to 

menu /icon="Local"   "Local call:call Ed" 

For c), the action on clicking the icon, search for :initMain.  Then
change the line

icon /id="Local" /action="call Iw" loc

to 

icon /id="Local" /action="call Ed" loc

again using Edinburgh as the example.

5.0 Some Frequently Asked Questions
===================================
 
1) When I log on, SlipDial appears to miss the "l" off "login" - is
this a bug?

No - it is recommended by Demon that during login, diallers should
wait for the strings  "ogin:", "otocol:" etc.  See the section "The
Login Sequence" in the file 

         ftp.demon.co.uk:/pub/doc/Demon.txt
         
2) When I start up SlipDial it exits immediately with an error.  What
can I do?

Firstly, this is most likely to be due to the DemonSpr file.  You need
the latest version of this which contains three sprites.  See below
(how to get DemonSpr when !SlipDial isn't working).

However it might be some other problem. The best way of finding out is
to enable the script log.  To do this, edit the script file, and
search for the line

#trace "SlipDial:logoutput"

and change it to 

trace "SlipDial:logoutput"

i.e. delete the #.  This will cause SlipDial to write debugging
information to the file !SlipDial.Scripts.logoutput

You can use the information obtained to try and find out what is going
on.

3) SlipDial starts up, dials, my modem gets through, but then the
call finishes immediately?  

The SlipDial script is set up to watch the DCD (data carrier detect)
line from your modem. If this line remains low, SlipDial will think
the call has finished straight away.  You should check

a) your modem setup
b) your cable
c) your serial interface driver

Be especially careful to match lead and serial driver. The lead can be
either Archimedes wiring or PC wiring - they are not compatible!  Also
the BlockDriver must be set to match the interface port and the cable
wiring.  The BlockDriver loaded by the SlipDial script is defined in
the file !SlipDial.Scripts.demonconfg, which is initialised the first
time your run the script.  Here are some examples

You have a PC wired cable, with an internal port - first two lines of
demonconfg are

InternalPC
0

You have an Arc cable, with an internal port - should lead to 

Internal
0

You have a Serial port Dual interface card, you have connected the
cable to port 1, you have a PC wired lead - should lead to 

SP_DualPC
1

4) I've updated the script, and now it doesn't work because I haven't
got the latest DemonSpr file - how can I log on if the script doesn't
work?

Good question. The simplest answer is to use Paint to create an extra
sprite in the DemonSpr file.  For instance, copy one of the existing
sprites (such as hgon) and rename the copy to loc.  It might be a good
idea to change its colour so that you don't mix it up with hgon.  Then
log on to demon, and download the latest version of DemonSpr.

You can of course create your own sprite, representative of local
traditions and/or landmarks.

5) Last time I logged into Demon I changed my password, and now
SlipDial doesn't work - what should I do?

You have to edit the file !SlipDial.scripts.demonconfg.  The last line
of this should be changed to your new password (which is case sensitive
I believe).

6) I've modified the script, and nothing seems to have changed.

You must make sure the new script has been loaded in.  Quit SlipDial
and  load it again to ensure this.

7) The script never calculates the newsrate - why?

The SlipDial script computes the newsrate by looking at the timestamp
on the downloaded news batch.  If you run Newsbase while you are on
line (for instance so that you can edit and send new mail while logged
in), Newsbase will remove the batch of news before the script can get
at it to measure the timestamp. Hence SlipDial is not able to compute
the newsrate.  

The only way round this is not to have Newsbase running at the same
time as you are on line. 

8) The news rate reported by Newsbase when debatching is not the same
as SlipDial - why?

The newsrate reported by SlipDial is computed by looking at
timestamps, and is an estimate of the speed of downloading news.

The debatching rate measured by Newsbase is simply a measure of the
speed of Newsbase - it has no relation at all to the speed of
downloading.

9) Even though I get good download rates for ftp, and everyone says
Demon is running fast, I can't get good rates from newsrate - why?

The newsrate computed by SlipDial is simply a measure of the
timestamps on the two files DemNG and DemNews.  If you are downloading
other information (for instance mail, or an ftp session), the average
newsrate will be low even if everything is operating at maximum speed,
simply because the available line capacity is being shared by ftp,
mail, and news.

To get a true measure of newsrate, you must have nothing else running
at the same time.

With a 14400 baud modem with mnp5/v42bis you should get 2500cps on a
good day.

6.0 Conclusion and Acknowledgements.
====================================

I hope this helps if you want to modify the script.

I should like to acknowledge Robert Orwin for writing the original
script, and of course thank Graham Allen for writing SlipDial in  the
first place.  Also thanks to Mike James for improving the support for
Mercury numbers. and introducing the Local icon.

Alan Fitch  18th February 1995
alan@cycle.demon.co.uk