                   __      __   _       ______    _ _ _
                   \ \    / /  | |     |  ____|  | (_) |
                    \ \  / /__ | |_ ___| |__   __| |_| |_
                     \ \/ / _ \| __/ _ \  __| / _` | | __|
                      \  / (_) | ||  __/ |___| (_| | | |_
                       \/ \___/ \__\___|______\__,_|_|\__|


                                   VOTEEDIT
                                   vers3.02
                                   --beta--

                        Vote Data Editor For CastAWote


                       1996 Richard Murray (BudgieSoft)


For update notes, jump to end of file.


VoteEdit:

     VoteEdit is a fairly powerful program, but simple to use. Emphasis has 
     been kept on simplicity, and as such, there is no complex or trivial 
     configuration sequence.
     The point behind VoteEdit is to provide a means of editing the votes data
     if some users place 'undesirable' questions. CastAWote itself offers 
     reasonable protection against certain vulgarities, but it is possible to 
     fool CastAWote, and CastAWote doesn't detect slanderous remarks that 
     could get you into trouble.
     Hence this program.

     Above all, it is exceedingly convenient to be able to freely edit 
     CastAWote's data, to correct mispeliingz or even to create your own 
     questions without logging on locally and using CastAWote.

     Please note that this program DOES NOT deal with 'old format' data files.
     It can cope with data files from CastAWote 2.45 to 2.50 and v3.xx.


Features:

     One of the most important features is the heap manager. Now if you delete
     a question, or add a question etc, CastAWote doesn't freak and prevent 
     users from voting on questions they haven't voted on.
     Other features... 
          The SAVE menu option is redundant as saving occurs as soon as you 
          alter something.

          The DELETE icon in the vote data editor now provides an ACCEPT 
  facility, so no more bashing Return to update the data.

          VoteEdit now interfaces in a basic form with CastAWote's WimpMessage
          broadcast. It doesn't make it's own broadcast.

          Now supports new format HasVoted files (only). Quicker redraws.

     VoteEdit is getting ready to provide a full-featured interface to other
     popular databases/BBS systems to allow you to export your votes database
     to popular databases such as ProBase, FoxPro (coming), dBase 4 (coming),
     my TurboSnail (coming) and CSV/TSV (coming) for many other databases
     and spreadsheets and desktop publishers. Also the ability to export the
     results data for various BBS screen scipt formats (coming) or ANSI for
     most BBSs.
     To add to that, you can UUcode (coming) the output file so you can post
     it across fidonet or the Internet easily.

     Finally, VoteEdit offers you quick and simple vote file verification.



Installing:

     Simply put !VoteEdit where ever you like. It will refuse to run until 
     CastAWote has been 'seen' by the filer, but you can always add a 
     Filer_Boot command to the !Run file.

     The reason for needing CastAWote is that a system variable is accessed, 
     <CastAWoteA$Dir>, and this is found in CastAWote's !Boot file.....

     Note: VoteEdit searches for "<CastAWoteA$Dir>", so it WILL NOT 
           automatically recognise versions of CastAWote prior to 3.00 - you
           can bodge this if you really need to by inserting:
             Set CastAWoteA$Dir <Obey$Dir>
           in your !CastAWote.!Run file.



Using:

     Double click on the !VoteEdit icon. Icons are provided in low-res and
     high-res.

     It is worth pointing out that no Interactive help is present. This will
     be added later.

     A window will open, giving identification on the program. This is my
     form of 'banner'. :-) Click on it and it'll go away.

     If you click ADJUST on the icon bar icon, you will see the status window.
     This tells you useful/useless information like the number of votes, if
     the data has been modified etc... It even tells you when you ran the
     program, in case you ran !VoteEdit and went into a three year coma at
     your keyboard - and without a powercut [unlikely :-)].

     Clicking SELECT on the iconbar icon will bring up the List Votes window.
     This lists the first ten votes by question, and allows you to edit them.
     Click on the SCROLL UP and SCROLL DOWN icons to move up/down the list.
     If there are less than ten votes in the database, nothing will happen.
     If you click SELECT on the question, the caret will appear. Here you may
     directly edit the question text.

     If you click ADJUST on the question number, you will tag the vote. More
     on that later. Clicking SELECT on the vote number will open the Vote
     Editor window for that vote.

     The List Votes menu is also interesting as it is one of the main features
     of VoteEdit.
          Edit           This will allow you to edit the vote that MENU was
                         clicked on, or vote 1 if MENU was clicked elsewhere.
          -----------
          Cut            You only get these options if MENU was clicked over
          -----------    a vote question...
          Copy           And these ones too!
          Paste
          Insert
          Delete         See later for details of these operations.
          -----------
          Append         See later for details of this operation.
          Verify data    See later for details of this operation.
          -----------
          ExprtResult    Does nothing. Not coded yet.
          Export data    See later for details of this operation.
          Save votes     Save the current data back to CastAWote.
          Load/reload    Load/reload the data from CastAWote.
          Ensure         Does nothing (I think).



Vote Editor:

     This opens a window with a number of icons in it. The top left of the
     window displays the vote number, and how many votes there are.
     The top right allows you to flick through the votes. These icons blank
     out when approriate, ie: the NEXT will blank if it is the last vote.
     The greater part of the screen is dominated by the data for the current
     vote.

     New to this window are the "Additional Information" icons, and the "votes
     count" icons, the latter being down the right-hand side of the window.

     Now, at last, you can totally edit a vote in one window.

     Finally, at the bottom, are three icons...
          REMOVE USER VOTED-ON FLAG will scan through CastAWotes data and 
               re-enable the vote for users that have already voted on.
          CLEAR will clear the current data. Clicking ADJUST will 'unclear' 
               the data, but only for the same vote. Use the cut'n'paste
               method for cross-copying information.
          ACCEPT will accept and save the current vote.

     In the Created By field, you type a name. This name will be associated 
     with the person that created this vote. If you do not type a name, 
     "Anonymous (via VoteEdit v3.00)" will be used as default.
     You type/edit the question in the Question field. There must be a 
     question.

     If you wish for additional information to be shown for this question,
     type it into the next three fields.

     To the right of the additional information fields is the total votes
     field. This cannot be altered. If it does not match the seperate votes
     count, click accept and it will be re-calculated.

     Then, you type/edit the options in the next six fields. There must be at
     least two options. If you leave any of options 3, 4, 5 or 6 blank, all
     subsequent options will be blank. When you press [RETURN] or [] you will
     be sent to the "voted" field. Alter this as you need, then [RETURN] or
     [] to continue...

     If you see "{/}" appear, you should delete it as it is the old CastAWote 
     null marker, and is no longer used (subsequently CastAWote will display 
     this to the user as a valid option)...

     Menu options are Delete, Clear, Cut, Copy, Paste, Append, Goto. These are
     described below.



Save:

     This option is now rather superfluous because VoteEdit saves your change 
     as soon as you make them. But for the paranoid - you can click this just
     to be sure...



Cut, copy, paste etc...:

     CUT       - will delete the current vote, after storing it in the
                 clipboard. Previous clipboard data is overwritten.
     COPY      - will store the current vote in the clipboard. This is useful
                 for 'cloning' votes. It overwrites previous clipboard data.
     PASTE     - will write the contents of the clipboard into the current
                 vote, overwriting it.
     INSERT    - Inserts a blank vote before the current vote.
     DELETE    - Deletes the current vote.
     APPEND    - Adds a blank vote to the end of the votes data list.
     GOTO      - This brings up a sub-menu with three items. The first item is
                 to first vote. The second item is the last vote. The third
                 item, initially '1', is writable. Enter/select your vote and
                 you will jump straight to it.


Verify:
     This uses a modified version of the "VoteFile" programme. The checks 
     performed are identical to VoteFile, with a few major differences:
        * There is NO screen output. AT ALL. Therefore the code can verify
          100 votes in a second... WOW!
        * Two system variables are created if needed:
             Vote$File$Errors       - The number of errors found.
             Vote$File$ErrorString  - Serious error codes.
          In your code, you should do:
             Set Vote$File$Errors 0
             Set Vote$File$ErrorString n/a
          This makes your life easier. You now need to just check if the
          contents have changed, not if the variables exist in the first
          place.

          Vote$File$Errors is simple. It is have many errors were found, in
          all, or "0" if none.

          Vote$File$ErrorString is "n/a" if no serious errors occured, or
          "FTS" if the Data file is too small, or "ERS" if there was an error
          whilst reading a string, or "ERW" if there was an error whilst
          reading a word.
          The former indicates a possibility of a blank Data file. The later
          two indicate possible file corruption.
          There is no code returned if the Data file doesn't exist. VoteEdit
          loads in the code, so it assumes the file is present. :-)

     In typical VoteFile tradition, it builds up a replacement Data file
     called "Fix_Data". You must copy this over "Data" yourself. You cannot
     pass any parameters to "ve_vf". It is locked into 'fix' mode, and with
     no screen output - 'fast' mode has been removed.

     Using this option in VoteEdit will run the verification code. It will
     lock up your computer for, say, a second for 100 votes. Then you will
     be informed of the results. Once you have read the message, the Fix_Data
     file will be copied over the Data file, and the Data will be reloaded.

     Note, errors are flagged for:
        Creator is anonymous
        Weird additional_info strings
     However nothing is changed, you'll have to do this manually - if you can
     be bothered. :-)



Export results:

     This has not been coded yet.



Export data:

     See 'export selection' for details on selecting what you would like to
     output...

     A window will open. Down the left-hand side is a list of filetypes.
     Click which you would like. At the bottom is a toggle (disabled) that
     switches automatic UUcoding of the output on and off. The top-right
     behaves like a regular "save as" window.

     ProBase       - Output for the PD database application "ProBase".
     FoxPro        - Output for MicroSoft FoxPro and many other PC databases
                     (such as Zephyr).
     TurboSnail #  - Output for my own database program.
     CSV           - Output in CSV format for many databases, spreadsheets
                     and DTP programs.
     TSV           - As CSV, but uses the TAB character as a seperator.
     ASCII text #  - Output in ASCII format. Each data element on a new line.
                     Two lines between votes.
     BudgieSoft... - As for the 'Backup file' option.
     Old CAV file #- Outputs the split-file data as used by early versions of
                     CastAWote.

     NOTE: Currently, #'d types are not implemented. The others are.

     Ignore the "DIF" option. DIF is some PCish format (Data Interchange
     Format) that I thought about adding, but decided it wouldn't be worth it.
     I would, however, like to be able to include S-Base output. Does anybody
     have format details?



Export selection:

     All Votes      is an option to save the entire votes database as a
                    results file. You can pick from ANSI, ArcBBS, ASCII or
                    CSV.

     Vote #         is to save just a single vote result. If you clicked MENU
                    over a vote, then you can use this to output ANSI, ArcBBS,
                    ASCII or CSV data for that one vote. If you clicked MENU
                    elsewhere, this option will say 'No Vote' and be greyed-
                    out. Not yet implemented.

     Tagged         is to save selected (tagged) votes only. This is a
                    powerful, and useful, feature that took me ages to perfect
                    [touch wood :-)]. See below for details of tagging. You
                    can export in ANSI, ArcBBS and ASCII. Not yet implemented.



Tagging votes:

     You tag a vote by clicking ADJUST on the vote number icon. A * will
     appear by the number. Clicking ADJUST again will remove the *, and untag
     that vote.



Backup:

     Being the very first BudgieSoft application to use the &16F generic
     filetype mechanism - this will store ALL the data in a special format
     file. The file can be sent around the various computer networks as no
     control codes are used. It is also human readable.

     To reload, simply drag to VoteEdit...



Old Format CastAWote files:

     These are not supported, and should have been converted by an update of
     CastAWote. If you cannot convert the data - you'll have to recreate it
     with VoteEdit.

     Earlier releases of CastAWote 3 come supplied with a utility called
     "OldToNew" that should help.



Using an older VoteEdit with v3.00 data files:

     Here are the important points:
       * Tagging a vote will wipe the results for options seven and eight.
       * Verify will remove options seven and eight and 'clean up' some other
         important points.
       * Accepting a vote will blank options seven and eight.
       * When viewing votes, options seven and eight are ignored.
       * Older VoteEdits will fail upon loading a datafile with 0 votes. You'll
         get a "Division by zero" error.

     Therefore - use the right version!  You should have few problems using
     older files with this version of CastAWote.



Birds:

     Support the RSPB...



CastAWote's WimpMessage broadcast:

     CastAWote sends a WimpMessage broadcast to all tasks as soon as a user
     creates a new vote or votes on an existing vote. The purpose behind this
     is to keep multiple CastAWote's totally up to date. If is not recommended
     that VoteEdit and CastAWote be run together, but in case it is... This
     will allow updates automatically.
     VoteEdit will respond to WimpMessage &16F (old message number) or the
     newer WimpMessage &16F00 (new number, changed to equal BudgieSoft's self
     allocated SYS block (SWI chunk)).

     Full details for the BudgieSoft Wimp_Message protocol available from
     BudgieSoft. Details of CastAWote specific messages are printed in the
     CastAWote user guide.

     CastAWote 3 will refuse to load if VoteEdit is loaded, in order to
     minimise possible problems.



Default_mode:
     
     Load up !VoteEdit, and hold down ALT. It will skip the loading in
     datafiles and create a 'default' file with one blank vote. THIS WILL BE
     SAVED AS THE REGULAR VOTES FILE AND WILL OVERWRITE WHATEVER IS THERE, SO
     USE THIS OPTION WITH CARE.

     :-)



And finally...

     I hope you enjoy using CastAWote, and that it performs well and is a
     useful addition to your system.

     I'm constantly revising and changing CastAWote to make it better, nicer,
     faster, less memory/file load and so forth. That's why it is important
     that I keep up with what's going on. :-)


     If you would like to program BBS bits for/with BudgieSoft... Contact me.



                                A few HELLOs:

          To John Stonier and Steve Pursey for testing stuff. Thanks.
            To Robin Abecasis, Keith Hall, DaviD Dade, Dave Coleman
               and Chris Jackson for also testing this software.
      To Chris Jackson for educating me on the in's and out's of Fidonet.
              To Hugo for 1.63 and the impressive looking 1.64.
                    To Justin Fletcher, the mega-patcher.
                    To all the Acorn SysOps reading this.
            To Bridget Fonda and Claire Danes for interesting TV
                   ("The Assassin" & "My so-called Life")
              MeatLoaf, Dire Straits, Genesis, Beverley Craven,
           The Eagle (formerly Country Sound), Weird Al Yankovic,
           and Neil Diamond for interesting background noise. You
            should have seen me grooving with Mark Knopfler! :-)
                   To the guy that invented tea. Thanks.


   Finally, thank you to all those Acorn SysOps that have used my software,
       believed in me and prodded me when things didn't quite go right.
 
             Your support has meant a lot to me. So, thank you.

                                                                           

                                  Hello mom!



UPDATE NOTES:
  Hacked into VoteModule form. I have a suspicion that the vote heap thing
  that reallocates entries after a deleted vote is buggered. However I can't
  see exactly how.

  That's where YOU come in.

  Tell me what is wrong, and I can fix it. 

  It's in your best interests. Get this sorted and CastAWote will have a
  nice fast editor. You have the sources to play with. It might just be
  a misallocation somewhere? One vote count too many?

  The interesting code is from line 1492. It should make sense <vbg>.

  Oh, and it goes without saying that you should keep backups of your
  data. Misallocated heaps can cause havoc. ;^)

  PS: Verify should now work.
