last updated: Wed Mar 23 21:12:50 EST 2005 (sklar)

assignment description.

This homework assignment is the second part of your four-part homework project. This hw2 will be written in C and will implement a "database" (text file) of users.

This assignment is worth 10 points. Distribution of points is indicated below.

IMPORTANT NOTES:

• MAKE SURE THAT ALL REFERENCES TO FILES ARE LOCAL!!! do NOT put any full "http" URLs anywhere in your code. This includes both the C CODE that you write for this homework as well as the PERL CODE from the last homework, some of which you will modify for this assignment. Double-check the hw1 code that you don't modify specifically and if necessary, change any non-local URLs to local.

• MAKE SURE THAT ALL FILES ARE IN ONE DIRECTORY. While in general, it is good programming practice to separate out files into different "data", "code" and "image" directories, it makes things more complicated given the way the submission and automated portions of the grading process work if everyone doesn't follow the same structure for file organization. So please for this assignment, keep everything in one directory. Thanks :-)

I posted an example on the class web page: bigform.html which has examples of a number of different form widgets. When you click on it, the form values get processed by a C program called bigform.c. Note that this C program gives you a good way to parse form name/value data, hint, hint. :-)

Once a user has logged in, you will need to generate all subsequent pages as HTML forms so that you can pass the name of the logged in user from one page to another (using the "hidden" input type).

HOW TO PASS VALUES to CGI programs using the URL.
Look at the URL for the CGI program examples that send data from forms to CGI programs using the GET method (where data is read from the QUERY_STRING environment variable). Try running the form_qs_c.html example and after you enter a message and press "click me", look at the URL in the "location" portion of the browser. If I enter the message "hello", then the action URL in the brower's location window becomes:
http://www1.cs.columbia.edu/~cs3157/cgi/qs_c.cgi?msg=hello

You can use this feature to your advantage (see the "personalize" steps below).

HERE ARE THE STEPS FOR HW2:

1. description of user data file. (0.5 points)

   Begin by deciding what information you want to store for each of the registered users of your system. Each person who uses your movies database will need to register with your system by creating a login name and password, and entering some information that describes them. For example, my user data file contains: user name, password, gender, age group and email address.

   Note that each user must have a unique user name.

   The user data will be kept in a formatted data file called users.dat. The exact format of this file is up to you, but the format should allow you to define multiple records (i.e., users) and fields for each record (user). This means that you must define field separators and record separators.

   Include in your homework submission a plain text file (i.e., not a word doc!) that is called README and contains:

   1. a brief description of what information your user data includes, and
   2. a description of the user data file format.
   Note that in addition to the unique user name, you must have at least 4 other fields!!!

   ALSO NOTE that your documentation file must be named README. It is too much of a hassle for the TAs to go chasing around everyone's directory looking for a file that seems to contain the documentation. If your file is not named README, then we will assume that you did not submit a documentation file, and you will receive 0 points for this portion of the assignment!!!

    

2. site map description. (0.5 points)

   So far, your web site consists of a home page, an about page and a list movies page. Here's the corresponding site map:

   home
   |
   +--- about
   |
   +--- list
   

   In this assignment, you will be adding a registration page and a login page. So you need to think about the sequence of possible screens that your user might follow through your site. For example, they might go to the home page followed by the registration page, followed by the thanks for registering! page, followed by the home page, followed by the login page, etc.

   For this section, you need to add a description of your site map to your README file. It would be good to draw a diagram, as above.

    

3. user.h (0.5 points)

   Define a structure (i.e., using typedef and struct) that contains the five fields (defined above) for describing a user. Store the structure in a header file called user.h. In the C programs you will write below, you will be able to "include" this file by doing:
      #include "user.h"
   instead of having to re-type the structure definition each time you need it.

    

4. user registration form (0.5 points)

   Create an HTML page called register.html which contains an HTML form, your NEW USER REGISTRATION PAGE, and asks for the user to enter values for each of the (at least 5) fields that describe the user. You must demonstrate your facility with HTML forms by using at least 3 different form components (in addition to the "submit" button); for example, an input text field, an input password field and a selection list.

   Use the POST method for sending the data from this form to your CGI program (see below) which will store the user's information in the users data file. The action method, as described below, will be called register.cgi. You must use relative referencing and just specify the file name register.cgi. No path names will be accepted.

    

5. user registration program (2.5 points total, distributed as indicated below)

   Here, you need to write a C program called register.c (to be compiled into register.cgi) which will be the action method activated when the "submit" button is pressed on the NEW USER REGISTRATION PAGE (described above). The program must parse and store the user's input from the registration form in the users.dat file. Make sure to include the user.h file and use the structure in your code below.

   • Grab the data from the form that was sent via the POST method, which means reading from stdin. (0.25 points)
   • Parse the data read from stdin into name/value pairs and store the data in a variable of the type you defined in user.h. (0.75 points)
   • Append the name/value pairs to your users.dat file, following the format you described above. Write a function called appendUser() which takes an argument of the type you defined in user.h and appends the contents of that argument to the end of users.dat. (1 point)
   • Display a friendly message in the browser, indicating that the user has completed the registration process and thanking her/him for registering. (0.25 points)
   • Include a link on the "thank you for registering page" that goes back to the home page of your site. (0.25 points)

    

6. user login form (0.5 points)

   Create an HTML page called login.html which contains an HTML form, your LOGIN PAGE, and asks for the user to enter their username and password. Make sure you use a "password" form widget so the user's password doesn't display on the screen as s/he types it!!

   Use the POST method for sending the data from this form to your CGI program (see below) which will check to see if the user entered a valid login. The action method, as described below, will be called login.cgi. You must use relative referencing and just specify the file name login.cgi. No path names will be accepted.

    

7. user login program (3.5 points total, distributed as indicated below)

   Here, you need to write a C program called login.c (to be compiled into login.cgi) which will be the action method activated when the "submit" button is pressed on the LOGIN PAGE (described above). The program must parse the user's input from the login form and check to see if the user entered a valid username/password. Make sure to include the user.h file and use the structure in your code below.

   • Grab the data from the form that was sent via the POST method, which means reading from stdin. (0.25 points)
   • Parse the data read from stdin into name/value pairs and store the data in a variable of the type you defined in user.h. Note that you'll only be filling the username and password fields, since that's all you'll be grabbing from the login form. (0.75 points)
   • Read the contents of your users.dat file, and check to see if the username and password entered by the user on the LOGIN page match a username/password set in the users.dat file. Do this with two functions. First, write a function called readUsers() which takes an argument that is an array of the type you defined in user.h and reads the contents of users.dat and stores the contents in the array argument. Second, write a function called findUser() which takes one argument that is an array of the type you defined in user.h and a second argument that is a username and returns true (1) if the username argument matches an entry in the array, and returns false (0) otherwise. Note that after you call findUser() and find a username that matches, you'll still have to check if the password that the user entered matches the one in the users.dat file (which you have stored in the array you read in using readUsers()). (1.0 point for readUsers() and 1.0 point for findUser())
   • If the username/password does match, then display a friendly message in the browser, indicating that the user has logged in successfully. Include a link on the "successful login" page that goes back to the home page of your site. (0.25 points)
   • If they do not match, then display a friendly message telling the user what the problem is and suggesting that they try again. Include a link on the "unsuccessful login" page that goes back to the login page so the user can try again. Also include a link that goes back to the home page, in case the user doesn't want to try again. (0.25 points)

    

8. personalize home page (1 point)

   Modify your home page from hw1. Instead of having a static index.html page, write a C program (called index.c, to be compiled into index.cgi) and if it is invoked by someone who is logged in, then it says "welcome mary" (if mary is the user logged in - otherwise substitute "mary" for the user's name...)

   My recommendation for doing this is to use the feature that allows you to pass CGI programs using the URL. So you can invoke index.cgi with the username in the URL when someone is logged in, e.g.: index.cgi?user=mary or without the username (index.cgi) when nobody is logged in. Then inside your C code, check the QUERY_STRING environment variable. If it doesn't exist or it exists but doesn't have a "user=" field, then you know that nobody is logged in.

   Note that you should keep index.html as the default home page for the site when nobody is logged in. Remember to maintain consistency between index.html and the output of index.cgi in this assignment and the subsequent assignments!

   Add to your home page a logout link (that only displays when the home page is output from index.cgi - since that's the only home page a logged in user will have access to). Clicking on the "logout" link should send the user to index.html, i.e., the home page for users who are not logged in.

   Decide how to handle your about page for logged in users. You can either write a about.cgi program or script to make sure that the username doesn't get lost, or you can simply remove the "about" link from your home page for logged in users. That's up to you.

    

9. personalize movies list (0.5 points)

   Modify your PERL code from hw1, list.cgi, so that if it is invoked by someone who is logged in, then it says "welcome mary" (if mary is the user logged in - otherwise substitute "mary" for the user's name...). See the previous step for hints on how to do this. But DO IT IN PERL!!! (the previous step is done in C)

    

10. submit.

    Just like with the labs, you need to submit your homework electronically. Make sure that you have followed the file naming specifications listed above (case included!) Failure to follow do so will result in 10% off the assignment grade -- ouch!

    You need to submit: README, user.h, register.html, register.c, users.dat, login.html, login.c, index.c, index.html, about.html, list.cgi, your version of movies.dat, any image files that your movies.dat file references locally, and any other files we'll need to run your assignment.

    • Log in to a CS cluster machine by running:
      

      bash# ssh cluster.cs.columbia.edu
      

    • From your hw2 working directory (on cluster), run the submit-hw script:
      

      unix$ ~cs3157/bin/submit-hw 2
      

    • Answer the script's questions as they come up. You will receive an email shortly after the script is done running --- on your CS account!