This section includes or links to information on the following topics:

CGIEmail Instructions
FormMail Instructions
Links to CGI Resources
Internal Server Error Troubleshooter
HTML Perl Documentation (perldoc.com)

What is CGI?
CGI stands for “Common Gateway Interface”. CGI is the long-standing standard for passing information between a server and an application as part of HTTP protocol. CGI is a consistent way for information to be passed from the Web server to the application program and back again. The most common use of CGI is in scripting.

A CGI script is a program written with a scripting language such as PERL, Java or C++. Rather than being compiled into machine code, scripts are interpreted. They link on-screen forms with background databases. For example, when a user views a web page and inputs information into a form, a CGI program gathers that data and provides a response or sends the information elsewhere (as in E-Mail). Almost any time users are asked to input information on a web site, a CGI script is at work.

CGI scripts typically reside in the CGI-BIN. The “bin” part alludes to the binary executables that result from compiled or interpreted programs. It is a bit misleading because CGI’s are sometimes commonly called UNIX shell scripts or interpreted languages like PERL. On our servers, CGI scripts are not required to reside in the cgi-bin directory — they can run from anywhere within your www directory. However, in order to execute from a location outside of the cgi-bin directory, they must be named with the .cgi extension (as opposed to the .pl extension, for example.)

So then, what is PERL?
Now we’re getting somewhere. PERL, which stands for Practical Extraction Reporting Language, is one of the most popular programming languages for processing text used on web sites. PERL is an interpreted program, not a compiled one. This means that your programming is exclusively in text format, and is executed without the need for a compiler. (A compiler is a program that changes the high-level source code of a programming language such as C into the basic machine language a computer understands.)

A comparatively simple programming language (compared to C++ and other languages that are compiled), it is robust, flexible and serves the most popularly needed purposes.

Most of the installed scripts on your domain, as well as most of the common CGI scripts in use elsewhere, are programmed in PERL, so we will pay more attention to PERL than the other languages.

Support Notes
We cannot provide free technical support on the CGI scripts installed on your account. The free, preinstalled scripts that are included with your account will run “out-of-the-box” as installed. You’re free to make modifications as you wish, but if the modifications cause problems, the only solution we can offer is for you to delete the modified script and reinstall it from your control panel. In some cases, we may be able to offer paid support on an hourly or per-project basis. Contact our sales department for more information.

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. A popular resource is The Perl Archive, which lists nearly 4,000 Perl and CGI programs and offers informative articles and tutorials for the beginning to the advanced programmer.

View our list of related CGI/PERL links.

Configuring and Using FormMail

Configuring and Using FormMail

What is FormMail?

This script is one from Matt’s Script Archive which we have installed and preconfigured for your domain. 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 functional options, most of which can be specified through the form. This means you don’t need any programming knowledge, nor do you need multiple scripts for multiple forms. This also makes FormMail the perfect system wide solution for allowing users form-based user feedback capabilities without the risks of allowing freedom of CGI access.

Note: If you wish to use FormMail on a secure server please see the special instructions.

CLICK HERE for the script author’s formmail documentation.

How do I use it?

There is only one form field that you must have in your form, for FormMail to work correctly. This is the recipient field. IMPORTANT NOTE: The recipient field must specify an e-mail address from the domain that the form resides on (in other words, if your domain name is fred.com, the recipient value must specify a fred.com e-mail address — specifying an e-mail address from another domain will cause the form submission to fail.) 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, 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-bin/formmail.cgi”>
<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 the proper syntax for many of the fields you can use with FormMail.

Recipient Field

This form field allows you to specify to whom your form results will 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

The subject field will allow you to specify the subject that you wish to appear in the email that is sent to you after the 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

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, it is strongly suggested that you include this form. 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

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

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

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

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

This field allows you to choose the order you would like 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 email 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

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

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

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

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

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: Back to Main Page

Syntax:

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

Special Notes about Using FormMail.cgi with the secure server

If you are using formmail.cgi 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://machinename.safe-order.net/cgi-bin/formmail.cgi

Here’s an example of how the first parts of your form might look:

<FORM METHOD=POST ACTION=”https://machinename.safe-order.net/cgi-bin/formmail.cgi”>
<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 for it to work properly. You must use: https://machinename.safe-order.net/yourdomain/order.htm. If you call formmail.cgi through the secure server, you must also call the order form through the secure server. Otherwise, a “bad referrer” message will result.

Configuring and Using CGIEmail

Configuring and Using CGIEmail

What is CGIEmail?

CGIEmail is another form processing script, totally different than FormMail. It 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 location. 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.

How do I use it?

Cgiemail is usually in the cgi-bin directory of your server. You need to have an action in your order.htm file to call it. It should look like this:

<form method=post action=”http://www.yourdomain.com/cgi-bin/cgiemail/order.txt”>

Note: If you wish to use CGIEMAIL on a secure server please see the special instructions.

order.htm

Look for a file in your www directory called order.htm. This is our example form we put on your site that shows how a form should be configured to work with CGIEmail. Look at it in a browser, and download it to your hard drive using FTP so you can see how it works. If you’ve never dealt with HTML forms before, don’t worry, they’re easy to create and understand.

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 thename 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 may want to change the email address in the required-tofield, and likely the subject in the subject field. The first item tells CGIEmail what to show the user after successfully 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=60tells 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 email address.

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

By the way, you can name your HTML form anything you want to.

order.txt

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 file to show it what to send. (If you didn’t want flexibility you’d use a mailto link.) The program will read this file, perform substitutions, and pass it to the mail system. In our example, the mail file is named order.txt, but you can name it anything you want.

Make sure that you upload your mail file in ASCII mode. Failure to upload in ASCII mode will generate the message: “Server Error: The server encountered an internal error or misconfiguration and was unable to complete your request.” There is already an example order.txt document in the forms directory in your www directory ( http://yourdomain.com/forms/order.txt).

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 into 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 file 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.

CGIEmail does not report environmental variables like FormMail will, but other than that, it is an excellent program, allowing you more flexibility in the way you want your data returned by the form.

The CGIEMAIL User Guide

For a more detailed explanation of cgiemail’s capabilities and syntax, visit the cgiemail user guide published at MIT.

Calling CGIEmail Through the Secure Server

If you want to call your cgiemail form through the secure server, use the following ACTION tag:

<FORM METHOD=POST ACTION=”https://machine.safe-order.net/cgi-username/cgiemail/forms/order.txt”>

where machine is the name of the server on which your domain resides, and username is your domain name without the top-level domain extension (e.g., for hostingmanual.net, the username is hostingmanual.)

If you’re specifying a success page, the appropriate tag would be:

<INPUT TYPE=HIDDEN VALUE=”https://machine.safe-order.net/username/pagename.html name=”success”>

CGI & Perl Resources

CGI & Perl Resources

Introduction

These resources are provided to assist you in learning more about PERL programming. We do not take responsibility for the contents of these web sites. There are many more resources available to you. For more resources, you can check the search engines for CGI or PERL.

Web Sites – Learning

The Perl Archive’s Learning Center
Our own project, offers you lots of articles including non-programmer’s introduction to perl, program customizing and web site discussions.

Common Gateway Interface CGI documentation 
Introduction, primer for getting started, interface spec, tutorial for writing ErrorDocument. Examples of behavior and programs.

CGI Made Really Easy
Tutorial for writing CGI scripts to process Web forms. In English or German.

CGI Programming 101
A course intended for anyone who knows HTML but doesn’t know Perl or CGI programming.

Instantaneous Introduction to CGI Scripts and HTML Forms
Detailed explanation of CGI forms, how to use them and the mechanics behind how they work.

 

Web Sites – Downloadable Scripts

The Perl Archive’s Guide
Listing nearly 4,000 cgi and perl programs. If you can’t find it here — it hasn’t been made yet.

Site Interactive
Some very good scripts, some shareware, some excellent “non-free” scripts. It’s verified… CGI Script Center’s scripts are compatible with our servers.

nms Project: Web Scripts Written by Experts
nms is a set of CGI scripts that are intended as drop-in replacments for the scripts at Matt’s Script Archive.

 

 

Books

Please note that the listing of these books does not imply endorsement of any kind. We realize that there are many, many, many books on CGI available and just wanted to help you weed out some of the “better” ones (in our opinion, of course).

CGI for Commerce : A complete Web-Based Selling Solution – A complete solution for selling products over the Internet, Building an Online Store provides pre-written scripts, a complete section on dealing with security on the Internet, and includes Perl scripts, SQL databases, JavaScript and VBScript code, as well as finished Web pages. The CD contains multiple shopping cart examples in Perl 4 and 5, e-mail libraries, and HTTP libraries.

Webmaster Note: A very good and easy to understand book. Gets you “up and running” fairly quickly, as you learn the basics.

Learning Perl – Ideal for system administrators, programmers, and anyone else wanting a down-to-earth introduction to this useful language. Written by a Perl trainer, its aim is to make a competent, hands-on Perl programmer out of the reader as quickly as possible. The book takes a tutorial approach and includes hundreds of short code examples, along with some lengthy ones.

The Cgi/Perl Cookbook – Souping up a Web site has never been easier. This book/CD-ROM set offers a complete introduction to CGI programming with Perl plus a collection of sophisticated CGI programs that readers can use to add popular functions to their Web sites, including search engines, passwords, product databases, a shopping cart, custom forms, animated images, and more. Readers will learn how to incorporate the scripts into their own Web sites, how to customize them for their own goals, and how to use a host of other CGI and Perl programming tricks to create unique and interactive Web sites. CD-ROM includes all the CGI programs from the book–both code and ready-to-run versions; a full copy of Matt’s Script Archive,” a collection of the best scripts from across the Web.

Perl 5 Interactive Course : Certified Edition – The clear, step-by-step instructions in Perl 5 Interactive Course, Certified Edition, teach you how to develop sophisticated Net applications and Web sites using the flexible power of Perl. From simple tasks like writing loops and opening files to advanced topics such as networking, generating graphics, and linking Perl and C, these hands-on lessons show you how it’s done. Throw your Internet connection into the mix and you’ll have free access to the eZone, the innovative Web-based learning center from Waite Group Press. You’ll get expert help from the pros, interactive quizzes for immediate feedback, dedicated discussion groups for interaction with other students, certification, and even optional continuing education units (for a nominal fee). This isn’t just a book; it’s a Web-based learning center.

Webmaster Note: An excellent book from start to finish. Purchase this book only if you’re 100% dedicated to learning PERL and are faily good with math. You’ll walk away with more than you’ll ever need about PERL. You will receive a certificate, which can be converted to college credits upon successful completion within 1 year. The book is combined with a support web site, a web-based “mentor” and a support majordomo list for maximum exposure to programming and your peers.

Effective Perl Programming: Writing Better Programs With Perl – explains idiomatic Perl, covering the latest release (5.0), and includes information and useful examples about the structure, functions, and latest capabilities of the language, such as self-documenting object-oriented modules.

Webmaster Note: A great book if you’re already pretty advanced. Beginners may be “lost”, until more is learned.

Perl: The Programmer’s Companion – With the increase in Web-based technology, Perl has become the language of choice for creating CGI applications, an essential process for creating large Web pages. This book introduces the latest version, Perl5, to programmers, illustrating the language’s strengths and weaknesses. This title shows how to write sophisticated Perl scripts and covers all of the new benefits of Perl5.

Perl Cookbook – Is a comprehensive collection of problems, solutions, and practical examples for anyone programming in Perl. Topics range from beginner questions to techniques that even the most experienced Perl programmers can learn from. More than just a collection of tips and tricks, the Perl Cookbook is the long-awaited companion volume to Programming Perl, filled with previously unpublished Perl arcana.

Perl 5 by Example – This book is similar to all other By Example books in that it provides a jump-start to the Perl language for both new programmers and experienced programmers alike. It concentrates heavily on showing readers how to program similar to existing programs that are cited throughout the book as examples.

Perl 5 Complete (McGraw-Hill Complete Series) – Perl is the dominant scripting language for the World Wide Web. Scripting languages build interactivity into a Website–like shopping carts, contests, forms, etc. This book is the complete reference to existing Perl technologies and to the new Perl5 compiler provided on the CD-ROM.

Perl 5 for Dummies – Perl for Dummies introduces the reader to the power and flexibility available for UNIX system management through the scripting language Perl. The book covers the primary advantages of and applications suited to the Perl language. Although Perl for Dummies details the language syntax for the beginner, it also lets more experienced readers apply their knowledge of similar languages.

Webmaster Note: Don’t let the title fool you. It’s an utterly fantastic reference for beginners and experts alike to keep next to you while undertaking any PERL project.

Perl 5 Pocket Reference – This is a standard, quick-reference guide for the Perl programming language. The second edition, updated to cover the latest Perl version, provides a complete overview of the language, from variables to input and output, from flow control to regular expressions, from functions to document formats–all packed into a convenient, carry-around booklet.

Perl 5 Quick Reference – This book is an excellent desktop reference for all Perl programmers, but will predominantly be used by the more advanced users who are already familiar with the syntax. A series of jump-tables will refer the user to specific sections of the book by page number.

Perl Cgi Programming : No Experience Required – Experienced HTML authors, Webmaster, and Intranet programmers will find this book one of the fastest ways to learn CGI programming. Topics include catalog, search engine, order forms, database referencing, and user feedback scripts. Real world examples emphasize creating forms and user-driven, interactive Web sites.