secure
online
application

Section III - Cgi-bin scripts

1) OVERVIEW

• 1.a) What are cgi-bin scripts?
• 1.b) Where should I put cgi-bin scripts?
• 1.c) Charges

2) FEEDBACK FORMS AND SIMILAR FORMS

• 2.a) add.html
• 2.b) mail.txt
• 2.c) Using cgi-email (also easy to use)
• 2.d) Charges
• 2.e) Using formmail (easiest to use)

3) IMAGEMAPS

4) HTML PAGE COUNTERS

• 4.a) Using Count.cgi
• 4.b) Using nph-count

5) COMPLETE WEB SITE COUNTERS

• 5.a) Using wusage
• 5.b) Sample wusage.conf file
• 5.c) Sample prefix.html and suffix.html files
• 5.d) Using wwwstat
• 5.e) Analog: A WWW logfile analysis program

6) TROUBLESHOOTING

1) OVERVIEW

1.a) CGI scripts...

"cgi" stands for "common gateway interface", a fancy name meaning computer programs running on the web that can be invoked from a WWW page at the browser. The "bin" part alludes to the binary executables that result from compiled or assembled programs. It is a bit misleading because cgi's can also be Unix shell scripts or interpreted languages like Perl.

A typical use for cgi is the processing of online forms. When the user fills in the boxes on the form and hits the SUBMIT button, the cgi program specified in the html will be run at the , and the information in the boxes become available to the program as parameters. The program, being a program, can then do anything the programmer wanted it to do.

"cgiemail", for example, is a canned program written in C that gathers up the contents of the boxes on the form and emails them to a specified destination, then sends a WWW page confirming the action.

1.b) Where should I put cgi-bin scripts?

Put your cgi-bin scripts in the web subdirectory named cgi-bin.

If your domain is named company.com, you would then access your scripts as /cgi-company/

1.c) Charges

DGL can create and design scripts for you. Our rate for scripting is $150 per hour (with a one hour minimum). We can provide a quote for you on more complex scripts. The following scripts are already provided by DGL: feedback forms, imagemaps, page counter, and guestbook scripts.

2) FEEDBACK FORMS AND SIMILAR FORMS

Cgiemail is a program written in the C language that takes the contents of fill-in boxes on a form and emails them to a specified destination. In addition to the form specification in the .html file, a mail specification in a .txt file is required to format the resulting email message.

We provide cgiemail in the cgi-bin directory of each machine. Thus, it would be called with a URL such as /cgi-bin/cgiemail/mail.txt. Details are provided below.

While there are a number of subsections below this one, they all work together and are meant to be read from start to finish.

2.a) add.html

If you've never dealt with HTML forms before, don't worry. They're easy to create and understand. (And if you briefly tried that link and thought, noooooo!!! I don't want to read this!, scroll down a bit. The easy examples are at the bottom. You should not need to follow it at all to understand what will be explained presently.)

The form prompts the user for data which is sent to the as simple key-value pairs. Each <input> tag specifies a record. The key is given by the name attribute, and the value is given by the value attribute. The type attribute tells the browser what kind of data to expect. Now, try looking at the example.

Please note that the hidden items are used to transmit critical info to cgiemail. They provide the location of the success file, the name of the person the results should be sent to, and the subject of the form. When making your own forms, you would definitely (please!) change the e-mail address in the "required-to" field, and likely the subject in the "subject" field. The first item tells cgiemail what to show the user after succesfully completing the form. You can, but don't need to, customize this.

After that come the items that are actually presented to the user. You'll want to use type=text input items with cgiemail; it's a simple tool. The size=60 tells the browser how big to make the box. The name=something is required in each input tag, otherwise the browser wouldn't know how to send the data to the . The value="" attribute is correct in most cases, unless you want a default value in the form.

Note that if a field begins with required-, cgiemail will require that the user enter a value for this field. This is particularly useful if you want to require a user to submit their e-mail address.

When the user presses the Submit button, the data goes to our machine where cgiemail starts doing something with it. What it does is controlled by ...

2.b) Mail.txt

Make sure that you upload mail.txt in ASCII mode.

Now that we have all this data, what do we do with it? Mail it, of course! But for flexibility, cgiemail requires that you create a mail.txt file to show it what to send. (If you didn't want flexibility you'd use a mailto link.) The program will read in this file, perform substitutions, and pass it to the mail system.

First, how does cgiemail know where to find this file? Look at the first line in the example form used in the previous section. The bit after the word cgiemail in the action attribute tells cgiemail where to look. Cgiemail does not know what your domain is, because it is installed for everyone. So, the first component of this path must be your domain. After that, it goes to your www directory and looks from there.

Camper.com might want to put the mail.txt file in his www directory. His form would then start off with <form method=post action="/cgi-bin/cgiemail/mail.txt">

BTW, there's nothing magical about the name mail.txt. Feel free to call it mail1.txt, or form1.mail, or what suits you, as long as the form has the correct name for what you uploaded.

Here's the mail.txt we used with the form presented earlier. It's pretty simple. Note that the first several lines are mail headers. You probably shouldn't change that part, or the corresponding parts in your form. In particular, there must be a To: header or the mail won't go anywhere!

What cgiemail does is simply replace every string that looks like [key] with the value the user typed in to the field with name=key. That's all. You can lay out your form as is best for your users, but lay out your mail.txt as is best for you to read. You can even insert gobs of text to help format the output. Only the [key] parts will be replaced by cgiemail.

2.c) Using cgi-email

Actually, if you've read the previous two sections you should know enough to use it. We'll summarize here.

1. Get a sample add form and sample mail.txt file. If you prefer to edit things on-line, upload them to your www directory.
2. Replace 'YourDomain' in the form with your domain.
3. Edit the form to have the input areas you like.
4. Edit mail.txt to use that input.
5. Have your variables start with the name required- if you want to require that the user input these fields. (Like 'required-to' in the example.)
6. You may alter the success variable in the HTML form to change the message someone receives after filling out the form.
7. Wait! What we gave you was an example form, not a complete example HTML file. Put the necessary stuff around it to make it that. (Minimally put it between a <body> </body> pair.)
8. If you were editing off-line, upload the files.
9. Try it, and play with it.

2.e) Using formmail

formmail.cgi should already be in your cgi-bin directory. Formmail is a simple to use cgi script that will email to you the contents of a web based form. To use it, simply reference it in your html page like:
<FORM ACTION="http://www.YourDomain.com/cgi-Domain/formmail.cgi" METHOD="POST">

You will need to at least include the following line containing the email address of where you want the form information to be emailed to:
<INPUT TYPE="hidden" NAME="recipient" VALUE="EmailAddress@YourDomain.com">

That's it! Of course, there are lots of other configuration options you can set to customize how the email will look, require certain fields, and redirect the user to a URL after submitting the form. This link contains the various options for customizing formmail.cgi

3) IMAGEMAPS

'Imagemap' refers to an interaction between a user's browser and the WWW which allows clicking on an image to select hyperlinks. (Other implementations have a seperate /cgi-bin/imagemap program. Our handles them internally. Use the reference style shown below, not one like /cgi-bin/imagemap/mymap.map.) Each designated portion of the image may select different links.

Images that are to be used as imagemaps must be designated as "ISMAP". A companion .map file specifies the coordinates of the portions of the image that are hyperlinks, and the URL or local reference of the link.

The following HTML:

<A HREF="name-of-map-spec-file.map">
<IMG BORDER SRC="name-of-image.gif" ISMAP></A>

tell the browser that "name-of-image.gif" is to be displayed and used as an imagemap. The "name-of-map-spec-file.map" file contains the coordinates of the clickable areas in the image and specify the hyperlinks associated with each clickable area.

The map specification file MUST have extension ".map". While this example assumes the file is located in your www directory, it may be located anywhere under the www directory. In such a case, the path from the www directory must be specified. If you put it in /home/your-id/www/map-directory, then use <A HREF="../map-directory/name-of-map-spec-file.map">

Please use the NCSA format for your .map file.

A file named imagemap.conf does NOT have to edited when using our imagemap program. That complication has been removed from our version of imagemap.

Here is a sample file named fo-abc.map:

default http://camper.org/links.html
poly http://camper.org/links.html#A 23,14 44,2 66,14 66,39 45,51 23,39
poly http://camper.org/links.html#A 67,14 88,2 110,14 110,39 89,51 67,39
poly http://camper.org/links.html#C 111,14 132,2 154,14 154,39 133,51 111,39

Note that the URL's are full URLs. You can't use relative URLs.

The number pairs specify the X-Y coordinates in pixels of the points of the three hexagons that are the clickable areas in fo-abc.map. Clicks outside of the areas specified get the default link.

4) HTML PAGE COUNTERS

4.a) Using Count.cgi

Adding a counter to your pages is quite easy. All that is needed is to add a
<IMG SRC="http://www.YourDomain.com/cgi-YourDomain/Count.cgi?df=name_of_file"> tag in your page that calls the counter script.

The Count.cgi script is in your personal cgi-bin dir, and writes its data files to the data dir off of your www directory. The configuration file can be found in your home directory.

This counter program is quite powerful, allowing you to have the same counter on mutiple pages, change the color of the digits or border, change the style of the counter, show a digital clock, change how mant digits are shown, etc..
This Examples Page demonstrates some of the features of this counter.

For more information on this counter, please refer to http://www.fccc.edu/users/muquit/Count.html

4.b) Using nph-count

Option 2
<IMG SRC="http://www.mydomain.com/cgi-mydomain/nph-count?width=5&link=http://www.mydomain.com/index.html">

For a counter on another page, simple replace the URL after link= with the HTML file you want to track. That's it! This counter looks like

5) COMPLETE WEB SITE COUNTERS

DGL runs wusage and wwwstat automatically to generate usage reports for each of our customers. These programs are explained below. Analog allows you to run and customize web stats right from your web browser.

5.a) Using wusage

Wusage is available to all of our customers. It is a powerful count program that is run once a week. It generates web pages which include graphical representations of the amount of hits that you have received both in the past week and over time. To access it, go to:
http://www.YourDomain.com/wusage

Wusage is run automatically each week on Sunday morning. It puts its output in the directory wusage under your www directory. If you do not see a wusage directory or it is empty after a week or two, please contact us and we will make sure it is setup for you. The file wusage.conf in your wusage directory is the configuration file for the program. You may customize this by editing the file and reading the comments contained in the file. Also contained in your wusage directory are the files prefix.html and suffix.html, which put customized headers and footers on your wusage stats pages. You may also customize these to your liking.

5.c) Sample prefix.html and suffix.html files

These files are referenced by wusage.conf, and are put at the top and bottom of all reports. Here is the prefix.html we used for world-health.net:

<HTML>
<HEAD>
<TITLE>World Health Net - Statistics Report</TITLE>
</HEAD>
<BODY BGCOLOR="#ffffff" TEXT="#0000bf" LINK="#0000ff">
<center><IMG SRC="bk_bar.gif" alt=""><p>
<H1>World Health Net - Statistics Report</H1>
<IMG SRC="bk_bar.gif" alt=""><p>
</center>

And here is the suffix.html we used for world-health.net:

<center><IMG SRC="bk_bar.gif" alt=""></center><p>
</body></html>

5.d) Using wwwstat

wwwstat is a web site statistics program that is run each night for our customers. It makes a complete html page that logs and displays the total amount of data transferred as well as the types of access and what pages were accessed. This data is outputted to the logs directory, a sub-directory under your www directory, as the file usage.html This data is summarized for the current month, and keeps a running total of hits that are averaged over the month as well as daily stats. To access it, go to:
http://www.YourDomain.com/logs/usage.html

If you do not have a usage.html file in your logs directory after a few days, please let us know and we will make sure it is setup for your account. You may also run this program manually with your own options if you need different generated statistics. The program is located at /www/wwwstat, and if you type "/www/wwwstat -h", it will output a help file to the screen showing you the options you may use.

5.e) Analog

Analog is a WWW logfile analysis program. All virtual domain customers have access to this GREAT web stat program via the WWW. To use it, simply point your web browser to: http://www.YourDomain.com/logs/analogform.html
Then choose the options you would like and click on the [Produce Statistics] button at the bottom of the page. This will produce a summary of your website access statistics, customized to your liking.

6) TROUBLESHOOTING

"When I activate my CGI program, I get back a page that says ' Misconfigured'".

Log on and go to your www/cgi-bin directory. Try running the program manually to see what errors you get. Remember that when a CGI program produces error output, that output is discarded and you get the non-specific page you saw. To check on it, you'll have to run it yourself.

If you get something like

bash: ./search.pl: No such file or directory

and you know you typed the name correctly, it's almost certain you uploaded the script from your PC or Macintosh in binary mode. Perl scripts are ASCII text and must be transferred in ASCII mode. (So are shell scripts and any other kind of script that starts with '#!' on the first line.)

Then there's this response:

Literal @dgl now requires backslash at ./bigones line 16, within string

Many scripts that you'll find widely distributed are still written for Perl, version 4. Our /usr/bin/perl is version 5, which is 99.9% compatible with version 4, along with many improvements. You've found the other 0.1%.

In Perl 4, you could get away with a statement like

$mailaddress = "joe@schmoe.com";

because Perl didn't think the '@' sign was special in a string. Perl 5 does, so you need to escape it, like so:

$mailaddres = "joe\@schmoe.com";

You can't just change all the '@' signs to '\@', only the ones in strings. To speed your search, however, Perl gives you the line number of the problem line(s) in its error message. Fix them, and see if it works.