AllWebCo Manual

4.1) OVERVIEW

• 4.1.1) What are cgi-bin scripts?
• 4.1.2) Where should I put cgi-bin scripts?
• 4.1.3) What is the path of date, mail, perl, ...?
• 4.1.4) Charges

4.2) FEEDBACK FORMS, GUESTBOOK & SEARCH

• 4.2.1) add.html
• 4.2.2) mail.txt
• 4.2.3) How to use cgiemail and formmail
• 4.2.4) How to use the Guestbook
• 4.2.5) How to use Search.cgi

4.3) IMAGEMAPS

4.4) HTML PAGE COUNTERS

• 4.4.1) index.cgi
• 4.4.2) Using index.cgi
• 4.4.3) Charges

4.5) READY TO RUN SCRIPTS & ALL SITE COUNTERS

• 4.5.1) Site Counter using SSI
• 4.5.2) WWWBoard
• 4.5.3) Secure and Unsecure order form Samples
• 4.5.4) Password Protected directory
• 4.5.5) Database and Search engine business accounts Only

4.6) TROUBLESHOOTING

4.1) OVERVIEW

4.1.1) What are cgi-bin scripts?

"cgi" stands for "common gateway interface", a fancy name meaning computer programs running on the web server 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 server, 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.

4.1.2) Where should I put cgi-bin scripts?

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

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

4.1.3) What is the path of date, mail, perl ...?

To find the path of the program date, type which date. Do this for any program that you need your cgi-bin script to access.

I see lots of perls, which one should I use?

They should all be the same. /usr/local/bin/perl should work nicely.

4.1.4) Charges

AllWebCo can create and design scripts for you. For very simple ones, we normally charge $60/script. We can provide a quote on more complicated ones.We Provide the following standardized scripts for free: feedback forms, imagemaps, page counter scripts.

4.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 URI 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.

4.2.1) 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 server 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 server. 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 ...

4.2.2) Mail.txt

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

Failure to upload mail.txt in ASCII mode will generate the message:

Server Error

The server encountered an internal error or misconfiguration and was unable
to complete your request.

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. When called from AllWebCo.com, 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. If you have a domain name, we suggest that you explicitly put it in the action attribute, because the behavior is different: cgiemail does know what your domain is if called for your domain.

Fred.com might want to put the mail.txt file in his www directory. His form would then start off with

<form method=post action="http://www.fred.com/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.

4.2.3) How to use cgiemail

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 'thelist' 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.) Remember to change both the form (.html) and template (mail.txt).
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.

Formmail.cgi

Formmail is a program written in the Perl language that takes the contents of
fill-in boxes on a form and emails them to a specified destination. In addition
it is also capable of generating its own Confirmation page.

Setting Up the FormMail Script:
===============================

The FormMail.pl script does not have to be extensively configured to get
it to work. There are only two variables in the perl file which you will
need to define along with changing the top line of your script to match
the location of you Perl interpreter.

Necessary Form Fields:
======================

There is only one form field that you must have in your form, for
FormMail to work correctly. This is the recipient field.

Field: recipient
=====================

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 e-mail
address.

Syntax:

<input type=hidden name="recipient" value="email@your.host.xxx">

-----------------------------------------------------------------------------

Optional Form Fields:

=====================


Field: subject

Description: The subject field will allow you to specify the subject that 
you wish to appear in the e-mail 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">

-----------------------------------------------------------------------------

Field: email

Description: This form field will allow the user to specify their return 
e-mail 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.

Syntax:

<input type=text name="email">

-----------------------------------------------------------------------------

Field: realname

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">

-----------------------------------------------------------------------------

Field: redirect

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://your.address/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">

-----------------------------------------------------------------------------

Field: required

Version Added: 1.3

Description: You can now require for 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.  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.

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 a syntax like:

<input type=hidden name="required" value="email,phone">


-----------------------------------------------------------------------------

Field: env_report

Version Added: 1.3

Description: Allows you to have Environment variables included in the 
e-mail 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 a request.

REMOTE_ADDR     - Sends the IP address of the remote host making the request.

REMOTE_USER     - If server supports authentication and script is 

                  protected, this is the username they have authenticated as.

                  *This is not usually set.*

REMOTE_IDENT    - If HTTP server supports RFC 931 identification, then 

                  this variable will be set to the remote user name 

                  retrieved from the server. *This is not usually set.*

HTTP_USER_AGENT - The browser the client is using to send the request.  

                  General format: software/version library/version


There are others, but these are a few of the most useful.

Syntax:

If you wanted to find the remote host and browser sending the request, 
you would put the following into your form:

<input type=hidden name="env_report" value="REMOTE_HOST,HTTP_USER_AGENT">

-----------------------------------------------------------------------------

Field: sort

Version Added: 1.4

Description: This field allows you to choose the order in which you wish 
for your variables to appear in the e-mail 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 sends the information to the script (which isn't always the 
exact same order 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 e-mail 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...">

-----------------------------------------------------------------------------

Field: print_config

Version Added: 1.5

Description: print_config allows you to specify which of the config 
variables you would like to have printed in your e-mail message.  By 
deafult, no config fields are printed to your e-mail.  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 shoul dbe 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">

----------------------------------------------------------------------------

Field: title

Version Added: 1.3

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">

-----------------------------------------------------------------------------

Field: return_link_url

Version Added: 1.3

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://your.host.xxx/main.html">

-----------------------------------------------------------------------------

Field: return_link_title

Version Added: 1.3

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:


<a href="return_link_url">return_link_title


Syntax:

<input type=hidden name="return_link_title" value="Back to Main Page">


-----------------------------------------------------------------------------

Field: background

Version Added: 1.3

Description: This form field allow you to specify a background image 
that will appear if you do not have the redirect field set.  This image 
will appear as the background to the form results page.

Syntax:

<input type=hidden name="background" value="http://your.host.xxx/image.gif">

-----------------------------------------------------------------------------

Field: bgcolor

Version Added: 1.3

Description:  This form field allow you to specify a bgcolor for the 
form results page in much the way you specify a background image.  This 
field should not be set if the redirect field is.

Syntax:

For a background color of White:
<input type=hidden name="bgcolor" value="#FFFFFF">

-----------------------------------------------------------------------------

Field: text_color

Version Added: 1.3

Description: This field works in the same way as bgcolor, except that it 
will change the color of your text.

Syntax:

For a text color of Black:
<input type=hidden name="text_color" value="#000000">

-----------------------------------------------------------------------------

Field: link_color

Version Added: 1.3

Description: Changes the color of links on the resulting page.  Works in 
the same way as text_color.  Should not be defined if redirect is.

Syntax:

For a link color of Red:
<input type=hidden name="link_color" value="#FF0000">

-----------------------------------------------------------------------------

Field: vlink_color

Version Added: 1.3

Description: Changes the color of visited links on the resulting page.  
Works exactly the same as link_color.  Should not be set if redirect is.

Syntax:

For a visited link color of Blue:
<input type=hidden name="vlink_color" value="#0000FF">

-----------------------------------------------------------------------------

Field: alink_color

Version Added: 1.4

Description: Changes the color of active links on the resulting page. 
Works exactly the same as link_color.  Should not be set if redirect is.

Syntax:

For a visited link color of Blue:
<input type=hidden name="alink_color" value="#0000FF">

4.2.4) How to use Guestbook

http://yourdomain.com/Guestbook/guestbook.html

4.2.5) How to use Search.cgi
Search will look at all your html pages for words you enter, and return all pages on a list with links. This program is completly configured and ready to run, just access it with the following URL

http://yourdomain.com/cgi-yourdomain/search.cgi

4.3) IMAGEMAPS

'Imagemap' refers to an interaction between a user's browser and the WWW server which allows clicking on an image to select hyperlinks. (Other implementations have a seperate /cgi-bin/imagemap program. Our server 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://oceania.org/weblinks.html
poly http://oceania.org/weblinks.html#A  23,14  44,2  66,14  66,39  45,51  23,39
poly http://oceania.org/weblinks.html#A  67,14  88,2 110,14 110,39  89,51  67,39
poly http://oceania.org/weblinks.html#C 111,14 132,2 154,14 154,39 133,51 111,39

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.4) HTML PAGE COUNTERS

4.4.1) index.cgi

index.cgi, will be found in your cgi-bin. which you will use to update a counter on your home page. Put this file in your main web directory, you don't need to put it in a special cgi-bin directory. It must, however, be called index.cgi to have the desired effect.

Upload this file by using rz -a with telnet or in ASCII mode if you are using ftp. Otherwise you may run into unusual problems.

Because it is a program, the file must be executable to work. If you are telnetting in, use chmod +x index.cgi to make it so. If you wish to only use FTP, you'll have to type chmod 755 index.cgi after uploading it to have the same effect.

4.4.2) Using index.cgi

Type chmod +x index.cgi to activate index.cgi. Then create a file named .count with one line that contains the number 0. Then type chmod o+w .count to allow the counter to be updated. (chmod 666 .count if you're stuck with FTP.) The counter and index.cgi are in your main page in this example.

When http://your-domain.com is referenced at the browser, instead of delivering the file index.html as normally expected, the program index.cgi is run instead. index.cgi reads the .count file, increments the number in that file by one, and writes the file back on disk. Then it reads in the index.html file, finds the string "#COUNT" imbedded somewhere in it, changes "#COUNT" to 1 + whatever value if found in .count, and sends the modified index.html to the browser.

To create a counter on a page other than your home page, change the source from index.html to the page that you wish to update. You would want to make another copy of index.cgi as well. So for example, if you wished to count a page called orders.html, you would change the source from index.html to orders.html, change the name from index.cgi to orders.cgi and then call this page from other pages by the name orders.cgi. Change two things within orders.cgi: find the string 'index.html' and change it to 'orders.html', and find the string '.count' and change it to '.countorders'. Both are right near the top of the program. Then make a file .countorders instead of .count, but otherwise as directed above.

4.4.3) Charges

We will charge $25 per home page counter that we install. Of course, you can easily install your own.

4.5) COMPLETE WEB SITE COUNTERS

4.5.1)Site Counter using SSI

Very simple to use, first the page which you would like to count must have the extension .shtml or .sht rather than .htm or .html
put the following on the page where you want the count file to appear.
<!--#exec cgi="/cgi-yourdomain/counters/counter.cgi"-->
For Example if your domain is fred.com the call would be
<!--#exec cgi="/cgi-fred/counters/counter.cgi"-->
That all there is to it, this will create a count file for each page the call is placed on, it will just show up as a number when looking at it from a web page.

4.5.2) WWWBoard

The World Wide web Board is already to run, you can call it from a page with the following URL: http://yourdomain.com/bbs/

4.5.3) Secure and Unsecure Orderform calls

When we setup your account we provide a sample secure and unsecure order form. These can be easily modified or changed to suite your individual or business needs. When calling a non secure order form there is nothing different, you would use your standard URL: http://yourdomain.com/order.html assuming the order form is in your main directory. To call a form or a document as secure you will be using AllWebCo's registration key. What this means is the page must be called thru our secure server, so the URL that points to this must be as follows: https//allwebco.com/domainname/secureorder.html. You will have to keep both secure and non-secure order for ms on your domain, you will find that the calls for each are different because the directory hierchy changes for the secure form, graphics and cgi scripts will have to be called in two different fashions for each form. If you follow the samples supplied for formaction and redirection, you should have n o problems using this successfully.

4.5.4) Password Protected Web directory

Placed in your WWW directory, you will find a sub directory called secure. This has been setup with the password file in place, and it cannot be entered from the web without first being prompted for a login and password.
You will need a brief knowledge of Telnet in order to build the login file for this directory, the steps are below.

1. Login to your domain via telnet.
   
2. At prompt type pass, this is a script we created to make adding to the file easy
   
3. Follow the prompts. enter login and then passwd desired twice.
4. You may enter as many logins as you like, you may also go back and add when ever you wish.
   
5. Just hit enter, when prompted for login to escape program.

4.5.5) Database and search engine

The database program is composed of 5 essential files database.cfg, database, post.htm, search.htm and output.html

database.cfg - this is the configuration file for your database.

• You need to make sure your unix permissions are set to chmod 666 for this file to work properly
  
• The first line is the location of the database, which has the default value of our test database.
  
• The second line is what page that it should return to after posting to database, the default value is to return to the post page for another entry.
  
• The third line is where you will start listing ay fields you want to have posted to the database.
  

These become your input fields and they must be associated with the input statements on your posting page for each of the above, you should have a matching input statement that looks like the following on your post page:

<input = text name = "name" size = "25" > <input = text name = name = "address" size = "25">

Database - This is nothing more than the actual data being stored after it is posted from your posting page.

Post.htm - This page is used to write to the database from a webpage. You should have an input statement for each field used in the database .cfg file. You may also use Query boxes, + Radio buttons. The formation for this page should be as follows:

<form method post action = "http://your domain.com/cgi-bin/database.cgi">

For better understanding look at the sample files in the database directory on you domain.

Email - You may activate this feature by adding the following.
<input type="hidden" name="email" value="youremailaddress"> When active each time someone posts to the database you will receive a email of the content

Search.htm - this is the page that reads the actual database file based on the criteria you would like to search. A good example of this page at work would be

http://cyberlands.com/mall/ this utilizes many of the features this program offers.

The form action for this page should be as follows:

<form method = post action = "http://your domain.com/cgi-bin/dsearch.cgi"> use the preconfigured example as a template that is in the database directory of your domain.

There are several ways to setup searches for your database.

1. Click on names (see http://cyberlands.com/mall/.)

This will allow a nice interface for your customer or client, that eliminates the need for a submit button

Use the following call:
EX:

The items before the ? mark call the script, this should always be the same. The first item after the ? mark is the word you are using for the search, then you will notice a & sign the listing after the & sign is the location of the database file (it's directory) in the above cyberlands/mall/ in the default sample set your domain, it would be domainname/database/:

2. The other way to do a search page is through checkboxes, radio button, query lists, and straight type in text. You may search by as many different mediums as you like. Look at http://winedine.com/nycsrch.htm

For an example of different criteria being used, there are only two variable names you will use in your search page. Keywords and Keywords-predefined.

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

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

$mailaddress = "joe@schmoe.com";

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