Acorn User 3/AUCD3.iso/airport/utils/freecost/!FreeCost/!Help

Text File | 1997-06-24 | 18KB | 449 lines

FreeCost 0.43 Help file - 24 Jun 1997

Contents:

0: Introduction
1: Installation
2: Configuration
3: Running
4: The last call option
5: The online timer
6: Bugs, limitations, contacting the author



0: Introduction

          FreeCost is a simple little utility that tells you how much
  money you have spent on phone calls to your internet service provider.
  It does this by looking at the log files produced by the dialler
  program (eg FreeDial) which record when the calls started and
  finished. The information is saved as a text file, which you can
  browse at your leisure.
          At the present time, three dialler programs are
  properly supported. These are SlipDial (version 0.35+), FreeDial
  (version 0.23+) and the ANT Internet Suite (version 2?).

     Licence
     ~~~~~~~
     FreeCost is Copyright © Rik Griffin of Squeaky Software 1996 and 1997.

     This application may be distributed freely, as long as no charge is
     made, except for reasonable media costs. No modifications may be
     made to versions being distributed, except for alterations made to
     the configuration files as instructed below.

     BBSs or FTP sites wishing to distribute FreeCost should ensure that
     the 'Toolbx.zip' archive containing the Toolbox modules is also
     available from the same place. I would also appreciate being told
     that a site is carrying my program, so I can send out updates when
     they become available.

1: Installation

  This is very simple. Just copy FreeCost to a directory of your choice.
  If you wish to run FreeCost from a read only filing system, You'll
  need to edit the !Run file, and redefine the variable FreeCost$Options
  to point to somewhere writable.

  FreeCost needs Acorn's ToolBox modules, and if you haven't got them
  loaded already, will look for them in System:Modules.Toolbox. The
  required modules will not have been supplied in the same archive as
  the main program, due to their size. They should be available from the
  same place that you got FreeCost from, in an archive called
  'Toolbx.zip'.

  Use the SysMerge application to update your !System directory, unless
  you have RISC OS 3.5 or greater, in which case open the configuration
  window (by running !Boot) and click on the System icon. Drag the
  supplied !System directory to the window that opens.


2: Configuration

  FreeCost comes preconfigured for customers of British Telecom. If you
  don't use BT, you have to edit the !FreeCost.Resources.UK.Config file.
  If you want to calculate costs for non-local calls, you'll also have
  to edit at least some of the config file.

  The config file consists of comments and tokens. The comments start
  with a # character, and everything else is a token. When you edit the
  file, you must only change whatever comes after the colon (:) in a
  token. FreeCost only uses one currency unit, in the UK this would be
  pence, however as long as you are consistent, it can be anything you
  want.
  If your phone company also charges you some form of tax on top of
  the basic rate, this is configured separately, so enter all the cost
  information WITHOUT tax added.
  For example, BT has to charge VAT at 17.5%, so don't add this to any of
  the charges you input, but set the TAX_RATE token to 0.175.

  The first tokens that you should change are listed below:

    MIN_CHARGE: The minimum charge for a single call. For BT, this is
                4.2 pence (before tax).

    TAX_RATE:   The local rate of tax on the charges. In the UK, this is
                17.5%, so set the token to 0.175.

    EXTRA_TIME: When you dial up a service provider, your modem spends a
                few seconds talking to their modem, before the dialler
                program sees that a connection has been made, and logs
                the call. This takes about 20 seconds for calls to Demon
                Internet. This token's value is added to the length of
                all the logged calls, to partially compensate for this
                inaccuracy in the logs.

  The next set of tokens are of the form "BAND_t_n" where t represents
  the time band and n represents the number-related band. These tokens
  are used to define all the different possible call costs. The number
  related band can be used to apply different costs for diffent dialing
  codes, and the time band is selected depending on the time of day that
  the call was made. The costs are expressed per unit, and you define
  what a unit is in the next section. For BT, it would be 1 second.

  So, the phone company might have three different time-based charges
  (BT has weekend, weekday off-peak and weekday peak) and three
  different distance bands. Also you might make some calls via another
  phone company, such as Mercury, which can be recognised as they start
  with a special code.

  At the moment the program only supports three time bands and five number
  bands, but if you don't need this many, just set the unused ones to
  zero. They all have to be set to something though. If you think you
  need more, mail the author!

  So, for the above example, you would set the tokens as follows:

    BAND_1_1:0.01500
    BAND_2_1:0.02333
    BAND_3_1:0.05667

    BAND_1_2:0.04667
    BAND_2_2:0.05667
    BAND_3_2:0.11667

    BAND_1_3:0.04667
    BAND_2_3:0.08333
    BAND_3_3:0.14000

    BAND_1_4:<mercury_weekend_charge>
    BAND_2_4:<mercury_offpeak_charge>
    BAND_3_4:<mercury_peak_charge>

    BAND_1_5:0.0
    BAND_2_5:0.0
    BAND_3_5:0.0

  A limitation of this is that the same time bands are applied to all the
  numbers, whereas in fact, the two phone companies might not use the same
  time bands. I'll try to provide a solution for this in a future version.

  Now, you have to set up the tokens that define the length of a unit
  during each time band. The tokens for this are of the form UNIT_t_n.
  For BT use, set them all to 1.

  For example, if your phone company charged 5p for 100 seconds at cheap
  rate, and 4p for 30 seconds at peak rate, you would use these tokens:

  BAND_1_1:5
  BAND_2_1:4

  UNIT_1_1:100
  UNIT_2_1:30

  and of course the tokens for the different number based bands as well.

  Some phone companies charge varying amounts of money for a constant
  length of time (like BT). Others charge a constant amount of money for
  a varying length of time. This is why you have to set both of these
  sets of tokens. I don't know of any that vary both the price and the
  unit length, but FreeCost can cope with that as well.

  Next you need to specify when each time band is in force. The next 7
  tokens define a 'map' of all the hours in a week, and specify which
  charge band is applied to each individual hour. The one below is for BT:

    DAY_0:111111111111111111111111
    DAY_1:222222223333333333222222
    DAY_2:222222223333333333222222
    DAY_3:222222223333333333222222
    DAY_4:222222223333333333222222
    DAY_5:222222223333333333222222
    DAY_6:111111111111111111111111

  This means that band 1 applies all day on DAY_0 (Sunday) and DAY_6
  (Saturday).
  Band 2 applies from midnight to 8am on all weekdays.
  Band 3 applies from 8am to 6pm all weekdays.
  Then Band 2 applies from 6pm to midnight all weekdays.


  Next, you configure any phone numbers that you want to be in a number
  band other than band 1. All numbers except those in the list you define
  here default to using rate 1. (The rates defined above with tokens
  BAND_1_1, BAND_2_1 and BAND_3_1)

  To define these tokens, use a pattern of digits to be matched, and use a
  * character as a wildcard that matches exactly one digit. Each string
  must be followed by a comma. For example:

    NUM_BAND_1:0151*******,
    NUM_BAND_2:01274******,
    NUM_BAND_3:0181*******,0171*******,
    NUM_BAND_4:131***********,132***********,
    NUM_BAND_5:

  Thus any numbers starting with 0151 and containing exactly 7 more digits
  will be charged at rate 1. Numbers starting 01274 with another 6 digits
  will be charged at rate 2. And so on. You can leave these five tokens
  blank if you like, and all numbers will be charged at rate 1.
  You can't define a token larger than 255 characters, so bear this in
  mind when making up these lists.


  Now you should set up the tokens that name the various bands. Set
  any unused tokens to be blank.
  First, the TIME_NAME_t tokens set the names of the three time bands, for
  example:
    TIME_NAME_1:Weekend
    TIME_NAME_2:Off peak
    TIME_NAME_3:Peak

  And the NUM_NAME_n tokens set the names of the number related bands. eg:
    NUM_NAME_1:Local
    NUM_NAME_2:Regional
    NUM_NAME_3:National
    NUM_NAME_4:Mercury
    NUM_NAME_5:


  When you've done all this (gasp pant), you are ready to run FreeCost !

  Last minute note: I lied! You have to edit one more thing if you don't
  live in the UK. In the !Run file, the last line will be something like
  this:

    run <FreeCost$Dir>.!RunImage -terr UK

  Change the UK to the name of the territory you want to use. The other
  two provided in this release are:
  NL - Netherlands
  SA - South Africa

  This territory name is used to find the resource files. So if you run
  FreeCost with 'UK' as the territory, the resource files needed are:
  <FreeCost$Dir>.Resources.UK.Res
  <FreeCost$Dir>.Resources.UK.Messages
  <FreeCost$Dir>.Resources.UK.Config

  So if you wanted to translate the files into German, for example, you
  would make a directory <FreeCost$Dir>.Resources.DE, and put copies of
  the 3 files into there. Messages and Config are text files. Res is a
  toolbox resources file, and you need !ResEd to edit it.

  If you translate my files into another language, please mail me a
  copy, so I can include this in the next release. Also, note that the
  NL and SA files are incompletely translated. I would be very grateful
  for complete versions!

  If you wish to use the last call option (see later) you will have to
  change the !FreeCost.!Last file in the same way as the !Run file.


3: Running FreeCost

  To run the program, just double click the !FreeCost icon. It will be
  installed on the icon bar.

  Click MENU over the iconbar icon, and the main menu will be shown. There
  are 4 entries, Info and Quit are obvious, the other two are explained
  below:

    Options... Opens the options window. See below for details.

    Auto... Select this option to auto detect which dialler program you
        use, and read in its log file. If this fails you will have to
        find the log file yourself, and drag it to the iconbar icon.

  To start processing a log file, either select Auto... from the menu, or
  drag the log file to the FreeCost iconbar icon. The results window will
  open. This contains a short summary of the call costs, grouped by time
  band, plus the overall cost.

  There is also a save dialogue in this window. Drag the file icon to a
  directory display to save the detailed results file. This file contains
  an entry for each call you made, detailing the length of the call, and
  its cost. If you turned on the 'Add tax' option, then an extra column
  details the tax added to the cost of each call. A total is shown at the
  bottom.

  Clicking SELECT on the icon bar icon is a short cut to the Auto ...
  option.

  The Options window.

  This window contains four groups of options. The first is 'Logging
  options', and there are 2 option buttons. 'Add VAT' causes the
  configuraed tax rate to be added to the cost of calls. 'Count bad
  calls' causes badly logged calls to be included in the cost
  calculations, at the minimum charge. Calls can get badly logged if
  your internet software crashed whilst online, for example

  In the section titled 'Log file type' are several radio icons.
  Normally you should leave 'Autodetect' selected. However, if FreeCost
  does not accept a file that you think is a valid log file, try
  changing this setting to override the autodetection. Note that this
  may produce erroneous results if the file is not actually a valid log
  file, but FreeCost will not reject it.

  The 'Process since' section contains three controls for setting a
  date. When processing log files, FreeCost ignores all calls before
  this date. So you could set this to the date of you last phone bill,
  for example, and find out how much the next bill would be.

  Finally, there is 'Online timer'. If the 'Show timer' option is
  ticked, the timer window will be shown when you are online. If 'Add
  VAT' is ticked, the cost shown in the timer window will include tax.
  If 'Extra time' is ticked, the timer will take into account the extra
  time that you configured in section 2.

  The timer window can be shown in one of 5 default places, select which
  you want from the pop up menu labelled 'Default position'. To allow
  the online timer to properly calculate the cost of a call, it needs to
  know the charge rate of the number you are calling. Select the number
  band from the next pop up menu. FreeDial sets a variable Inet$Phone
  which holds the phone number dialed, so FreeDial users can select this
  option.

  The final option is 'Poll every' which sets how often (in seconds) the
  online timer is updated. If you have a slow machine, you may find it
  beneficial to update less frequently. I haven't investigated this in
  much detail, feedback on performance issues is most welcome.

  Please see section 5 for more details about the online timer,
  especially if you don't use FreeDial.

  Clicking 'Save' will save the options the the file pointed to by
  FreeCost$Options. Clicking 'Cancel' will restore the previous
  settings.


4: The last call option.

  There is a second way of running FreeCost, which is to run the file
  <FreeCost$Dir>.!Last. This will output the length and cost of the last
  call in the logfile to a message box, then FreeCost will quit. The
  idea of this is to call FreeCost in this way when your internet
  software hangs up the phone, thus you will know how much money you
  just spent.

  For example, FreeDial users could put the following line at the end of
  the !FreeUser.Files.FreeDial.Stacks.FreeNet.!ShutDown file:

  Filer_Run <FreeCost$Dir>.!Last

  Users of other dialer software (SlipDial, ANT) will have to work out
  where to put the command themselves, sorry! Please let me know if you
  do this, so I can put the information in the next Help file.

  What the !Last file actually does is call !FreeCost.!RunImage with
  the -last switch. By default, when called with the -last option,
  FreeCost will attempt to autodetect the log file. To override this,
  use the -file <filename> switch.

  For example:

  Filer_Run <FreeCost$Dir>.!RunImage -terr UK -last -file <Inet$Dir>.CallLog

  or more simply:

  Filer_Run <FreeCost$Dir>.!Last -file <Inet$Dir>.CallLog

5: The online timer

  If you have selected the 'Online timer' option in the options window,
  then FreeCost keeps a look out for a system variable called
  Inet$Timer. This variable is set by FreeDial when it dials, and it is
  a code variable that simply counts the elapsed time. FreeDial also
  sets Inet$Phone to the phone number dialled, and if you have selected
  the appropriate option, FreeCost will use this variable to work out
  the rate of the call.

  This variable might be set by other software also, you'll have to try
  it out. Note that if the variable is invalid in any way, or the
  number is not in your config file, the call is treated as band 1
  (local), which for most people will be correct anyway.

  If you don't use FreeDial, but would like to use the online timer,
  then you will have to arrange to set the Inet$Timer variable yourself,
  as described below.

  When you go online, the command

    <FreeCost$Dir>.SetTimer Inet$Timer

  needs to be issued. This starts the timer.

  When you go offline, issue the command

    <FreeCost$Dir>.UnsetCV Inet$Timer

  which stops the timer.

  These two utility programs are included with FreeCost, but were
  written by Gert-Jan de Vos, author of FreeDial. Many thanks to him for
  permission to distribute them with FreeCost.

  If you lose the timer window, click Adjust on the iconbar icon.

6: Bugs etc.

  There may be problems with ANT logs, I haven't tested this part very
  much yet. Reports of successes and failures are welcome. If reporting
  a problem, please send me the log file that causes the problem.

  The online timer needs more testing, and is not guaranteed bug free.
  Again, reports of any sort are always welcome.

  The time taken by the timing algorithm to calculate the cost of any
  call is proportional to the length of that call. If the online timer
  is in use, the call cost is normally recalculated every second. It is
  possible that a really long call would take so long to cost that
  FreeCost would place a significant load on the system.

  If you find this is the case, reduce the frequency of polling in the
  options window. However, Ran Mokady's !Usage application shows
  FreeCost as using 2% of CPU time when costing a 1 hour call, and 7%
  for a 12 hour call, when polling every second (RiscPC, ARM 610, RISCOS
  3.60). Also, note that this is only an issue when the online timer is
  active.

Limitations:

  Only a single set of time bands, despite the fact that different
  numbers might have different time charges associated with them.

  I don't really know what to do when a time based charge band changes
  part way through a time unit. For 1 second units, this isn't a problem
  obviously. The present solution is merely to switch unit lengths
  immediately, and count the time expired so far (against the old unit
  length) against the first new unit length.

  FreeCost can't cope with call charges that change part way through a
  call (except for changing of time bands of course), for example BT
  customers who get a "surprise saver".

Contacting the author

  FreeCost was written by Rik Griffin of Squeaky Software.

  Feel free to email me with any comments about this program, especially
  if you find any bugs.
  Mail to: [e-mail]

  Why not check out TANKS from Werewolf Software? It's a multi player
  game of skill and cunning. See http://www.werewlf.demon.co.uk/

  And watch out for the next Squeaky Software game ... coming (not very) soon!