
                        BNBSURVEY 3.0 
       A survey script for Unix and Windows Servers

Original Release Date: January 25, 2000

Modified on March 7, 2000 to correct a misplaced Content-type
which prevented Location: (jump_to) from working.

Modified on March 20, 200 to correct a misnamed file handle
on the CLOSE(LOCK_FILE) - was close($lockfile)


#-----------------------------------------------------------#
 
  BNBSURVEY Script, (C)2000 Bignosebird.com 
  Use of this script means that you accept the disclaimer and
  agree to the terms of use and copyright notice.
 
  This script is provided without support. Please read the
  README.TXT file, as well as following the troubleshooting
  links and information at http://bignosebird.com/cgi.shtml
  Our BBS is located at http://bignosebird.com/bbs.shtml
  Please subscribe to our low volume newsletter from any of
  our pages. This is the fastest way to find out about 
  security issues and enhancements. Suggestions are always
  welcome!
  
#--------DISCLAIMER-AND-COPYRIGHT-INFORMATION---------------#

 ANY SOFTWARE PROVIDED BY BIGNOSEBIRD.COM, INC. IS ``AS IS'' 
 AND ANY # EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
 LIMITED TO, THE # IMPLIED WARRANTIES OF MERCHANTABILITY AND 
 FITNESS FOR A PARTICULAR # PURPOSE ARE DISCLAIMED. IN NO EVENT 
 SHALL BIGNOSEBIRD.COM, INC. OR  ITS CONTRIBUTORS BE LIABLE FOR 
 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 
 OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 
 OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF 
 THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 
 OF SUCH DAMAGE.  THIS SCRIPT IS PROVIDED WITHOUT SUPPORT 

 THIS SCRIPT IS FREEWARE AND CAN BE USED FOR BOTH COMMERCIAL 
 AND NON-COMMERCIAL USE. REPUBLICATION OF THE SCRIPT REQUIRES 
 OUR PERMISSION.
 webmaster@bignosebird.com

#-----------------------------------------------------------#

                    DISTRIBUTION CONTENTS

README.TXT:    This file with instructions, etc.
survey.cgi:    The actual survey script
survey.srv:    A sample configuration file
survey.log:    An empty log file
survey.html:   A sample survey form
GIF files:     Nice colored GIF files to make graphs with

             *** INSTALLATION INSTRUCTIONS ***

Under your main HTML document directory, make a directory
named "survey". Copy the survey.html page and GIF files into 
the "survey" directory.

Under your cgi-bin (or equivalent) directory, make a directory
called "survey". Set the permissions so that your web server
can write to it. In addition, you can create a directory elsewhere
that the web server can write to and specify that later on
in the DATA_PATH variable.

Copy the survey.cgi to the survey directory in your cgi directory.
Copy the survey.srv and survey.log there as well. Set the permissions
on the survey.cgi so that owner can read-write-execute, and group
and others can read-execute (chmod 775). The permissions on the
survey.srv and survey.log need to be set so the user the web 
server runs as can write to them. If you are not sure about this
part, give permission for all to read and write these two files.
(chmod 666)


         *** SCRIPT CONFIGURATION INSTRUCTIONS ***

The script is somewhat simple to configure, but it does 
require some attention to detail.

STEP 1: THE INPUT FORM

You can have as many surveys as you want. You indicate
the name of the survey with the hidden form field named
"survey_name".  You then just name your survey.srv file
to whatever.srv for each survey.

   <INPUT TYPE="RADIO" NAME="ITEM_1" VALUE="ITEM_1|Male" >Male
   <INPUT TYPE="RADIO" NAME="ITEM_1" VALUE="ITEM_1|Female" >Female
   <INPUT TYPE="RADIO" NAME="ITEM_1" VALUE="ITEM_1|No Answer" checked>No Answer

In this example, you will see that I provide a "No Answer" 
choice that is preselected. No Answer is important because
showing nonresponse helps validate your survey.

The idea is this. Each question has a name, such as ITEM_1.
Each possible value is named as ITEM_NAME|RESPONSE. It is
critical that you use this EXACT format including the pipe (|)
character. This will make more sense when we look at the 
survey.srv file. You can have spaces in the response values
after the pipe (|) character, but NOT before the pipe.

The form should call the script in the following manner using
the POST method:

   <FORM ACTION="/cgi-bin/survey/survey.cgi" METHOD="POST">

STEP 2: THE .SRV SURVEY CONFIGURATION FILE

The next step is to create a file such as the survey.srv
contained in this distribution. In making this file:

 1.) Make sure there are no blank lines.
 2.) Use a | pipe character between The ITEM and RESPONSE
     CHOICE.
 3.) A : colon between the RESPONSE CHOICE and the COUNTER.
 4.) A : colon between the COUNTER and the QUESTION TITLE.
 5.) The QUESTION TITLE must appear on each QUESTION LINE.
 6.) A : colon at the end of the line.

ITEM_1|Male:0:Respondent's Sex:
ITEM_1|Female:0:Respondent's Sex:
ITEM_1|No Answer:0:Respondent's Sex:
ITEM_2|First Time Visitor:0:Visitor Status:
ITEM_2|Been Here Before:0:Visitor Status:
ITEM_2|No Answer:0:Visitor Status:

In the example above, ITEM_1, titled Respondent's Sex has three
possible answers, each with a starting count of zero.

STEP 3: SCRIPT CONFIGURATION

You will need to edit the following information near the
top of the script. To edit the results display page, find
the COSMETIC section near the end of the script.

 $DATA_PATH is the FULL system path to the directory where
 your survey data files are stored. Your web server must have
 permission to write to and create files in this directory

  $DATA_PATH="/home/httpd/cgi-bin/survey";

 The $DOMAIN must be your site's domain name. 

  $DOMAIN="www.yourdomain.com";

 $GRAPHICSDIR is the directory under your main html directory
 containing the colored gif files.

  $GRAPHICSDIR="survey";
 
 To prevent people from voting too often, set $USE_COOKIES=1
 HOURS is the NUMBER OF HOURS before the voter can vote
 again. 1 Day=24, 1 Week=168, 1 Month=720 give or take....
 To disable cookies, let $USE_COOKIES=0

 WARNING: DO NOT ENABLE COOKIES UNTIL YOU ARE SURE EVERYTHING
 IS WORKING PERFECTLY, OR YOUR DEBUGGING CAN BE SERIOUSLY
 SLOWED DOWN WHILE YOU WAIT FOR THE COOKIE TO EXPIRE. ;-) 

  $USE_COOKIES=0;
  $HOURS=1;  # one hour delay between votes

 Set $USE_LOGGING to 1 to turn on log file capture.
 Log format is an ASCII tab delimited file consisting of:
 Visitor's IP address, date, time, responses, e-mail, comments
 Can be easily imported into spreadsheets and databases

  $USE_LOGGING=0;

 IF $SHOW_RESULTS=0 (do not display after voting), be sure
 to set $JUMP_URL to the page the voter should be sent to.
 By default, it sends the voter back to the page they came from.
 When used with SHOW_RESULTS=1, this is the link they can click
 on after viewing the voting.

  $SHOW_RESULTS=1;
  $JUMP_URL="$ENV{'HTTP_REFERER'}";

 These are the cosmetic settings in case you do not like my
 terrible taste in colors! The actual result page layout can
 be found near the bottom of the script.

  $TABLECOLOR="#FFFFFF";
  $HEADINGCOLOR="#000066";
  $HEADINGFONT="arial,helvetica";
  $BORDERCOLOR="#660000";
  $FONT="arial,helvetica";
  $FONTCOLOR="#000000";

               *** CALLING THE SCRIPT FOR VIEW ONLY ***

You can give your readers the option of viewing the current results
of the survey by providing a link such as:

   http://domain.com/cgi-bin/survey/survey.cgi?survey_name=number1

Give the full URL to the script, and after the question mark, 
change the number1 to be the name of your survey.


