#!/usr/bin/perl

# Name: db_manager.cgi
# Version: 5.0
# Last Modified: 01-31-97
#
# 02-03-98 (RVB): Change dir path where perl is from #!/usr/local/bin/perl to #!/usr/bin/perl
# 05-04-98 (WHB): changed title of displayed HTML page to use $db_title variable
#   + added code to require csee-lib.pl
# 05-08-98 (RVB): Have two copies of the same elsif (except for the ".x",)
#   in  the Perform Management Functions code area.
#   This is do we can use an image as a button as well as the browser made button
# 05-12-98 (RVB): Change so the words "Database Manager" are not in every title
#   of html pages. Around line 526
#
# Copyright Information: This application was written by Selena Sol
# (selena@eff.org, http://www.eff.org/~erict) and Gunther Birznieks
# (birzniek@hlsun.redcross.org) having been inspired by
# countless other Perl authors.  Feel free to copy, cite, reference,
# sample, borrow, resell or plagiarize the contents.  However, if you
# don't mind, please let me know where it goes so that I can at least
# watch and take part in the development of the memes. Information wants
# to be free, support public domain freware.  Donations are appreciated
# and will be spent on further upgrades and other public domain scripts.

#######################################################################
#                  Flush the Perl Buffer.                             #
#######################################################################

                # The script begins by telling the Perl interpreter that
                # it should continuously flush its buffer so that text
                # from this script is sent directly to the Web Browser.
                # We do this to streamline debugging and make sure that
                # the script operates with the flow we want it to.

$| = 1;

#######################################################################
#                 Send out the http Header                            #
#######################################################################

		# Next, the script sends out the http header so that we
		# can debug more easily and so that the browser won't time
		# the script out if it take too long to process.

print "Content-type: text/html\n\n";

#######################################################################
#               Read and Parse Form Data                              #
#######################################################################

		# Then, the script loads some supporting files
		# using the subroutine, require_supporting_libraries
		# documented at the end of this script.  cgi-lib.pl is
		# used to read and parse form data. auth-lib.pl is used to
		# authenticate users of the database management system.
		# db-lib.pl is used to search through the database for
		# matches to the users search criteria.

&require_supporting_libraries (__FILE__, __LINE__,
                              "./Library/cgi-lib.pl",
			                  "./Library/auth-lib.pl",
                              "./Library/db-lib.pl",
                              "../cgi-bin/csee-lib.pl"
                              );

        # Now that cgi-lib.pl has been loaded, we can take
		# advantage of its subroutines.  In particular, we will use
		# the ReadParse to read the incoming form data. However,
		# the subroutine is sent "form_data" as a parameter so
		# that the associative array of form keys/values comes
		# back with a descriptive name rather than just %in.
		#
		# In a nutshell, if we have two input fields on our HTML
		# form such as the follwoing:
		#
		# <INPUT TYPE = "hidden" NAME = "id_number" VALUE = "1">
        # <INPUT TYPE = "hidden" NAME = "setup_file" VALUE = "data.setup">
		#
		# Then the ReadParse routine will create an associative
		# array like:
		#
		# %form_data = ("id_number", "1",
		#		"setup_file", "data.setup");
		#
		# Throught this script, we will be able to access those
		# dynamically assigned values when we need them as we
		# would for an associtive array which was hard coded into
		# the setup file.  We access elemetns in an associative
		# array using key notation.  For example, to assign the
		# value of "setup_file" to $sf, we'll use:
		#
		# $sf = $form_data{'setup_file'}.
		#
		# In other words, $sf = "data.setup";

&ReadParse(*form_data);

#######################################################################
#                        Load Supporting Files                        #
#######################################################################

                # Once it has read the incoming form data, the script
                # will be able to determine which setup file it should
                # use to process the incoming form data.
                #
                # Perhaps a bit of explanation is in order.
                #
                # Whenever you run this application, you MUST pass to it
                # the name of the setup file which it will use to process
                # the management request.
                #
                # This variable will provide the name of the file which
                # this script will use to define all of the customizable
                # aspects of its operation.  For example, the setup file
                # defines what is contained in the database and which
                # fields should be displayed to the user.
                #
                # The reason for this is that this one script can handle
                # an infinite amount of databases.
                #
                # Each database has a corresponding setup file which defines
                # how the script performs.  The logic (and programming)
                # remains the same for all db's.  All that changes are
                # the variables and subroutines in the setup files.  This
                # makes it very easy for you to quickly generate diverse
                # databases with the one backend.
                #
                # The script first takes the value of "setup_file"
                # coming in from the form (which cgi-lib.pl has already
                # parsed into the %form_data associative array) and
                # assigns it to the variable $setup_file.
                #
                # So how do you get this information to the script?
                #
                # There are two ways to do that.  Firstly, you can encode
                # the information into the URL if you are executing this
                # script directly from a hyperlink.
                #
                # For example, you might use the following hyperlink to
                # direct the script to access address_book.setup:
                #
                # http://www.you.com/cgi/db_manager.cgi?setup_file=address_book.setup
                #
                # You can also send this information as a hidden field in
                # an HTML form using something like the following.
                #
                # <INPUT TYPE = "hidden" NAME = "setup_file"
                #        VALUE = "[NAME OF SETUP FILE]">
                #
                # For example, the following code would define a setup
                # file called address_book.setup:
                #
                # <INPUT TYPE = "hidden" NAME = "setup_file"
                #        VALUE = "address_book.setup">
                #
                # You might also create a select box so that the user can
                # choose from a number of databases dynamically:
                #
                # <SELECT NAME = "setup_file">
                # <OPTION VALUE = "address_book.setup">Address Book
                # <OPTION VALUE = "customer_list.setup">Customers
                # </SELECT>
                #
		# All these examples assume you placed the setup files in
		# the provided subdirectory called Setup_files.
		#
                # The script uses the subroutine require_supporting_libraries
                # documented later in this script to actually load the
                # setup file and all of its configuration options.

$setup_file = $form_data{'setup_file'};

&require_supporting_libraries (__FILE__, __LINE__,
                               "./Setup_files/$setup_file");

#######################################################################
#                       Authenticate User                             #
#######################################################################

		# Next the script must make sure that if the admin has
		# instructed it to authenticate all users through the
		# setup file variable $should_i_authenticate, that it
		# provides a level of authentication.  Authentication is
		# handled by the authentication subroutine which is
		# documented later in this script.

if ($should_i_authenticate eq "yes")
  {
  &authentication;
  }

#######################################################################
#                      Perform Management Functions 		      #
#######################################################################

		# After the user has been authenticated (if necessary), it
		# is time for the script to perform any or all of the
		# management functions.
		#
		# There are 5 general functions that this script must
		# provide.  The script must be able to 1) add a new item
		# to the database, 2) modify an item in the database,
		# 3) delete an item in the database, 4) provide the user
		# with a view of the database and finally 5) present
		# the user with a frontpage to give the user the previous
		# four options.
		#
		# These five general functions are broken down into
		# several other steps each.  For example, the general step
		# of modifying an item in the database can be broken down
		# into three sub-steps.  1) The user must choose to
		# "Modify an Item" from a submit button on the frontpage
		# 2) they must be taken to a screen on which they can
		# enter search criteria so that the script can dynamically
		# generate a list of matches from which they can then
		# choose a specific item to modify and 3) they user must
		# be able to choose an item from that list, describe the
		# changes she wants made and then submit the changes to
		# the database.
		#
		# When all is said and done, there are 11 general and
		# sub-functions that make up the main body of logic of
		# this application.  We will go over each as they appear
		# in the code below.
		#
                # The logic is broken down into a series of "if" tests.
                #
                # Specifically, the script checks the values of incoming
                # administrative form variables (mainly supplied from
                # the SUBMIT buttons on dynamically generated HTML forms)
                # and will perform its operations depending on whether
                # those administrative variables have values associated
                # with them or not.
                #
                # The basic format for such an "if" test follows the
                # syntax:
                #
                # if (the value of some submit button ne "")
                #   {
                #   process that type of request;
                #   exit;
                #   }
                #
                # For example, consider the first case in which the
                # customer has clicked on the "Add an Item" submit
                # button denoted with the NAME value of
		# "add_item_button".
		#
		# if ($form_data{'add_item_button'} ne "")
		#   {
		#   &generic_header("Add an Item to the Database Form");
		#   &generic_form_header;
		#   &add_form_header;
		#   &add_modify_data_entry_form;
		#   &add_form_footer;
		#   &generic_form_footer;
		#   exit;
		#   }
                #
                # Because the submit button will have some value
                # like "Add this new item", when the script reaches
                # this statement block, it will answer true to the test.
                #
                # Since the customer can only click on one submit button
                # at a time, we can be assured that only one operation
                # will answer true.
                #
                # The beauty of using the not equal (ne) test is that
                # regardless of what the submit button actually says
                # (it might say "Add a weiner dog to the chopping block")
                # the if test will still be satisfied if they have clicked
                # the button, since whatever the VALUE is, it will
                # certainly not be equal to "nothing". Of course, this
                # assumes that you do not rename the NAME argument of the
                # submit buttons.  If you do so, you must harmonize the
                # variable you use on the input forms, with the variables
                # used here to test.
                #
                # Similarly, if you wish to have graphical submit buttons
                # instead of the ugly default buttons supplied by the
                # browser, you will have to modify the if tests so that
                # they follow the standard image map test:
                #
                # if ($form_data{'some_button.x'} ne "")
                #  {
                #  do something
                #  }
                #
                # where the HTML code looks like the following:
                #
                # <INPUT TYPE = "image" NAME = "some_button"
                #        SRC = "Images/button.gif" BORDER = "0">
                #
                # Thus, if the button actually has an X-dimension value,
                # it means that the button had been clicked.
                #
                # Finally, note that every if test is concluded with an
                # exit statement.  This is because once the script is done
                # executing the routine specified in the submit button, it
                # is done with its work and should exit immediately.
                #
                # Get used to the idea that this script is "self-referencing".
                # The application itself contains many mini-routines
                # which all refer back to the routine community.  Every
                # instance of the script need only execute maybe 1/11th of
                # the routines in the whole file, but in the lifetime of
                # the application, most, if not all, routines are
                # executed.
                #
                # Okay, so now let's look at each of the routines which
                # this applicaiton must execute.
		#
		# 1. If the user clicks the "add an item" button on the
		# frontpage, they must be presented with an HTML form with
		# input fields for each field in the database which they
		# have access to define.  The user can then fill in the
		# input fields and submit the info to be added to the
		# database.
		#
		# The generation of this add form is handled by
		# several subroutines which are all defined in the setup
		# file.  generic_header will print out the basic HTML
		# header with the passed parameter placed between the
		# <TITLE> and </TITLE> tags.  generic_form_header will
		# print out the basic <FORM> tag as well as the important
		# hidden state fields"setup_file" and "session_file" which
		# must appear on ever screen.  add_form_header displays
		# the header of the add form and
		# add_modify_data_entry_form displays the actual input
		# fields for the form.  add_form_footer and
		# generic_form_footer display the page footer information.
		#
		# 2. Once the user submits the information that they want
		# to add to the database by clicking the button NAMED
		# "submit_addition", the script must be prepared to
		# actually modify the database with the new information.
		#
		# This is handled in the next if test.  The subroutine
		# submit_addition which is the meet of this function is
		# discussed later in this script.
		#
		# 3. On the other hand, the user might be asking to modify
		# an item by clicking on the frontpage button NAMED
		# "modify_item_button".  If this is the case, the user
		# must be presented a form upon which she can enter search
		# criteria so that the database can bring back a list of
		# database rows which match her search criteria.  The user
		# can then choose one of them and modify it.  We need this
		# search filter because in a large database, it would be
		# hard to select which row you wanted to modify without
		# dome level of filtering.  The search form is actually
		# generated with the modify_search_form subroutine
		# discussed further down in this script.
		#
		# 4. Once the user fills out the search criteria on the
		# form generated by the routine discussed above, and
		# clicked on the button NAMED
		# "search_and_display_for_modification_button" the
		# script must search through the database and come up with
		# a list of hits.  The user then can select one of the
		# rows to modify and then type in any new information she
		# wants.
		#
		# This requires two things.  1) The script must generate a
		# list of hits with a radio button for selection of each
		# row (only one row may be modified at one time) and 2)
		# the script must provide a form similar to the add an
		# item form so that the user can enter new info (if the
		# user does not enter info into an inpout field, the old
		# data will be kept.)  These chores are handled by
		# the subroutine search_and_display_for_modification which
		# is discussed later in this script.
		#
		# 5. Finally, the user will have selected an item and
		# filled in some new information to modify and clicked on
		# the button NAMED "submit_modification_button".  Now it
		# is time to actually submit this modification to the
		# database.  We'll do this with the subroutine
		# "submit_modification" discussed below.
		#
		# 6. Besides adding an item and modifying an item, the
		# user may wish to delete an item.  If the user clicks the
		# frontpage buttun NAMED "delete_item_button", the script
		# will display a form identical to the one which the user
		# got in step 3 so that the can define some search
		# criteria with which the script can use to generate a
		# dynamic list of database rows which may be deleted.
		#
		# 7. As with modification, the user will enter in some
		# search criteria and click the submit button named
		# "search_and_display_for_deletion_button".  The script
		# will then prepare the list of hits from which the user
		# can delete.  Unlike in the case of modification however,
		# there is no need to also include a form similar to the
		# "add" form, since we will not be modifying the data, we
		# will instead be deleteing the row entirely.
		#
		# 8. Finally, the user will select one of the database
		# rows displayed by routine 7 and click on the
		# "submit_deletion_button" button.  At this point, the
		# script must actually delete the item from the database.
		# This is performed with the submit_deletion subrtoutine
		# discussed later in this script.
		#
		# 9. Next, the user might have asked to simply view the
		# dataabse by clicking the "view_database_button" button
		# on the frontpage.  If this is the case, the user needs
		#to be presented with the familiar search form so that
		# they can enter in search criteria which the script can
		# use to generate a dynamic list of database rows to view.
		#
		# 10. As before, once the user choose some search criteria
		# and hits the submit button, the script must display the
		# list of hits.
		#
		# Finally, the script must display the very frontpage from
		# which the previous 10 functions were derrived.  This
		# frontpage must have 4 buttons, one for add, modify,
		# delete and view functions.
		#
		# Okay, well that was quite a mouthful...I have a
		# suspicion that a picture is worth those thousand
		# words (each step is in parenthesis)...
		#
		#    ----------------Display Frontpage (11)----------
		#    |              |              |                |
		#  User Clicks   User Clicks    User Clicks    User Clicks
		#  Add Button    Modify Button  Delete Button  View Button
		#    |              |              |                |
		#  Display Add   Display (3)    Display (6)    Display (9)
		#  Form (1)      Search Form    Search Form    Search Form
		#    |              |              |                |
		#  User Adds     User Submits   User Submits   User Submits
		#  New Item (2)  Search         Search         Search
		#                   |              |                |
		#                Mod Form (4)   Delete Form    Search Hits
		#                Displayed      Displayed (7)  Displayed
		#                   |              |	           (10)
		#                User Submits   User Submits
		#		         Modification   Deletion (8)
		#		           (5)
		#
		# Below are the 11 routines discussed above.

if ($form_data{'add_item_button'} ne "")
  {
  &generic_header("Add an Item to the Database Form");
  &generic_form_header;
  &add_form_header;
  &add_modify_data_entry_form;
  &add_form_footer;
  &generic_form_footer;
  exit;
  }

elsif ($form_data{'submit_addition'} ne "")
  {
  &submit_addition;
  exit;
  }

elsif ($form_data{'modify_item_button'} ne "")
  {
  &modify_search_form;
  exit;
  }

elsif ($form_data{'search_and_display_for_modification_button'} ne "")
  {
  &search_and_display_for_modification;
  exit;
  }

elsif ($form_data{'submit_modification_button'} ne "")
  {
  &submit_modification;
  exit;
  }

elsif ($form_data{'delete_item_button'} ne "")
  {
  &delete_search_form;
  exit;
  }

elsif ($form_data{'search_and_display_for_deletion_button'} ne "")
  {
  &search_and_display_for_deletion;
  exit;
  }

elsif ($form_data{'submit_deletion_button'} ne "")
  {
  &submit_deletion;
  exit;
  }

#05-08-98 (RVB), Have two copies of the same elsif, except for the ".x",
#this is do we can use an image as a button as well as the browser made button
elsif ($form_data{'view_database_button.x'} ne "")
  {
  &view_database_form;
  exit;
  }
elsif ($form_data{'view_database_button'} ne "")
  {
  &view_database_form;
  exit;
  }

#05-08-98 (RVB), Have two copies of the same elsif, except for the ".x",
#this is do we can use an image as a button as well as the browser made button
elsif ($form_data{'search_and_display_db_button'} ne "")
  {
  &search_and_display_db_for_view;
  exit;
  }
elsif ($form_data{'search_and_display_db_button.x'} ne "")
  {
  &search_and_display_db_for_view;
  exit;
  }

else
  {
  &generic_header("$db_title");
  &generic_form_header;
  &display_frontpage;
  &generic_form_footer;
  exit;
  }

		# Well, that is it!  That is the whole script.  Well, not
		# exaclty, now it is time to explain the subroutines which
		# make the above if tests work.

#######################################################################
#                       Require Supporting Libraries.                 #
#######################################################################

                # require_supporting_libraries is used to read in some of
                # the supporting files that this script will take
                # advantage of.
                #
                # require_supporting_libraries takes a list of arguments
                # beginning with the current filename, the current line
                # number and continuing with the list of files which must
                # be required using the following syntax:
                #
                # &require_supporting_libraries (__FILE__, __LINE__,
                #                               "file1", "file2",
                #                               "file3"...);
                #
                # Note: __FILE__ and __LINE__ are special Perl variables
                # which contain the current filename and line number
                # respectively.  We'll continually use these two variables
                # throughout the rest of this script in order to generate
                # useful error messages.

sub require_supporting_libraries
  {

                # The incoming file and line arguments are split into
                # the local variables $file and $line while the file list
                # is assigned to the local list array @require_files.
                #
                # $require_file which will just be a temporary holder
                # variable for our foreach processing is also defined as a
                # local variable.

  local ($file, $line, @require_files) = @_;
  local ($require_file);

                # Next, the script checks to see if every file in the
                # @require_files list array exists (-e) and is readable by
                # it (-r). If so, the script goes ahead and requires it.

  foreach $require_file (@require_files)
    {
    if (-e "$require_file" && -r "$require_file")
      {
      require "$require_file";
      }

                # If not, the scripts sends back an error message that
                # will help the admin isolate the problem with the script.

    else
      {
      print "Content-type: text/html\n\n";
      print "I am sorry but I was unable to require $require_file at line
            $line in $file.  Would you please make sure that you have the
            path correct and that the permissions are set so that I have
            read access?  Thank you.";
      exit;
      }
    } # End of foreach $require_file (@require_files)
  } # End of sub require_supporting_libraries

#######################################################################
#                       Perform Authentication                        #
#######################################################################

		# Authentication is performed by the set of "auth"
		# libraries in the Library subdirectory.  However, the
		# only one "you" need to worry about is auth-lib.pl.
		# Specifically, you call GetSessionInfo from auth-lib.pl
		# and it worries about all the other supporting libraries
		# on its own.
		#
		# Authentication demands that you define several variables
		# in the setup file as well and &GetSessionInfo will send
		# you back several variables hich you can use within this
		# script (particularly $session_username and
		# $session_group which are used for authentication of
		# modifications.
		#
		# The basic flow of authentication works like this:
		# Initially, when you install the application, you set
		# $auth_add_register and $auth_allow_register to "on" and
		# you set $auth_default_group to "Admin". This will allow
		# you to add yourself as an administrator.  go ahead and
		# run the script from the web and click on the "Register
		# New User Button" and fill out the resulting form.
		#
		# Once you have registered yourself as an admin, you have
		# two options.  Firstly, you can turn off registration so
		# that only you can use this applicaton.  To do so, turn
		# "off" $auth_add_register and $auth_allow_register.  Now
		# you will be able togon, but noone else will be able to
		# do so without your username and encrypted password.
		#
		# You might also decide to allow "users" to have access to
		# the database manager.  These people will be able to add
		# entries and delete and modify each others entries but
		# not touch yours.  To do so, change $auth_default_group
		# to "user".

sub authentication
  {

		# Make sure if the session_file variable is coming in as
		# form data that it is converted to a local variable name.
		# This is important.  We do not want to have to ask the
		# user to logon for every screen they want to see!  Thus,
		# we must make sure that session_file is passed (in a self
		# referential way) between every screen in this
		# application through the use of hidden form variables.

  $session_file = "$form_data{'session_file'}";

		# Now perform the authentication and gather the returned
		# values.

  ($session_file, $session_username, $session_group,$session_first_name,
                  $session_last_name, $session_email) =
                  &GetSessionInfo($session_file, $this_script_url, *form_data);
  }

#######################################################################
#                      Submit an Addition                             #
#######################################################################

		# The function of submit_addition is all in the name.
		# This subroutine takes the user-defined input, formats
		# it into a database row (along with some
		# administrative data like the time it was submitted and
		# by whom it was submitted) and appends it to the
		# database.

sub submit_addition
  {

		# The subroutine begins however, by access the counter
		# file defined in the setup file.  The counter file shuld
		# contain a number on one line.  This number represents a
		# unique database row identification. This is very
		# important because in order for the script to know which
		# row to modify or delete, it needs to be able to identify
		# that row absolutely.
		#
		# The database id number is that identification and it is
		# generated by incrementing the number in the counter file
		# for every item that is added.
		#
		# The process of getting a unique id number is pretty
		# straight forward.
		#
		# First the script uses get_file_lock discussed later in
		# this script to lock the counter file so no other
		# instances of this script can get to the counter file.
		#
		# Then, the script opens the counter file
		# (exiting gracefully with file_open_error discussed later
		# if there is a problem opening the file) and reads the
		# counter file assigning the number to $current_counter .
		#
		# Next, after closing the counter file back up, it
		# increments that number and assigns the incremented value
		# to $new_counter
		#
		# Finally, the script reopens the counter file for writing
		# and deletes the old number, replacing it with the new
		# incremented number, thus incrementing the counter file.

  &get_file_lock("$location_of_lock_file");
  open (COUNTER_FILE, "$location_of_counter_file") ||
	&file_open_error ("$location_of_counter_file", "Submit Addition",
	__FILE__, __LINE__);

  while (<COUNTER_FILE>)
    {
    $current_counter = $_;
    }
  close (COUNTER_FILE);

  $current_counter++;
  $new_counter = $current_counter;

  open (COUNTER_FILE, ">$location_of_counter_file") ||
        &file_open_error ("$location_of_counter_file", "Submit Addition",
        __FILE__, __LINE__);
  print COUNTER_FILE "$new_counter";
  close (COUNTER_FILE);

		# Once we have dealt with the database id number, we can
		# now grab the current date using the get_date documented
		# later in this script.

  $when_modified = &get_date;

		# With that, we are ready to open the database for
		# appending (>>).

  open (DATABASE, ">>$data_file_path") ||
        &file_open_error ("$data_file_path", "Submit Addition",
        __FILE__, __LINE__);


		# Now, for every field that the user could define on the
		# add form, we will append the value they entered to a
		# variable called $new_row using the append operator (.=).
		# Notice that we will add a pipe (|) delimiter between
		# every field in a database row.

  foreach $field (@db_user_definable_field_order)
    {
    $new_row .= "$form_data{$field}\|";
    }

		# Then, we will tag on the administrative fields of
		# when the addition was made,who made the addition, what
		# group are they in and the unique database id number.

  $new_row .= "$when_modified\|$session_username\|$session_group\|$new_counter\n";
  print DATABASE $new_row;
  close (DATABASE);

		# Once the database has been appended to, we will note
		# what we did in the log file, release the lock file so
		# that others can make their own additions and let the
		# user know that their item was added successfully.

  open (LOG_FILE, ">>$location_of_log_file") || &file_open_error
	("$location_of_log_file", "Submit Addition",
        __FILE__, __LINE__);
  print LOG_FILE "ADD\|$new_row";
  close (LOG_FILE);
  &release_file_lock("$location_of_lock_file");

  &successful_addition_message;
  }

#######################################################################
#                       Submit a Modification                         #
#######################################################################

		# The user might also be submitting a modification to the
		# database.

sub submit_modification
  {

		# The first thing we must do is make sure that they
		# actually chose a database item to modify.  If they did
		# not, we better warn them and stop processing.

  if ($form_data{'item_to_modify'} eq "")
    {
    &no_item_submitted_for_modification;
    exit;
    }

		# If they did choose an item, we need to find that items
		# so that we can modify it.  To do so, we'll open the data
		# file and read through it a line at a time.  We'll then
		# split up each line into its fields and compare the id
        # number given to us by the user against the id number of
		# the current line.  If it is not the same, we will add
		# the entire line to a variable called $new_data (By the
		# end of this, $new_data is going to hold the entire
		# contents of our database).

  open (DATABASE, "$data_file_path") || &file_open_error
	("$data_file_path", "Modify item",  __FILE__, __LINE__);

  while (<DATABASE>)
    {
    $line = $_;
    chop $line;
    @fields = split (/\|/, $line);

    if ($fields[$index_of_db_id_number] ne $form_data{'item_to_modify'})
      {
      $new_data .= "$line\n";
      }

		# If the id numbers ARE equal, however, it means that we
		# have found the database row that needs to be modified.
		#
		# First, we will save the old line in a variable $old_row.
		# We are going to need that value when we report what
		# happened in the log file.
		#
		# Then, we will go through the basic user-definable fields
		# checking to see which fields the user has asked to
		# modify (Only fields which have a $form_data value, will
		# be modified.)
		#
		# Notice, that we will append this row to $new_row one
		# field at a time.  If the user has not submitted a
		# change, we'll grab the value from the old row.

    else
      {
      $old_row = "$line";
      for ($i=0; $i <= (@db_user_definable_field_order-1); $i++)
        {
        $index = @db_user_definable_field_order[$i];
        if ($form_data{$index} ne "")
          {
          $new_row .= "$form_data{@db_user_definable_field_order[$i]}\|";
          }
        else
          {
            $new_row .= "$fields[$i]\|";
          }
        } # End of for ($i=1; $i <= @db_user_definable_field_order; $i++);
      $new_data .= "$new_row";

		# Now we will complete the row by adding all of the
		# administrative variables like the date and the
		# authentication values.  Notice that if the person who is
		# modifying the data is an admin, we will use the group
		# and user values from the old row instead of changing it
		# to admin.  That way the original poster will still be
		# able to modify it.

      $when_modified = &get_date;
      $who_modified = $session_username;

      if ($session_group eq "admin")
        {
        $group = $fields[$index_of_group_who_modified];
        $who_modified = $fields[$index_of_who_modified];
        }
      else
       {
       $group = $session_group
       }

      $new_data .= "$when_modified|$who_modified|$group|$fields[$index_of_db_id_number]\n";
      $new_row .= "$when_modified|$who_modified|$group|$fields[$index_of_db_id_number]";
      } # End of  else
    } # End of while (<DATABASE>)
  close (DATABASE);

		# Now that we have appended the entire database as well as
		# the modified row to $new_data, it is time to change the
		# data file. However, first, we must make sure that the
		# user is performing a legal operation.  The next if test
		# asks 1) is the user the original poster of the database
		#row or are they in the same group as the user who posted
		# it (provided that group is not the default "user" group
		# which everyone is assigned to, 2) or are they an
		# administrator.  If the user passes this test and the
		# admin has set the script to use authentication, the
		# script will add the overwrite the old database with the
		# contents of $new_data, protecting it with a lockfile as
		# we did for addition.

  if ((($session_username eq $fields[$index_of_who_modified]) ||
      (($session_group eq $fields[$index_of_group_who_modified]) &&
       ($session_group ne "user"))) ||
      ($session_group eq "admin") || ($should_i_authenticate ne "yes"))
    {
    &get_file_lock("$location_of_lock_file");
    open (DATABASE, ">$data_file_path") || &file_open_error
        ("$data_file_path", "Modify Item",  __FILE__, __LINE__);
    print DATABASE "$new_data";

    close (DATABASE);

		# We will also add the modification information to the log
		# file.

    open (LOG_FILE, ">>$location_of_log_file") || &file_open_error
        ("$location_of_log_file", "Modify Item",  __FILE__, __LINE__);
    print LOG_FILE "MODIFY_NEW\|$new_row|MODIFIED BY $session_username\n";
    print LOG_FILE "MODIFY_OLD\|$old_row\n";
    close (LOG_FILE);

    &release_file_lock("$location_of_lock_file");
    &successful_modification_message;
    }
  else
   {
   &unsuccessful_modification_message;
   }
  }

#######################################################################
#                       Submit a Deletion                             #
#######################################################################

		# Finally, the user might be asking to make an actual
		# deletion.

sub submit_deletion
  {

		# As in the case of modification, we must make sure the
		# user actually chose an item to delete from the list.

  if ($form_data{'item_to_delete'} eq "")
    {
    &no_item_submitted_for_modification;
    exit;
    }

		# Because we can delete multiple items at one time, the
		# next thing we do is to break up the item_to_delete
		# incoming form data into its separate parts (if there are
		# any) using SplitParam from cgi-lib.pl.

  @items_to_delete = &SplitParam($form_data{'item_to_delete'});

		# Then we will open the data file, read through it a line
		# at a time, splitting each line into its component
		# fields as we did for modificaiton.

  open (DATABASE, "$data_file_path") || &file_open_error
        ("$data_file_path", "Delete Item",  __FILE__, __LINE__);

  while (<DATABASE>)
    {
    $line = $_;
    chop $line;
    @fields = split (/\|/, $line);

		# Then, foreach item in the delete list, we will delete it
		# if the current line's item id is equal to the id
		# submitted.

    $already_added = "no";
    #*** added the following line ->got from the discussion board on Sol's site
    $already_deleted = "no";

    foreach $item (@items_to_delete)
      {
      if ($fields[$index_of_db_id_number] eq $item)
        {
        #*** changed to create multiple lines in log
        $deleted_row .= "DELETE\|$line\|DELETED BY $session_username\n";
		   ###$deleted_row = "$line"; old code
        $already_deleted = "yes";
        }
	  }
      if (($already_added ne "yes") && ($already_deleted ne "yes"))
	  {
        $new_data .= "$line\n";               ### some changes here
        $already_added = "yes"
      }
      }
  close (DATABASE);

		# As we did for modificaiton, we will pass the user
		# through authentication and overwrite the old datafile
		# with the new information.

  if ((($session_username eq $fields[$index_of_who_modified]) ||
      (($session_group eq $fields[$index_of_group_who_modified]) &&
       ($session_group ne "user"))) ||
      ($session_group eq "admin") || ($should_i_authenticate ne "yes"))
    {

    &get_file_lock("$location_of_lock_file");
    open (DATABASE, ">$data_file_path") || &file_open_error
        ("$data_file_path", "Delet Item",  __FILE__, __LINE__);
    print DATABASE "$new_data";
    close (DATABASE);

    $who_deleted = $session_username;

		# And as before, we will append the info to the log file.

    open (LOG_FILE, ">>$location_of_log_file") || &file_open_error
        ("$location_of_log_file", "Delete Item",  __FILE__, __LINE__);
    ###old print LOG_FILE "DELETE\|$deleted_row\|DELETED BY $who_deleted\n";
    #*** changed to accomodate multiple lines in log change
    print LOG_FILE "$deleted_row";

    close (LOG_FILE);

    &release_file_lock("$location_of_lock_file");
    &successful_deletion_message
    }
  else
    {
    &unsuccessful_modification_message;
    }
  }

#######################################################################
#                    Search and Display the Database 		          #
#######################################################################

sub search_and_display_db
  {
                # Before we go in and search however, we format any
                # incoming sort_by information.  We'll discuss the sorting
                # algorithm in just a minute.  However, I want to note
                # here that there are two ways to define a field by which
                # this script will sort the returned database rows.  You
                # can set a default row in the setup file by setting
                # $index_of_field_to_be_sorted_by equal to the index of
                # the field that you want sorted by.  Thus, you may just
                # want to sort automatically by last name and not even
                # give the user the option to sort by another row.
                #
                # On the other hand, you might want to allow the user to
                # choose which field the returned rows are sorted by.  If
                # this is the case, you need to add another form variable
                # to your HTML interface.  This variable MUST be called
                # "sort_by" and will usually be in the form of a
                # select box such as the following:
                #
                # <TH>Sort by which field</TH>
                # <TD><SELECT NAME = "sort_by">
                # <OPTION VALUE = "0">First Name
                # <OPTION SELECTED VALUE = "1">Last Name
                # <OPTION VALUE = "2">Email
                # <OPTION VALUE = "9">Age
                # </SELECT></TD>
                #
                # If you allow the user to define which field to sort on,
                # then this information will override the information in
                # the setup file using the following it test.
                #
                # Remember that arrays start counting from zero so the
                # first filed in your dataabse has an index value of 0,
                # not 1

  if ($form_data{'sort_by'} ne "")
    {
    $index_of_field_to_be_sorted_by = $form_data{'sort_by'};
    }
                # okay, now display the header and grab our lisdt of
                # database rows using &submit_query in db-lib.pl.  Notice
                # that you need to redefine
                # $index_of_field_to_be_sorted_by "before" you display the
                # header because the header displays the hidden form field
                # which will carry that data throughout further
                # self-referencing screens.

  ($total_row_count) = &submit_query(*database_rows);

                # Now here is where the real fun comes in.  We want to
                # sort the database rows that are displayed to the user.
                # The process of this is fairly simple.  For every
                # database row contained in @database_rows, we are going
                # to grab the value of the field defined as the field to
                # be sorted by and append that value to the very begining
                # of the line (so that the field will be repeated twice.)
                # Then you sort the rows (sort will sort on the first
                # characters first which is why you need to append the
                # sortable field to the front.)  Then, finally, you remove
                # the appended field so that the database rows are as they
                # began, but in a sorted order.
                #
                # Thus, if you were sorting by last name and you had the
                # following database rows ($row) in the @database_rows
                # array:
                #
                # Eric|Tachibanaerict@eff.org
                # Selena|Sol|selena@eff.org
                # Gunther|Birznieks|birzniek@hlsun.redcross.org
                #
                # The script would then take each row and append the last
                # name field to the front like so:
                #
                # Tachibana|Eric|Tachibana|erict@eff.org
                # Sol|Selena|Sol|selena@eff.org
                # Birznieks|Gunther|Birznieks|birzniek@hlsun.redcross.org

  foreach $row (@database_rows)
    {
    @row = split (/\|/, $row);
    $sortable_field = $row[$index_of_field_to_be_sorted_by];
    unshift (@row, $sortable_field);
    $new_row = join ("\|", @row);
    push (@new_rows, $new_row);
    }

                # Once we have the rows reformatted as above, we are ready
                # to sort them.  First however, we erase the contents of
                # @database_rows since we are going to want to recreate
                # that array with the sorted rows from @new_rows in just a
                # moment.

  @database_rows = ();

                # Then we are ready to sort...guess what the result is:
                #
                # Birznieks|Gunther|Birznieks|birzniek@hlsun.redcross.org
                # Sol|Selena|Sol|selena@eff.org
                # Tachibana|Eric|Tachibana|erict@eff.org

  @sorted_rows = sort (@new_rows);

                # Next, we need remove that first sortable field so that
                # we have the following:
                #
                # Gunther|Birznieks|birzniek@hlsun.redcross.org
                # Selena|Sol|selena@eff.org
                # Eric|Tachibana|erict@eff.org
                #
                # Look!  They are now sorted by last name!  By the way, if
                # you sort by a field with numbers, remember that
                # computers sort with their own funky rules.  That is, if
                # you don't put a 0 before the nuber 1, it will sort after
                # 9 but alphabetical sorting should be just fine.

  foreach $sorted_row (@sorted_rows)
    {
    @row = split (/\|/, $sorted_row);
    $sorted_field = shift (@row);
    $old_but_sorted_row = join ("\|", @row);
    push (@database_rows, $old_but_sorted_row);
    }

                # now that we have sorted the rows, lets figure out how to
                # display them all.
                #
                # The reason that we wanted to get the $total_row_count
                # back from the search libraries is so that we can then
                # check to make sure that if their search returned no hits
                # we can let them know rather than just sending them a
                # blank screen.

  if ($total_row_count < 1)
    {
    &no_hits_message;
    &generic_form_footer;  # added by (WHB) 05-06-98
    exit;
    }

                # So what exactly do we show the user if their search did
                # turn up some hits. Well, that depends on 1) how many
                # rows were returned from the database as scoring matches
                # to their search criteria, 2) how many rows we have
                # defined in the setup file to allow them to see and 3)
                # how many rows they have already seen.
                #
                # Let me expound.  Let's assume that we have set
                # $max_rows_returned to 2 in the setup file and that their
                # search turned up 11 hits which have just been sorted.
                #
                # The first screen that they should see should say, "You
                # scored 10 hits and I  have been instructed to show you
                # two at a time".  It should then display the first two
                # sorted rows and then provide a button which says "See
                # next 2 hits".  When the user clicks on that button, she
                # should then get the next two sorted rows.  The script
                # needs to remember that she already saw the first two
                # rows as well as remembering that it should only show her
                # two at a time.
                #
                # Finally, the script will have gone through all the rows
                # up to 9 and 10.  The final trick is that it must then
                # tell her that she can click the button to see the next 1
                # hi(t)...no "s" on the end of that....the script has to
                # know some grammar rules.
                #
                # So first, we will collect any incoming information about
                # the hits that the client has seen so far.  This
                # information will be stored in a hidden inpout field
                # called "hits_seen" which must accompany every submit
                # button that promises to show "x more hits".  Note that
                # the first time around, there will be no new_hits_seen
                # value coming in from the form since the user will not
                # have seen any hits yet.

                # Then we need to remove all of the rows from
                # @database_rows that will not be shown to the user quite
                # yet because we are only allowed to display
                # max_rows_returned at any one time.
                #
                # To do this we will first figure out how many elements
                # are left in the array.  Then, we will pop out (remove
                # from the end of the list) all of the extra rows.

  $length_of_database_rows = @database_rows;


  for ($i = $length_of_database_rows-1;$i >= $max_rows_returned;$i--)
    {
    $extra_row = pop (@database_rows);
    }

  &search_results_body;
  &search_results_footer;
  }

#################################################################
#                      get_date Subroutine                      #
#################################################################

                # get_date is used to get the current date and time and
                # format it into a readable form.  The subroutine takes no
                # arguments and is called with the following syntax:
                #
                # $date = &get_date;
                #
                # It will return the value of the current date, so you
                # must assign it to a variable in the calling routine if
                # you are going to use the value.

sub get_date
  {

                # The subroutine begins by defining some local working
                # variables

  local ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst,$date);
  local (@days, @months);

  @days = ('Sunday','Monday','Tuesday','Wednesday','Thursday',
           'Friday','Saturday');
  @months = ('January','February','March','April','May','June','July',
             'August','September','October','November','December');

                # Next, it uses the localtime command to get the current
                # time, from the value returned by the time
                # command, splitting it into variables.

  ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime(time);

                # Then the script formats the variables and assign them to
                # the final $date variable.  Note that $sc_current_century
                # is defined in web_store.setup.  Since the 20th centruy
                # is really 1900-1999, we'll need to subtract 1 from this
                # value in order to format the year correctly.

  if ($hour < 10)
    {
    $hour = "0$hour";
    }
  if ($min < 10)
    {
    $min = "0$min";
    }
  if ($sec < 10)
    { $sec = "0$sec";
    }
  $mon++;
  $year = ($current_century-1) . "$year";
  $date = "$mon/$mday/$year at $hour\:$min\:$sec";
  return $date;
  }

#######################################################################
#                            get_file_lock                            #
#######################################################################

                # get_file_lock is a subroutine used to create a lockfile.
                # Lockfiles are used to make sure that no more than one
                # instance of the script can modify a file at one time.  A
                # lock file is vital to the integrity of your data.
                # Imagine what would happen if two or three people
                # were using the same script to modify a shared file (like
                # the error log) and each accessed the file at the same
                # time.  At best, the data entered by some of the users
                # would be lost.  Worse, the conflicting demands could
                # possibly result in the corruption of the file.
                #
                # Thus, it is crucial to provide a way to monitor and
                # control access to the file.  This is the goal of the
                # lock file routines.  When an instance of this script
                # tries to  access a shared file, it must first check for
                # the existence of a lock file by using the file lock
                # checks in get_file_lock.
                #
                # If get_file_lock determines that there is an existing
                # lock file, it instructs the instance that called it to
                # wait until the lock file disappears.  The script then
                # waits and checks back after some time interval.  If the
                # lock file still remains, it continues to wait until some
                # point at which the admin has given it permissios to just
                # overwrite the file because some other error must have
                # occurred.
                #
                # If, on the other hand, the lock file has dissappeared,
                # the script asks get_file_lock to create a new lock file
                # and then goes ahead and edits the file.
                #
                # The subroutine takes one argumnet, the name to use for
                # the lock file and is called with the following syntax:
                #
                # &get_file_lock("file.name");

sub get_file_lock
  {
  local ($lock_file) = @_;
  local ($endtime);
  $endtime = 20;
  $endtime = time + $endtime;

                # We set endtime to wait 20 seconds.  If the lockfile has
                # not been removed by then, there must be some other
                # problem with the file system.  Perhaps an instance of
                # the script crashed and never could delete the lock file.

  while (-e $lock_file && time < $endtime)
    {
    sleep(1);
    }

  open(LOCK_FILE, ">$lock_file") || &file_open_error ("$lock_file",
                                                      "Lock File Routine",
                                                      __FILE__, __LINE__);

                # Note: If flock is available on your system, feel free to
                # use it.  flock is an even safer method of locking your
                # file because it locks it at the system level.  The above
                # routine is "pretty good" and it will server for most
                # systems.  But if youare lucky enough to have a server
                # with flock routines built in, go ahead and uncomment
                # the next line and comment the one above.

# flock(LOCK_FILE, 2); # 2 exclusively locks the file

  }

#######################################################################
#                            release_file_lock                        #
#######################################################################

                # release_file_lock is the partner of get_file_lock.  When
                # an instance of this script is done using the file it
                # needs to manipulate, it calls release_file_lock to
                # delete the lock file that it put in place so that other
                # instances of the script can get to the shared file.  It
                # takes one argument, the name of the lock file, and is
                # called with the following syntax:
                #
                # &release_file_lock("file.name");

sub release_file_lock
  {
  local ($lock_file) = @_;

# flock(LOCK_FILE, 8); # 8 unlocks the file

                # As we mentioned in the discussion of get_file_lock,
                # flock is a superior file locking system.  If your system
                # has it, go ahead and use it instead of the hand rolled
                # version here.  Uncomment the above line and comment the
                # two that follow.

  close(LOCK_FILE);
  unlink($lock_file);
  }

#######################################################################
#                    file_open_error Subroutine                       #
#######################################################################

                # If there is a problem opening a file or a directory, it
                # is useful for the script to output some information
                # pertaining to what problem has occurred.  This
                # subroutine is used to generate those error messages.
                #
                # file_open_error takes four arguments: the file or
                # directory which failed, the section in the code in which
                # the call was made, the current file name and
                # line number, and is called with the following syntax:
                #
                # &file_open_error("file.name", "ROUTINE", __FILE__,
                #                  __LINE__);

sub file_open_error
  {
                # The subroutine simply uses the update_error_log
                # subroutine discussed later to modify the error log and
                # then uses CgiDie in cgi-lib.pl to gracefully exit the
                # application with a useful debugging error message sent
                # to the browser window.

  local ($bad_file, $script_section, $this_file, $line_number) = @_;
  print "Content-type: text/html\n\n";
  &CgiDie ("I am sorry, but I was not able to access $bad_file in the
        $script_section routine of $this_file at line number $line_number.
        Would you please make sure the path is correctly defined in
        web_store.setup and that the permissions are correct.")
  }