CHAPTER 3. CGI-SCRIPTS

3.1 Pre-installed CGI-SCRIPTS
3.1.1. Cgiemail
3.1.2. FormMail
3.1.3. Pagecounter
3.1.4. WWWboard
3.1.5. Guestbook
3.2. Your Own CGI-SCRIPTS
3.2.1. How do I run my own CGI program
3.2.2. Paths to Date, Mail, Perl, etc.
3.2.3. Setting permissions
3.2.4. Trouble shooting CGI-bin problems


 

3.1. Pre-installed CGI-SCRIPTS

 

CGI-SCRIPPS  are computer programs running on the webserver that can be invoked from a web page in the browser.  These programs adds
functionality to web pages that are not possible with just HTML.

HostAvenueT TM provides 5 popular and useful CGI-SCRIPTS.  These come already pre-installed on your account under your cgi-bin directory.

 
3.1.1. cgiemail - Form Processing
 
Suppose you want to have an order form on your web page whose result would be emailed to you, follow instructions below:

1) Create a file called "order.txt" using a text editor such as Notepad
in your local PC.

2) Type following lines. Of course, you can add more fields to fit your
specific needs.

To: whatever@whereever.com
From: [email]
Subject: Order from [name]
Customer Contact Information
name: [name]
phone: [phone]
email: [email]
address: [address]
Order Information
Product Purchased: [product]

IMPORTANT: You MUST have the To: and the Subject: line followed by the blank line. Those three lines MUST be on the FIRST THREE lines.
That is the file that will be sent to whatever@whereever.com
Now, cgiemail will automatically replace [name], [phone], anything in
the brackets with the corresponding user supplied info from the web
form.

3) Save this file in plain text mode. Upload it to your main www/ folder
via FTP or FrontPage98 Explorer.

4) You need to create a web form in html.Here is a part of the web form
page called "order.html"

<form method="post" action="/cgi-bin/cgiemail/order.txt">
<input type="text" name="name">Your name?
<input type="text" name="phone">Your number?
<input type="text" name="email">Your email?
etc...

IMPORTANT: The name of the form field (e.g. name="name") must exactly match the what you put within the bracket in your order.txt file for it be replaced with the value your customer enters. For example, if you have <....name="name"> in your order.html and name: [Name], it will not work.

5) If you want to have your own customized "success" page, place the
following line in your form page:
<input TYPE="hidden" NAME="success"
VALUE="http://[yourdomain].com/somepage.html">

It will then redirect to somepage.html.
 
 
3.1.2. FormMail.pl

 
FormMail is a generic www form to e-mail gateway, which will parse the
results of any form and send them to the specified user. This script has
many formatting and operational options, most of which can be specified
through the form, meaning you don't need any programming knowledge or multiple scripts for multiple forms. This also makes FormMail the
perfect system-wise solution for allowing users form-based user feedback capabilities without the risks of allowing freedom of CGI access.
 
There is only one form field that you must have in your form, for
FormMail to work correctly. This is the recipient field. Other hidden
configuration fields can also be used to enhance the operation of
FormMail on your site. The action of your form needs to point towards
this script (obviously), and the method must be POST in capital letters.

Here's an example of the form fields to put in your form:
 
<FORM METHOD="POST"
ACTION="http://yourdomain.com/cgi-yourdomain/FormMail.pl">
<input type="hidden" name="recipient" value="whoever@yourdomain.com">
<input type="hidden" name="subject" value="Order">
<input type="hidden" name="return_link_url"
value="http://yourdomain.com/">
<input type="hidden" name="return_link_title" value="Back to Main Page">
The following are descriptions and proper syntax for fields you can use
with FormMail.
 
Recipient Field
Description: This form field allows you to specify to whom you wish for
your form results to be mailed. Most likely you will want to configure
this option as a hidden form field with a value equal to that of your
email address.
Syntax: <input type=hidden name="recipient"
value="email@yourdomain.com">

Subject Field
Description: The subject field will allow you to specify the subject
that you wish to appear in the email that is sent to you after this form
has been filled out. If you do not have this option turned on, then the
script will default to a message subject: "WWW Form Submission".
Syntax: If you wish to choose what the subject is:
<input type=hidden name="subject" value="Your Subject">
To allow the user to choose a subject:
<input type=text name="subject">

Email Field
Description: This form field will allow the user to specify their return
email address. If you want to be able to return e-mail to your user, I
strongly suggest that you include this form field and allow them to fill
it in. This will be put into the From: field of the message you receive.
If you want to require an email address with valid syntax, add this
field name to the 'required' field.
Syntax: <input type=text name="email">

Realname Field
Description: The realname form field will allow the user to input their
real name. This field is useful for identification purposes and will
also be put into the From: line of your message header.
Syntax: <input type=text name="realname">

Redirect Field
Description: If you wish to redirect the user to a different URL, rather
than having them see the default response to the fill-out form, you can
use this hidden variable to send them to a pre-made HTML page.
Syntax: To choose the URL they will end up at:
<input type=hidden name="redirect"
value="http://yourdomain.com/to/file.html">
To allow them to specify a URL they wish to travel to once the form is
filled out:
<input type=text name="redirect">

Required Field
Description: You can require certain fields in your form to be filled in
before the user can successfully submit the form. Simply place all field
names that you want to be mandatory into this field, separated by
commas. If the required fields are not filled in, the user will be
notified of what they need to fill in, and a link back to the form they
just submitted will be provided.
To use a customized error page, see 'missing_fields_redirect'
Syntax: If you want to require that they fill in the email and phone
fields in your form, so that you can reach them once you have received
the mail, use the syntax like:
<input type=hidden name="required" value="email,phone">

Env_report Field
Description: Allows you to have Environment variables included in the
email message you receive after a user has filled out your form. Useful
if you wish to know what browser they were using, what domain they were coming from or any other attributes associated with environment
variables. The following is a short list of valid environment variables
that might be useful:
REMOTE_HOST - Sends the hostname making the request.
REMOTE_ADDR - Sends the IP address of the remote host.
HTTP_USER_AGENT - The browser the client is using.
(Note: In our case, both REMOTE_HOST and REMOTE_ADDR are the same, since our servers don't do the reverse DNS lookup needed to generate the true REMOTE_HOST string).
Syntax: If you wanted to find all the above variables, you would put the
following into your form:
<input type=hidden name="env_report"
value="REMOTE_HOST,REMOTE_ADDR,HTTP_USER_AGENT">

Sort Field
Description: This field allows you to choose the order in which you wish
for your variables to appear in the email form that FormMail generates.
You can choose to have the field sorted alphabetically or specify a set
order in which you want the fields to appear in your mail message. By
leaving this field out, the order will simply default to the order in
which the browsers send the information to the script (which is usually
the exact same order as they appeared in the form). When sorting by a
set order of fields, you should include the phrase "order:" as the first
part of your value for the sort field, and then follow that with the
field names you want to be listed in the email message, separated by
commas.
Syntax: To sort alphabetically:
<input type=hidden name="sort" value="alphabetic">
To sort by a set field order:
<input type=hidden name="sort" value="order:name1,name2,etc...">

Print_config Field
Description: print_config allows you to specify which of the config
variables you would like to have printed in your e-mail message. By
default, no config fields are printed to your email. This is because the
important form fields, like email, subject, etc. are included in the
header of the message. However some users have asked for this option so
they can have these fields printed in the body of the message. The
config fields that you wish to have printed should be in the value
attribute of your input tag separated by commas.
Syntax: If you want to print the email and subject fields in the body of
your message, you would place the following form tag:
<input type=hidden name="print config" value="email, subject">

Print_blank_fields Field
Description: print_blank_fields allows you to request that all form
fields are printed in the return HTML, regardless of whether or not they
were filled in. FormMail defaults to turning this off, so that unused
form fields aren't emailed.
Syntax: <input type=hidden name="print_blank_fields" value="1">
Title Field
Description: This form field allows you to specify the title and header
that will appear on the resulting page if you do not specify a redirect
URL.
Syntax: If you wanted a title of 'Feedback Form Results':
<input type=hidden name="title" value="Feedback Form Results">

Return_link_url Field
Description: This field allows you to specify a URL that will appear, as
return_link_title, on the following report page. This field will not be
used if you have the redirect field set, but it is useful if you allow
the user to receive the report on the following page, but want to offer
them a way to get back to your main page.
Syntax: <input type=hidden name="return_link_url"
value="http://yourdomain.com/index.htm">

Return_link_title
Description: This is the title that will be used to link the user back
to the page you specify with return_link_url. The two fields will be
shown on the resulting form page as:
Syntax: <input type=hidden name="return_link_title" value="Back to Main Page">
 
 
Using FormMail.pl via Secure Server
 
 
If you are using FormMail.pl through the secure server, you can still
place your form anywhere on your webspace you want to, but you MUST use the following URL as the ACTION of your form:
https://[secureserver].com/cgi-yourdomain/FormMail.pl
Here's an example of how the first parts of your form might look:
 
<FORM METHOD=POST
ACTION="https://[secureserver].com/cgi-[yourdomain]/FormMail.pl">
<input type=hidden name="recipient" value="whoever@yourdomain.com">
<input type=hidden name="subject" value="Order">
<input type=hidden name="return_link_url"
value="http://yourdomain.com/">
<input type=hidden name="return_link_title" value="Back to Main Page">
 
It is still important that you call your order page through a secure URL
in order to work properly. For example:
https://[secureserver].com/[yourdomain]/order.html
 
Please contact support@HostAvenue.com to find out the name of the secure server you should be using.
 
3.1.3. Page Counter
 
A graphical counter that you can use by placing the following line in
your page:
<img SRC="/cgi-bin/nph count?width=5&amp;link=http://[yourdomain].com/yourpage">

This is what the counter looks like :

 

3.1.4. WWW Board

 
WWW Board is a threaded World Wide Web discussion forum and message board, which allows users to post new messages, follow-up to existing ones and more. It is already preconfigured for your server. Just go to http://www.[yourdomain].com/wwwboard to post your messages there.
There are several options you may want to configure. First of all, the
index.htm file in the wwwboard directory can be customized any way you
wish as long as you leave the method and input tags the way they are.
Additionally, here are some options contained in the wwwboard.pl script
itself (located in your cgi-bin directory) which you may want to change,
depending on your needs:

$show_faq = 1;
This option allows you to choose whether or not you want to display a
link to the FAQ on every individual message page or not. It defaults to
1 and the link will be put in at the top of the message along with links
to Followups, Post Followup and Back to $title. Setting this to 0 will
turn it off, and keeping it at 1 will keep the link. You need to create
a faq.html file and put it inside the wwwboard directory. The FAQ can
contain any information you want to give your visitors about how the
board works, your organization, types of postings that will be allowed,
etc.

$allow_html = 1;
This option lets you choose whether or not you want to allow HTML
mark-up in your posts. If you do not want to allow it, then everything
that a user submits that has <>'s around it will be cut out of the
message. Setting this option to 1 will allow HTML in the posts and you
can turn this option off by setting it to 0.

$quote_text = 1;
By keeping this option set to 1, the previous message will be quoted in
the followup text input box. The quoted text will have a ':' placed in
front of it so you can distinguish what had been said in the previous
posts from what the current poster is trying to get across. Setting this
option to 0 will leave the followup text box empty for the new poster.

$subject_line = 0;
There are three options for the way that you can display the subject
line for the user posting a followup. Leaving this option at 0 which is
the default value, will put the previous subject line into the followup
form and allow users to edit the subject however they like. Setting this
option to 1, however, will quote the subject, but simply display it to
the user, not allowing him or her to edit the subject line. The third
and final option can be achieved by setting the $subject_line variable
to 2. If it is set to 2, the subject will not be quoted and instead the
user will be prompted with an empty subject block in their followup
subject line.

$use_time = 1;
This option allows you to choose whether or not you want to use the
hour:minute:second time with the day/month/year time on the main page.
Day/Month/Year will automatically be placed on the main wwwboard.html
page when a new entry is added, but if you leave this variable at 1, the
hour:minute:second time will also be put there. This is very useful for
message boards that get a lot of posts, but if you would like to save
space on your main page, you can set this to 0, causing the
hour:minute:second display not to be added.
 

3.1.5. Guestbook

 
Guestbook allows you to set up your own comments page. From there,
visitors can add entries to your guestbook and they will be displayed
with the most recent at the top and scrolling down, or vice versa. Other
options include the ability to limit HTML in the entry, link to e-mail
address with mailto tag, use a log to log entries, redirect to a
different page after signing, emailing whenever a new entry is added,
and much more.
Guestbook is already set up for use on your server. You can simply use
the following URL to access it:
 
http://[yourdomain].com/guest/guestbook.html
If you want to change any of the configuration options, locate the
guestbook.cgi file in your Guestbook directory (inside your www
directory). Download it to your hard drive in ASCII mode, and save it
somewhere safe. Create a copy of the file and give it the same name,
then edit the options as specified below. Keep your backup of the
original guestbook.cgi in case you run into problems.

Option 1: $mail
This option will allow you to be notified via an E-mail address when a
new entry arrives in your guestbook. The entry will be mailed to you as
a notification. If you should choose to turn this variable on you will
need to fill in the 2 variables that go along with it:
$recipient - Your email address, so that the mailing program will know
who to mail the entry to.
$mailprog - The location of your sendmail program on your host machine.

Option 2: $uselog
This will allow you the ability to use the short log feature. It is
already turned on so you will have to change it to 0 if you do not wish
to use it. It has been implemented since there are probably many people
who feel no need to have a log when people are making entries to a file
anyway. Keep in mind that it will show errors which is one nice aspect
about it.

Option 3: $linkmail
Turning this option on will make the address links in your guestbook
become hyperlinked. So instead of simply having (name@some.host) it will
put (<a href="mailto:name@some.host">name@somehost</a> so that anyone
can simply click on the address to email them.

Option 4: $separator
This allows you to choose whether you want guestbook entries to be
separated by a Paragraph Separator <p>, or a Horizontal Rule <hr>. By
changing the 0 in the script to a 1, you will turn on the <hr> separator
and turn off the <p> separator. The 0 option will do the reverse of
that; turn on the <p> and turn off the <hr>.

Option 5: $redirection
By choosing 1 you will enable auto redirection and 0 will return a page
to the user telling them their entry has been received and click here to
get back to the guestbook.

Option 6: $entry_order
Set this option to 0 and the newest entries will be added below the rest
of the entries. Keep this option at 1 and the guestbook will add the
newest entries at the top.

Option 7: $remote_mail
Many users of the guestbook have requested that a form letter be
automatically sent to the remote user when they fill in the guestbook.
Turning this option on will tell the script to automatically mail any
user who leaves an email address. You can specify the contents of the
mail message by editing the section of the script that sends mail to the
remote user. By default it sends a message that says, "Thank you for
adding to my guestbook." and then shows them their entry. If you should choose to turn this variable on, you will need to fill in the 2
variables that go along with it:
$recipient - Your email address so that the mailing program will know
who to mail the entry to.
$mailprog - The location of your sendmail program on your host machine.

Option 8: $allow_html
This option allows you to turn on or off the use of HTML tags by users
of your guestbook. Setting this variable to 1 allows users to embed html
tags such as <b> or <H1> or <a href=" "></a> into your html document.
Setting this variable to 0 will not allow them to use any html syntax in
their comments or any other field. You can still link to their comments
or any other field. You can still link to their email address by turning
$link_mail to 1.
There is also the ability for users to add their own URL and then their
name is referenced to their URL in the guestbook.html file. This helps
to eliminate the need for allow_html to be turned on, and lets users
point you to a spot that will tell you more about them. Several users of
the guestbook script have asked for this option. If you wish to disable
the option, simply delete the following line from your addguest.html file:
URL: <input type=text name=url size=50><br>
These are the rest of the important guestbook files found in your
Guestbook directory:
guestbook.html
This is the file that you will link to that will contain the Guestbook
Entries. You may want to edit the title and heading spaces and customize the look any way you desire. Do not delete the line <!--begin--> from this guestbook, or else the script will have no way of knowing where to begin the editing. The <!--begin--> line is the only necessary line in your guestbook.html file, but the link to the addguest.html file is also a good idea. :-)

3.2. Your Own CGI-SCRIPTS

 

CGI-SCRIPPS  are computer programs running on the webserver that can be invoked from a web page in the browser.  These programs adds
functionality to web pages that are not possible with just HTML.

CGI scripts need to be saved in ASCII format and uploaded to your
server's cgi-bin in ASCII or text format. This is very important.

HostAvenueT TM does not provide free support for CGI scripts which did not come installed on your account. So if you are not already familiar with CGI scripting, you may want to read a book on the subject or find places on the Internet with CGI scripting information. There are many good
resources for CGI scripts found on the web. The scripts at Matt's Script
Archive found at http://www.worldwidemart.com/scripts/ are very good.
Many of our scripts come from here. Another excellent resource is The
CGI Resource Index found at http://www.cgi-perl.com/ -- if you are not
an expert, look for scripts that are very well documented and come with
step-by-step instructions, or contact us for help or installation.


3.2.1. How do I run my own CGI program
 
a.) Put your CGI programs in the cgi-bin directory. When calling the programs from the web page, you must use the alias for the cgi-bin directory. The alias is "cgi-[yourdomain]". If your domain
is example.com, then the alias is cgi-example. Note that ".com" is not
included. So the action line from your form page would look like
action="/cgi-example/program".
b.) Put your CGI programs anywhere outside of the cgi-bin directory. In
this case, the program name must end in ".cgi".
 
 
3.2.2. Paths to Date, Mail, Perl, etc.
 
Here are your paths to the common server resources that CGI scripts
often require:
Sendmail:
/usr/sbin/sendmail
Perl5.003:
/usr/bin/perl
Perl5.004:
/usr/bin/perl5.004 (Full 5.004 lib support not available currently)
Date:
/bin/date
Java:
/usr/bin/java
Python:
/usr/bin/python
Domain path:
/www/[yourdomain]
 
(puts you in your web directory)
Cgi-bin path:
/www/[yourdomain]/cgi-bin
 
(puts you in your cgi-bin)
 
 
3.2.3. Setting Permissions

The following is a simple explanation of file permissions in Unix. To
list the access permissions of a file or directory, telnet to your
server, then: cd directoryname to change the directory until you are either in the directory above the file you are interested in, or above the directory you are checking.
Type: ls -l filename and you will see what the current permission settings are for that file, along with a bunch of other stuff.
Examples of using chmod:
 PEOPLE
 PERMISSIONS
 u = the file's user (you)
 r = read access
 g = the file's group
 x = execute access
 o = others
 w = write access
 a = the user, the group, and others
 
To change permissions for a file named filename.cgi, you need to chmod
the file (change mode). For example, when you type this:
chmod u=rwx,g=rx,o=rx filename.cgi
you've given:
read, execute, and write access to the user (that's you)
read and execute access to the group and
read and execute access to others
Some scripts will tell you to chmod 775 (for example). Doing the above
is the same thing as typing chmod 775. You can use either method with
our Unix servers. Let me explain:
When using the numeric system, the code for permissions is as follows:
r = 4 w = 2 x = 1 rwx = 7
The first 7 of our chmod775 tells Unix to change the user's permissions
to rxw (because r=4 + w=2 + x=1 adds up to 7. The second 7 applies to
the group, and the last number 5, refers to others (4+1=5).
When doing an ls -l on the file, telnet always shows the permissions
this way:
-rwxr-xr-x
Ignore the first dash, then break up the above into three groups of
letters. If there's a dash where a letter should be, it means that there
is no permission for those people.
Remember: the first 3 apply to user, the second 3 apply to group, and
the third 3 apply to others.
Some FTP clients support changing permissions in a more graphical way.
If you have Fetch for the Mac, you have an easy way to change
permissions. Go to the file you want to change the permissions on, and
highlight it. Under the Remote menu, select Change Permissions. A window will pop up showing the current permissions for the file you had
highlighted, as in Figure 3A below. Click on the boxes to change
permissions as needed.

Figure 3A


WS_FTP accomplishes the same task as above. Just highlight the file you
want to check, and right-click on it. A menu will pop up, then select
CHMOD. You will see the window below, as in Figure 3B.

Figure 3B

 

3.2.4. Troubleshooting CGI-bin Problems

Below are solutions to some of the more common CGI script problems, in
question and answer format.

When I activate my CGI program, I get back a page that says "Internal
Server Error. The server encountered an internal error or
misconfiguration and was unable to complete your request."
This is generally caused by a problem within the script. Log in via
Telnet and test your script in local mode to get a better idea of what
the problem is. To do this, go into the directory in which your script
is located, then execute the script. To execute the script, you can do
it by two ways:

1) Type "perl myscript.pl" (Perl being the language interpreter in this
case).
2) Or simply type "myscript.pl" alone, that will work if the first line
is well written to indicate the location of Perl.

The first one is useful to see if there's any error IN your script. The
second one is useful to test if your "calling line" (the first line of
the script) is okay, i.e. if you entered the right location of Perl.
I am being told "File Not Found," or "No Such File or Directory."
Upload your Perl or CGI script in ASCII mode, not binary mode.

When I test my Perl script in local mode (by Telnet), I have the
following error: "Literal @domain now requires backslash at myscript.pl
line 3, within string. Execution of myscript.pl aborted due to
compilation errors."
This is caused by a misinterpretation by Perl. You see, the "@" sign has
a special meaning in Perl; it identifies an array (a table of elements).
Since it cannot find the array named domain, it generates an error. You
should place a backslash (\) before the "@" symbol to tell Perl to see
it as a regular symbol, as in an email address.

I am getting the message "POST not implemented."
You are probably using the wrong reference for cgiemail. Use the
reference /cgi-bin/cgiemail/mail.txt. Another possibility is that you
are pointing to a cgi-bin script that you have not put in your cgi-bin
directory. In general, this message really means that the web server is
not recognizing the cgi-bin script you are calling as a program. It
thinks it is a regular text file.

It's saying I don't have permission to access / (1)
This error message means that you are missing your index.htm file. Note
that files that start with a "." are hidden files. To see them, type ls
-al. If you wish to FTP this file in, go to the home/[[yourdomain]]
directory.
It's saying I don't have permission to access/ (2)
Your cgi-script is probably set as world writeable. Our cgi security
mechanism prevents execution of such cgi-scripts. To ensure that the
permission setting for your cgi-script is correct issue following
command. "chmod 755 yourcgiscript " in the directory where your cgi-script is located.
Also the directory in which your script is located must be set to same
permission setting. Use same method as described just above.