                               HELP ON VOTEFILE v2.01
                               ~~~~~~~~~~~~~~~~


Purpose:
~~~~~~~~
   This program is designed to scan through your CastAWote 'Data' file and
   warn you of possible errors.

   You see, CastAWote isn't perfect. In a worst case scenario, up to five
   instantations of CastAWote can be fighting to access the CastAWote data.
   [this is greatly reduced now, with the aid of VoteModule...]
   Luckily the chance of errors are now slim, however there were problems in
   the past. Due to early VoteEdit's (for CastAWote 2.50 and previous) method
   of fixing errors, many people didn't bother. Currently VoteEdit (for 3.00)
   has no checking routines.

   So here is the cure!



How to use VoteFile:
~~~~~~~~~~~~~~~~~~~~
   Once CastAWote has been 'seen' by the filer, you can run this program.
   Simply double-click on it. You will see the introduction screen. Press a
   key to scan the first vote, then press a key for each vote.


   Don't want to press keys? Well you can run this program in what is known
   as 'fast' mode. Simply run like:
      VoteFile FAST
   This will skip the press-a-key bit.

   The ideal use for this is to create this obey file:
      Set VoteFile$Dir <Obey$Dir>
      Spool <VoteFile$Dir>.Recording
      Run <VoteFile$Dir>.Code FAST
      Spool
   This will zip through your data and output everything to the file
   "Recording".


   But... You may now be thinking, "Okay, so this cool thing is loaded. If it
   can identify problems, why doesn't it do something about them?".

   Ah - gotcha there. It can.
      Set VoteFile$Dir <Obey$Dir>
      Spool <VoteFile$Dir>.Recording
      Run <VoteFile$Dir>.Code FIX
      Spool
   The FIX parameter automatically selects 'fast' mode. The corrected 'Data'
   is written as 'Fix_Data'. The original is not touched. It is anticipated
   that VoteEdit will call this program to fix, and copy 'Fix_Data' as 'Data',
   which is what you should do.



Relative timings:
~~~~~~~~~~~~~~~~~
   Time taken in 'fast' mode to scan 1 vote  . . . . . . .  1 second.
   Time taken in 'fix' mode to scan and fix 1 vote . . . .  1 second.
   Time taken in 'fast' mode to scan 100 votes . . . . . .  9 seconds.
   Time taken in 'fix' mode to scan and fix 100 votes  . . 10 seconds.
   Time taken PC version in 'fast' mode  . . . . . . . . . Doesn't support 'fast'.



Messages you may see:
~~~~~~~~~~~~~~~~~~~~~
   Examining question #xx (of #xx)...
      This informs you what question is being examined. A listing of what is
      in that question follows. This is for 'informational' purposes.


   ...question xx contains xx error(s), use !VoteEdit to repair.
      This tells you how many errors were detected.


   [fixed!]
      This appears after the above message when in 'fix' mode.


   [This program is running in 'fix' mode]
      This also appears in the initial screen (with a bleep) when in 'fix'
      mode.


   (Acorn version, C)
      Believe it or not, there is a PC version. It is totally crap, but that's
      the OS - not my programming. :-)


   (PC version, C)
      And when you see this, you're sad enough to be using the PC
      version I was sad enough to code... :-)


   ERROR! Sorry, the CastAWote data file cannot be opened. Aborting...
      Has CastAWote been 'seen' by the filer? Is there a 'Data' file? Is
      the file locked against read access? Check and try again.


   ERROR! Sorry, the CastAWote fix file cannot be created. Aborting...
      Has CastAWote been 'seen' by the filer? Is there an existing 'Fix_Data'
      file? Is the file locked? Check and try again.


   ERROR! Sorry, this Data file is too short. Aborting...
      This occurs when this input file is less than 55 bytes, which is the
      smallest reasonable size for a blank file (the 'null' blank file
      created by CastAWote is 55 bytes in length).


   Oooopppps! Major errors when reading a string.
   I'm looking for a '[00]' byte and didn't find one.
   There is a possibility your votes data is corrupted.
      or
   Oooopppps! Major errors when reading a word.
   I'm looking for a '[40]' byte ('@') and didn't find one.
   There is a possibility your votes data is corrupted.
      This appears whilst reading data if there is an unexpected end-of-file.
      If you get this message, your data will not be recoverable except by a
      quick stint with !Edit or !Zap.
      If an original BudgieSoft program corrupted the file in 'normal'
      operation, I'll have a go at rescueing the data for you - send me the
      data file. Note, the chances of full recovery are slim.


   Error, read in non 0x40 (was xx) - file possibly corrupted?
   Next five bytes are: xx, xx, xx, xx, xx.
      Because of 'limitations' in the PC compiler, I coded this for myself as
      a test routine (wasn't picking up the next data block and compiler did
      not tell me I left the '()' off of a routine call. So I coded this nice
      little thing...

   Basically, if the non value is '0x00' it fluffed trying to read in a
   string. If the non-value is '0x40', it fluffed trying to read a word.


   Please press a key to begin...
      Well?


   A total of xx errors were found...
      This appears at the end of examinations in 'normal' or 'fast' mode.


   A total of xx errors were found and fixed...
      This appears at the end of examinations in 'fix' mode.


   BYE!
      Byeeee!


   xxx string is outmoded '{/}' null.
      In early versions of CastAWote, the sequence '{/}' meant "". This has
      now been removed, but it is not inconceivable that a few remain.
      Replaced with "".

   xxx text is too short (less than x characters).
      All text, except additional information and options, should be at least
      two or three (depending on which string) characters in length.
      Replaced with "<invalid data fixed by VoteFile>".


   xxx text is too long (over 60 characters).
     - this could cause serious problems!
      And it can! :-) The limit is 60 characters. This applies to all strings.
      Replaced with the original text truncated at 60 characters.

   OPTION_x has no text!.
      Options one and two MUST have text.
      Replaced with "<invalid data fixed by VoteFile>".


   The creator of this question is Anonymous.
      This is not strictly an error, more a warning - and therefore is not
      fixed. 'Anonymous' means something went wrong when CastAWote tried to
      read the user name from the BBS server...


   The option results (xx) do not equal the total (xx).
      This occurs if the added-up results do not equal the total voted
      counter. This can get confused with null-options that have results or
      votes 'tagged' with old software.
      You no longer need two passes of VoteFile to correct this if it is
      caused by null votes with results or vote tagging (first fix the
      result, then fix the title)... VoteFile can handle it. :-)
      Replaced total voted counter with results added.


   Weird additional info strings (check 1)
      The additional information strings are weird. In this case, line one is
      blank and line two isn't blank.


   Weird additional info strings (check 2)
      The additional information strings are weird. In this case, line two is
      blank and line three isn't blank.


   Weird additional info strings (check 3)
      The additional information strings are weird. In this case, line one is
      blank and line three isn't blank.


   Option xx extended beyond end-point (yy;zz).
     This appears if - say - options one, two and three contain data; option
     four and five is blank and option six contains data.
     The value of 'xx' points to the option extended (6 in this example).
     The value of 'yy' points to the end point (4 in this example).
     The value of 'zz' points to the option extended (6 in this example).
     'xx' and 'zz' are the same.
     Replaced by "".


   Option xx has no text but does have a result.
      This occurs when an option has a result but doesn't have any text. This
      messes up the results count and the totals.
      You no longer need two passes of VoteFile to correct this (first fix
      the result, then fix the title)... VoteFile can handle it. :-)
      Replaced by '0'.


   This vote has been marked as 'tagged' by old software.
      This may be left-over from previous versions of CastAWote that shoved a
      '-1' into option 7 or option 8 results (unused then) to indicate vote
      was 'tagged'.
      You no longer need two passes of VoteFile to correct this (first fix
      the result, then fix the title)... VoteFile can handle it. :-)
      Replaced by '0'.


   This vote has not been updated, please run the votes convertor.
     - you will find this in the 'VoteConv' directory.
      In order to use NVP with CastAWote, you need to engage in some really
      quick hacking to the data file. A little utility called "VoteConv" will
      do this for you. Run it once and all is fixed.
      VoteFile puts in null corrections. You should still run "VoteConv" as
      soon as you can because otherwise you won't have any old votes
      identified as "local".
      Replaced system_addr with "<bbsname> @ 0:0/0.0".
      Replaced software_options with "CastAWote 3.00 alpha/- (ArcBBS)  000000
      0000000000"


   This file was fixed and recreated by:
   VoteFile version 2.00 (4th January 1994) *ACORN VERSION*
   (C) copyright 1996 Richard Murray
      This is tacked on to the end of the Fix_Data file to identify what it's
      all about. If this is renamed 'Data' and accessed by CastAWote or NVP
      or VoteEdit, upon saving, this data will be omitted.



Knopfler:
~~~~~~~~~
   Some releases include the 'Knopfler' code (named after the lead singer of
   Dire Straits - which is what I am listening to at the moment).

   Knopfler **OVERWRITES** the CastAWote 'Data' file (awooga etc, make a
   backup before you run this) and creates a thoroughly nasty 'Data' file to
   test VoteFile.

   Do not try and run CastAWote or NVP or VoteEdit with this file. Behaviour
   is unpredictable (see below).

   However, since VoteFile is designed to remove all the crud from the 'Data',
   I thought I'd give it loads of crud to examine.

   It builds up a five-question 'Data' file, with the following errors:

   Vote one:
      No creator.
      Question is 128 characters in length.

   Vote two:
      Question is only one character in length.
      Vote option four is over-extended.
      No flags data present.
      Additional Information line three has text, lines one and two do not.

   Vote three:
      Creator is 'Anonymous'.
      Total does not match the results of each option.
      All options have results, but only three options have text.

   Vote four:
      Everything is madness and on maximum overdrive... All strings are 255
      characters in length and all numerical bits are set to '36624'.
      Consequently, the total doesn't match the options.

   Vote five:
      Is totally blank.


   So what do I mean by unpredicatable?

     CastAWote - Copes well until vote #4 where it crashes with a 'string too
                 long' error.
     DoDisplay - Crashes with a 'string too long' error.
     NVP       - Not tested.
     VoteEdit  - Copes quite well... The icons in the editor and listvotes
                 window get screwed up, and vote#5 is inaccessible through
                 VoteEdit. Hmmm...

     So use this output to test VoteFile, like you're supposed to. :-)



So where's the BASIC code gone?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   Hehehe... Welcome to my very first C program. :-)



PC version!?
~~~~~~~~~~~~
   A little practical joke of mine. The PC version is locked into 'fix' mode
   (with 'fast' disabled). Stick the code into a DOS directory and run.

   It will look for "DATA.CAV" in the same directory. It will write a file
   called "FIX_DATA.CAV".

   When it feels like it, you may get a burst of colour.

   Basically everything looks kinda the same, except it takes quite a while
   to run on PCEm (software).


   NO!
   I did not copy the code directly over to the PC and compile...

   Firstly:
      --8<--------
      #include <string.h>
      #include <stddef.h>
      #include <stdio.h>
      #include <stdlib.h>
      #include "swis.h"
      #include "bbc.h"
      #include "kernel.h"
      --8<--------
   became:
      --8<--------
      #include <stdio.h>
      --8<--------

   The compiler was a bit 'odd'.

   The compiler didn't like parameter passing through functions, so:
      --8<--------
      void read_string(FILE *file, char *string);
      int read_word(FILE *file);
      void write_string(FILE *file, char *string);
      void write_word(FILE *file, int num);
      void loadquestion(void);
      void examinequestion(void);
      void updatequestion(void);
      --8<--------
   became more like:
      --8<--------
      char read_string()
      int read_word()
      void write_string()
      void write_word()
      void loadquestion()
      void examinequestion()
      void updatequestion()
      --8<--------
   Note also the ";" is missing from the PC equivalent. The compiler got 
   upset by declarations.

   Due to the lack of variable passing, a nice simple:
      --8<--------
      read_string(file_handle,creator);
      read_string(file_handle,system_addr);
      --8<--------
   becomes:
      --8<--------
      read_string();
      strcpy(creator,string);
      read_string();
      strcpy(system_addr,string);
      --8<--------

   And finally, a few other incompatibilities:
      --8<--------
      {
         _kernel_swi(OS_ReadC,&r,&r);
         junk_variable = r.r[0];
      }
      --8<--------
   and:
      --8<--------
      if (fastmode == TRUE )
         os_swi1(Wimp_CommandWindow,-1);
      --8<--------

   If you don't understand any C, read it like "PC's suck!". That's close
   enough. :-)



Fanks:
~~~~~~
   Exclusive fanks go out to:

      Ricky Sarge; for the word/string read/write routines, and for sending
        me loads of sources to conversions of my programs in the hope that
        one day this whole C lark will finally 'click'.
      Keith Hall; for reassuring me that the all-singing-all-dancing stdio
        library is totally incabable of just 'reading' a keypress, and for
        instructing me as to how to use _kernel_swi. Keith, you forget to
        mention that I need to include "kernel.h". Took me bl**dy ages to
        work that one out!
      Chris Jackson; for pointing out that this code writes 6 bytes per word
        in some instances. Well... Erm... I took a 'fixed' data file and
        Diff'd it with the same file after being loaded and resaved by
        VoteEdit. The only two differences were the header (very first line)
        and the bit VoteFile tags onto the end of the data... The rest was
        identical...?
      John Stonier; who was brave to run my code, given the results some of
        my past experiences have created ("Address exception at %0" and
        "!!CAM map corrupted!!" being my favourite two. Well, serves me right.
        I was only trying to branch to a random location in memory. :-)



Fixes:
~~~~~~
   * Obey files updated to use the name "VoteFile", not look for "Code".
   * End-of-examine result bits added.
   * That big 'postmortem requested' crap replaced by a half-understandable
     message.
   * 'Easter egg' added. :-)



But whhhyyyy!?!?!?
~~~~~~~~~~~~~~~~~~
   Rumours are several people are making CastAWote compatible products, and
   so this little utility will offer some tiny little bit of protection to
   developers that don't stick to the specifications.



So where are the specifications?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   The official 3.00 beta-testers have a rough copy. I'll write the real
   copy someday...


   ___
  /__/
 /  \ichard.  7th January 1996
