
                  BigNoseBird.Com's Survey Script
               Installation and Operation Instructions

This script as with all others at BigNoseBird.Com is free for you
to use in anyway you see fit, for either commercial or noncommercial 
use. A link back is always nice, but that's up to you. 

This little system allows you to construct survey forms based on
RADIO BUTTONS. You may ONLY use RADIO BUTTONS, and NOT CHECKBOXES!
The system as configured allows for up to 20 possible answers per
questions, with NO LIMIT on the number of questions.

After voting, a person will be shown the current tally of the 
survey. I tested the performance on a pentium-133 running Linux
in the old basement here, and it processed a 10 question survey
with 25,000 responses in under 20 seconds. Actual mileage will
vary based on your individual driving habits.

The system uses a simple method of preventing multiple votes by
the same person close together. If you turn ENFORCEMENT on, then
the user will be checked against the log based on the date, time
and their IP address. Your worst case scenario is that somebody
could vote about once per hour. The purpose of this is to prevent
"button pushing"! 

                      -------------------------
  Quirk! If you have 5 items (0-4) and only have responses for
  0 and 2, then 3 and four will not show up until they get responses!
                      -------------------------

Before starting on the installation, here are a list of files that
should be in this distribution. Next to each file, is how to transfer
the file from your PC to a Unix server- ASCII or BINARY, where to
put them, and the basic function of the file.

To Prepare your site, start my creating a directory 

                     simages

under your main web or html directory. This is just in case you
have any gif files named for colors, you will not overwrite them.
The program is preconfigured to look for them there!


NAME     HOW TO FTP  WHERE       PURPOSE
---------------------------------------------------------------------------
survey.cgi ASCII   cgi-bin       the actual script
---------------------------------------------------------------------------
vote.html  ASCII   main html dir example data input form
view.html  ASCII   main html dir example view results only form
---------------------------------------------------------------------------
demo.cnt   ASCII   cgi-bin   counter file
demo.dat   ASCII   cgi-bin   survey data used by result display
demo.log   ASCII   cgi-bin   survey data in database import format
demo.cfg   ASCII   cgi-bin   configuration information for this survey
---------------------------------------------------------------------------
black.gif  BINARY
blue.gif   BINARY
cherry.gif BINARY  htmldir/simages/
green.gif  BINARY            these are small graphics files used
navy.gif   BINARY            for creating bar charts.
pink.gif   BINARY
purple.gif BINARY
red.gif    BINARY
sky.gif    BINARY
teal.gif   BINARY
yellow.gif BINARY
---------------------------------------------------------------------------

To sum it up, place the survey.cgi, and the demo.* files in your
cgi-bin directory. Place the two html files in your main html or
web directory, and the gif image file in the simages directory
under your main html/web directory.

If you typically edit your files after installing them, then you
can upload them first. If you do not have telnet access to your
site, edit the files listed below before uploading.

   survey.cgi 
   ----------
   This is the program script itself. You will need to check that
   the path to your perl language is correct. /usr/local/bin/perl
   or /usr/bin/perl are usually the norm.
   If you choose to place the data files or images elsewhere, you
   will need to change the appropriate variables or names. They are
   all clearly labeled near the top of the script.
   BE SURE TO SET YOUR SITE'S URL!
   *NOTE* This script uses what is called fgrep to handle searches.
   if your system does not have fgrep, then you can use grep. Again,
   make sure the path is correct. Normally both of these programs
   are located in the /bin directory.
   DO NOT turn on ENFORCEMENT until you are done testing! You will 
   have to wait up to 1 hour between tries from the same location.
   PERMISSIONS: You MUST set this file to the equivalent of
   chmod 755. This means that owner has read-write-execute permission
   and group and others have read-execute permission. Using telnet,
   at your unix prompt:  chmod 755 survey.cgi
   FTP users- Please see your FTP instructions for issuing the unix
   chmod command.

   **NOTE: If the script runs, but finds no data, check your path
    to "grep" or "fgrep". fgrep is usually in /bin, but can also 
    be in /usr/bin. **

   demo.cnt demo.dat demo.log
   --------------------------
   These three files make up the data of the demo survey. Place
   them in the cgi-bin directory and change their permissions
   to the equivalent of chmod 666. This means read-write permission
   for owner, group, and others. ALL NEW FILES CREATED BY THE SURVEY
   SYSTEM BY DEFAULT USING THE FORM- WILL AUTOMATICALLY HAVE THE
   PROPER PERMISSIONS!

   So, if you do "filebase="mysurvey" in your form, it will create
   mysurvey.cnt, mysurvey.dat, and mysurvey.log for you. You must
   set up the mysurvey.cfg file.

   demo.cfg
   --------
   This file contains the configuration information about the demo
   survey. It looks like this:

   ITEM1:Reader's Gender:Male:Female:Neuter
   ITEM2:Reader's Age:Under 18:18-35:36+
   ITEM3:How Reader Found Us:Search Engine:Directory:Link:Referral:Accident

   Each "ITEM" refers to a group of related RADIO buttons having the
   SAME name on a form. In order for a response set to show up on the
   result, the "ITEM" as it relates to the name in the form MUST be in
   this file. Note that each field is separated by a ":" colon.
   There must be no blank lines in this file.
   The first field relates to the NAME in the form.
   The second field is the title to appear over that response set.
   The remaining fields are the labels for each response, in order
   from 0,1,2,3,4...  

   **************************************************************
                          VERY IMPORTANT!!!
   As a way to get the best system efficiency, I made the decision not
   to place any extra "if" statements in the program code. Instead, I
   am relying on the pattern matching ability of the "grep/fgrep" filter
   program. This means that you MUST be very careful in naming your 
   fields to avoid confusing the system! Here is an example that would
   confuse the computer:

      ITEM1:         In this example, when the data is selected for M1
        EM1:         it would end up pulling ITEM1 and EM1 as well.
         M1:
 
   The best way around this problem is to keep all of your names the
   same length- in all UPPERCASE! In the description part of the  
   entries, use a mix of upper and lower or all lower case. The example
   I have in the demo.cfg is a good way to do it.
   **************************************************************

   vote.html
   ---------
   This is an example survey form for the demo survey. Please note
   that there are two MANDATORY HIDDEN fields in it. You must supply
   an action, either VOTE or VIEW and a filebase. The filebase is 
   what the system uses to name the various data files. Do NOT use
   any special characters in this field!

   Please be sure to enter the correct call to the script. On
   my system it is /cgi-bin/survey.cgi 
   This varies from server to server.

         <input type=hidden name=action value="VOTE">
         <input type=hidden name=filebase value="demo">
         Your Gender
          <input type=radio name=ITEM1 value="0">Male
          <input type=radio name=ITEM1 value="1">Female
          <input type=radio name=ITEM1 value="2">Neuter
         Your Age
          <input type=radio name=ITEM2 value="0">Under 18
          <input type=radio name=ITEM2 value="1">18-35
          <input type=radio name=ITEM2 value="2">36+
   
   Notice the relationship between the ITEMs in the form, and the
   ITEMs in the demo.cfg file. By matching the location in the
   demo.cfg against the information in the form, the program is 
   able to correctly tabulate and display the data.

   PLEASE NOTE THAT THE FIRST VALUE FOR EACH RESPONSE ITEM MUST
   BE THE NUMERAL 0 (ZERO). After that, use 1,2,3,4,5 and so on
   in order.

   view.html
   ---------
   This is a simple way to call the script so that results can
   be shown without voting. Again, you MUST supply the filebase
   and  and an action of VIEW.

  <input type=hidden name=action value="VIEW">
  <input type=hidden name=filebase value="demo">
  
  Please be sure to enter the correct call to the script. On
  my system it is /cgi-bin/survey.cgi 
  This varies from server to server.


