dcodeurl Documentation

This C program is an aid to writing CGI scripts that can decode the contents of the QUERY_STRING environment variable. If you are unfamiliar with the basics of CGI try reading the introduction first. dcodeurl acts as a filter taking data from the standard input and placing the results on the standard output. By itself it is not very useful, but when used in a shell script, it can make it easy to send the output of a simple fill-in form to a file or via e-mail, even if the browser does not support the mail-to tag.

To use dcodeurl, you must first design an HTML form. If you are unfamiliar with designing forms in HTML look and this overview first. The form that you design must use a method of GET. This will limit the amount of data that your form can return because the results of the form are placed in the environment variable, QUERY_STRING. The format of the data is the same as that for the query placed in URLs after the ? when using the ISINDEX tag. In brief, equal signs (=) separate the field names from the values entered; ampersands (&) separate one line from the next; plus signs (+) are used in place of spaces; and any other special character (including =, &, +, or %) used in the value of a field are escaped. An escaped character takes the form of a percent sign (%) followed by the hexadecimal representation of the ASCII value of the character.

The dcodeurl program takes data in this encoded form and converts it to a more "people readable" form. Each field will be placed on a separate line, with the field name on the left and the data on the right. (In between is an = sign.) All spaces (+) and special characters are converted back to their original character values. For example, the following QUERY_STRING:

  name=Jeff+Peters&phone=555-1212&favorite_candy=M%26M+plain+candies

would be decoded as:

  name = Jeff Peters
  phone = 555-1212
  favorite_candy = M&M plain candies

The dcodeurl program has another feature which makes it easier to use with the sendmail command. If a filename is passed to dcodeurl on the command line, this file will be sent to the standard output before the decoded results of the standard input. This allows you to define a SMTP header with addressing information and any other message preface. A working example of this system is found in the infoform.html file used by the Chapman Campus Tour.

  <FORM METHOD="GET" ACTION="/cgi-bin/request-info">

This is the form tag from the infoform.html file, and it shows the method as GET. It also shows the action as "/cgi-bin/request-info". request-info is a CGI shell script that uses the dcodeurl program.

  #!/bin/sh

  echo Content-type: text/html
  echo
  echo "<h3>Form Accepted</h3>"
  echo "<hr>"
  date +"<i>%A, %B %d, %<br>%r</i><p>"
  echo "Thank you for your interest in <b>Chapman University</b>."
  echo "The information you have requested will be sent to you.<p>"
  echo $QUERY_STRING | dcodeurl chapinfo.txt | /usr/lib/sendmail -i -t

The first two lines echoed back to the server tell it what the content format will be; in this case it is an HTML encoded text file. (The blank line after the Content-type line is required.) The next four echoed lines (and the date command) send a simple response to the server telling the person who sent the form that their form was accepted.

The last line is the interesting one. The QUERY_STRING environment variable is piped into the dcodeurl program for decoding, but first, the text file, chapinfo.txt, will be sent to standard output.

  From: ? (WWW Browser)
  To: low@chapman.edu (Johnelle Low)
  Subject: Request for Information

  The following individual has requested additional information about
  Chapman University:

This file contains the SMTP header information. This file and the decoded QUERY_STRING are piped to the /usr/lib/sendmail command which will mail it to Johnelle Low. The -t option tells sendmail to scan the message for recipient info, and the -i option keeps the message from being cut short by a lone "." on a line (the old message termination indicator).

Because dcodeurl is just a filter, it's use is quite flexible. The results could be redirected to a file, or sent to a printer. The dcodeurl.c program could also be modified to output the data in a different format for other uses, such as a delimited text file for importing into a database program.

If you modify the program, please copy it to another file first. To compile the program just type:

  cc -o dcodeurl dcodeurl.c

Make sure that you put the program (and any other CGI scripts or text files that you use) in the /usr/local/etc/httpd/cgi-bin directory. Also include a copy of you source code in the /usr/local/etc/httpd/cgi-src directory so that others can benefit from your work.